@tapicker/bridge 1.0.0

package/src/bridge/control.ts

@@ -0,0 +1,281 @@
+import { createHash } from 'node:crypto'
+import { chmod, mkdir, unlink } from 'node:fs/promises'
+import { createConnection, createServer } from 'node:net'
+import type { Server, Socket } from 'node:net'
+import { join, resolve } from 'node:path'
+import { BridgeError, toBridgeError } from '../errors.js'
+
+export type BridgeControlAction = 'code.get' | 'code.refresh' | 'extensions.list' | 'bridge.stop'
+
+const CONTROL_ACTIONS = new Set<BridgeControlAction>(['code.get', 'code.refresh', 'extensions.list', 'bridge.stop'])
+const MAX_CONTROL_MESSAGE_BYTES = 4096
+
+export function getBridgeControlPath(dataDir: string) {
+  const normalizedDataDir = resolve(dataDir)
+  if (process.platform === 'win32') {
+    const suffix = createHash('sha256').update(normalizedDataDir.toLowerCase()).digest('hex').slice(0, 24)
+    return `\\\\.\\pipe\\tapicker-bridge-${suffix}`
+  }
+  return join(normalizedDataDir, 'bridge.sock')
+}
+
+export async function startBridgeControlServer(
+  dataDir: string,
+  handle: (action: BridgeControlAction) => Promise<unknown>,
+) {
+  await mkdir(dataDir, { recursive: true, mode: 0o700 })
+  const endpoint = getBridgeControlPath(dataDir)
+  const server = createServer((socket) => handleControlSocket(socket, handle))
+
+  try {
+    await listenControlServer(server, endpoint)
+    if (process.platform !== 'win32') {
+      await chmod(endpoint, 0o600)
+    }
+  } catch (error) {
+    await closeServer(server)
+    throw error
+  }
+
+  return {
+    async close() {
+      await closeServer(server)
+      if (process.platform !== 'win32') {
+        await unlink(endpoint).catch((error) => {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+        })
+      }
+    },
+  }
+}
+
+export async function sendBridgeControlRequest<T>(dataDir: string, action: BridgeControlAction): Promise<T> {
+  const endpoint = getBridgeControlPath(dataDir)
+
+  return new Promise<T>((resolveResponse, rejectResponse) => {
+    const socket = createConnection(endpoint)
+    let buffer = ''
+    let settled = false
+
+    const finish = (callback: () => void) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timeout)
+      socket.destroy()
+      callback()
+    }
+
+    const timeout = setTimeout(() => {
+      finish(() =>
+        rejectResponse(
+          new BridgeError('BridgeControlTimeout', 'Timed out communicating with Tapicker Bridge', { status: 504 }),
+        ),
+      )
+    }, 3000)
+
+    socket.setEncoding('utf8')
+    socket.once('connect', () => socket.write(`${JSON.stringify({ action })}\n`))
+    socket.on('data', (chunk: string) => {
+      buffer += chunk
+      if (Buffer.byteLength(buffer) > MAX_CONTROL_MESSAGE_BYTES) {
+        finish(() =>
+          rejectResponse(new BridgeError('InvalidBridgeControlResponse', 'Bridge control response is too large')),
+        )
+        return
+      }
+
+      const newline = buffer.indexOf('\n')
+      if (newline < 0) return
+
+      let response: unknown
+      try {
+        response = JSON.parse(buffer.slice(0, newline))
+      } catch (cause) {
+        finish(() =>
+          rejectResponse(
+            new BridgeError('InvalidBridgeControlResponse', 'Bridge returned an invalid control response', {
+              status: 502,
+              cause,
+            }),
+          ),
+        )
+        return
+      }
+
+      if (!response || typeof response !== 'object') {
+        finish(() =>
+          rejectResponse(
+            new BridgeError('InvalidBridgeControlResponse', 'Bridge returned an invalid control response', {
+              status: 502,
+            }),
+          ),
+        )
+        return
+      }
+
+      const result = response as {
+        ok?: unknown
+        data?: unknown
+        error?: { code?: unknown; message?: unknown; status?: unknown }
+      }
+      if (result.ok === true) {
+        finish(() => resolveResponse(result.data as T))
+        return
+      }
+
+      const error = result.error
+      finish(() =>
+        rejectResponse(
+          new BridgeError(
+            typeof error?.code === 'string' ? error.code : 'BridgeControlFailed',
+            typeof error?.message === 'string' ? error.message : 'Bridge control request failed',
+            { status: typeof error?.status === 'number' ? error.status : 500 },
+          ),
+        ),
+      )
+    })
+    socket.once('error', (cause) => {
+      const code = (cause as NodeJS.ErrnoException).code
+      const isUnavailable = code === 'ENOENT' || code === 'ECONNREFUSED' || code === 'EINVAL'
+      finish(() =>
+        rejectResponse(
+          new BridgeError(
+            isUnavailable ? 'BridgeControlUnavailable' : 'BridgeControlFailed',
+            isUnavailable
+              ? 'No Tapicker Bridge control service is available'
+              : 'Could not communicate with Tapicker Bridge',
+            { status: isUnavailable ? 503 : 500, cause },
+          ),
+        ),
+      )
+    })
+    socket.once('end', () => {
+      if (!settled) {
+        finish(() =>
+          rejectResponse(
+            new BridgeError('InvalidBridgeControlResponse', 'Bridge closed the control connection without a response', {
+              status: 502,
+            }),
+          ),
+        )
+      }
+    })
+  })
+}
+
+function handleControlSocket(socket: Socket, handle: (action: BridgeControlAction) => Promise<unknown>) {
+  let buffer = ''
+  socket.setEncoding('utf8')
+  socket.setTimeout(5000, () => socket.destroy())
+  socket.on('data', (chunk: string) => {
+    buffer += chunk
+    if (Buffer.byteLength(buffer) > MAX_CONTROL_MESSAGE_BYTES) {
+      socket.destroy()
+      return
+    }
+
+    const newline = buffer.indexOf('\n')
+    if (newline < 0) return
+
+    socket.removeAllListeners('data')
+    let action: unknown
+    try {
+      const message = JSON.parse(buffer.slice(0, newline)) as { action?: unknown }
+      action = message?.action
+    } catch (cause) {
+      sendControlError(
+        socket,
+        new BridgeError('InvalidBridgeControlRequest', 'Control request is not valid JSON', { status: 400, cause }),
+      )
+      return
+    }
+
+    if (typeof action !== 'string' || !CONTROL_ACTIONS.has(action as BridgeControlAction)) {
+      sendControlError(
+        socket,
+        new BridgeError('InvalidBridgeControlRequest', 'Unsupported Bridge control action', { status: 400 }),
+      )
+      return
+    }
+
+    void handle(action as BridgeControlAction)
+      .then((data) => socket.end(`${JSON.stringify({ ok: true, data })}\n`))
+      .catch((error) => sendControlError(socket, error))
+  })
+}
+
+function sendControlError(socket: Socket, error: unknown) {
+  const bridgeError = toBridgeError(error)
+  socket.end(
+    `${JSON.stringify({
+      ok: false,
+      error: {
+        code: bridgeError.code,
+        message: bridgeError.message,
+        status: bridgeError.status,
+      },
+    })}\n`,
+  )
+}
+
+function listenControlServer(server: Server, endpoint: string): Promise<void> {
+  return listen(server, endpoint).catch(async (error) => {
+    if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw error
+    if (await canConnect(endpoint)) {
+      throw new BridgeError(
+        'BridgeControlInUse',
+        'A Tapicker Bridge control service is already using this data directory',
+        {
+          status: 409,
+          cause: error,
+        },
+      )
+    }
+
+    if (process.platform === 'win32') throw error
+    await unlink(endpoint).catch((unlinkError) => {
+      if ((unlinkError as NodeJS.ErrnoException).code !== 'ENOENT') throw unlinkError
+    })
+    await listen(server, endpoint)
+  })
+}
+
+function listen(server: Server, endpoint: string) {
+  return new Promise<void>((resolveListen, rejectListen) => {
+    const onError = (error: Error) => {
+      server.off('listening', onListening)
+      rejectListen(error)
+    }
+    const onListening = () => {
+      server.off('error', onError)
+      resolveListen()
+    }
+    server.once('error', onError)
+    server.once('listening', onListening)
+    server.listen(endpoint)
+  })
+}
+
+function canConnect(endpoint: string) {
+  return new Promise<boolean>((resolveProbe) => {
+    const socket = createConnection(endpoint)
+    const timeout = setTimeout(() => {
+      socket.destroy()
+      resolveProbe(false)
+    }, 300)
+    socket.once('connect', () => {
+      clearTimeout(timeout)
+      socket.end()
+      resolveProbe(true)
+    })
+    socket.once('error', () => {
+      clearTimeout(timeout)
+      resolveProbe(false)
+    })
+  })
+}
+
+function closeServer(server: Server) {
+  if (!server.listening) return Promise.resolve()
+  return new Promise<void>((resolveClose) => server.close(() => resolveClose()))
+}

package/src/bridge/daemon.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { z } from 'zod'
+import { BridgeError } from '../errors.js'
+
+const BridgeDaemonStateSchema = z
+  .object({
+    pid: z.number().int().positive(),
+    bridgeId: z.uuid(),
+    httpUrl: z.url(),
+    startedAt: z.number().int().positive(),
+  })
+  .strict()
+
+export type BridgeDaemonState = z.infer<typeof BridgeDaemonStateSchema>
+
+export function getBridgeDaemonStatePath(dataDir: string) {
+  return join(dataDir, 'bridge.pid')
+}
+
+export function getBridgeDaemonLogPath(dataDir: string) {
+  return join(dataDir, 'bridge.log')
+}
+
+export async function readBridgeDaemonState(dataDir: string): Promise<BridgeDaemonState | undefined> {
+  const filePath = getBridgeDaemonStatePath(dataDir)
+  let content: string
+
+  try {
+    content = await readFile(filePath, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    throw error
+  }
+
+  let value: unknown
+  try {
+    value = JSON.parse(content)
+  } catch (cause) {
+    throw new BridgeError('InvalidDaemonState', 'Saved Bridge process state is not valid JSON', {
+      status: 500,
+      cause,
+    })
+  }
+
+  const parsed = BridgeDaemonStateSchema.safeParse(value)
+  if (!parsed.success) {
+    throw new BridgeError('InvalidDaemonState', 'Saved Bridge process state has an unsupported format', {
+      status: 500,
+      details: parsed.error.issues,
+    })
+  }
+
+  return parsed.data
+}
+
+export async function writeBridgeDaemonState(dataDir: string, state: BridgeDaemonState) {
+  const filePath = getBridgeDaemonStatePath(dataDir)
+  const directory = dirname(filePath)
+  await mkdir(directory, { recursive: true, mode: 0o700 })
+
+  const temporaryPath = join(directory, `.bridge-${process.pid}-${randomUUID()}.tmp`)
+  const content = JSON.stringify(state, null, 2)
+  let file: Awaited<ReturnType<typeof open>> | undefined
+
+  try {
+    file = await open(temporaryPath, 'wx', 0o600)
+    await file.writeFile(content, 'utf8')
+    await file.sync()
+    await file.close()
+    file = undefined
+    await rename(temporaryPath, filePath)
+  } catch (error) {
+    await file?.close().catch(() => undefined)
+    await unlink(temporaryPath).catch(() => undefined)
+    throw error
+  }
+}
+
+export async function removeBridgeDaemonState(dataDir: string, expectedPid: number) {
+  const state = await readBridgeDaemonState(dataDir)
+  if (state?.pid !== expectedPid) return
+
+  try {
+    await unlink(getBridgeDaemonStatePath(dataDir))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+  }
+}
+
+export function isProcessRunning(pid: number) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code
+    if (code === 'ESRCH') return false
+    if (code === 'EPERM') return true
+    throw error
+  }
+}

package/src/bridge/extension-session.ts

@@ -0,0 +1,286 @@
+import { EventEmitter } from 'node:events'
+import type { WebSocket } from 'ws'
+import { DEFAULT_REQUEST_TIMEOUT, PROTOCOL_VERSION } from '../constants.js'
+import { BridgeError, safeError, safeSuccess } from '../errors.js'
+import {
+  BridgeHelloDataSchema,
+  BridgePairDataSchema,
+  ExtensionHelloInputSchema,
+  ExtensionPairInputSchema,
+  SafeResultSchema,
+  createEnvelope,
+  parseEnvelope,
+} from '../protocol/schema.js'
+import type { ExtensionHelloInput, ExtensionPairInput, MessageEnvelope } from '../protocol/schema.js'
+
+export type ExtensionSessionStatus = {
+  connected: boolean
+  ready: boolean
+  pairingRequired?: boolean
+  clientId?: string
+  clientName?: string
+  capabilities: string[]
+}
+
+export type ExtensionSessionOptions = {
+  bridgeVersion: string
+  protocolVersion: number
+  capabilities: string[]
+  remoteAddress: string
+  verifyCredential: (clientId: string, credential: string) => boolean
+  pair: (input: ExtensionPairInput, remoteAddress: string) => Promise<string>
+}
+
+type PendingRequest = {
+  type: string
+  timer: ReturnType<typeof setTimeout>
+  resolve: (value: unknown) => void
+  reject: (error: unknown) => void
+}
+
+export class ExtensionSession extends EventEmitter {
+  private ready = false
+  private pairingRequired = false
+  private clientId: string | undefined
+  private clientName: string | undefined
+  private capabilities: string[] = []
+  private pendingRequests = new Map<string, PendingRequest>()
+
+  constructor(
+    private readonly socket: WebSocket,
+    private readonly options: ExtensionSessionOptions,
+  ) {
+    super()
+  }
+
+  start() {
+    this.socket.on('message', (data) => void this.handleMessage(data).catch((error) => this.reportError(error)))
+    this.socket.on('error', (error) => this.reportError(error))
+    this.socket.on('close', (code, reason) => {
+      this.rejectPending(new BridgeError('ExtensionDisconnected', 'Tapicker Extension disconnected', { status: 503 }))
+      this.emit('close', { code, reason: reason.toString() })
+    })
+  }
+
+  getStatus(): ExtensionSessionStatus {
+    return {
+      connected: this.socket.readyState === this.socket.OPEN,
+      ready: this.ready,
+      pairingRequired: this.pairingRequired,
+      clientId: this.clientId,
+      clientName: this.clientName,
+      capabilities: this.ready ? this.capabilities : [],
+    }
+  }
+
+  request<T>(type: string, data: unknown, timeout = DEFAULT_REQUEST_TIMEOUT): Promise<T> {
+    if (!this.ready || this.socket.readyState !== this.socket.OPEN) {
+      return Promise.reject(
+        new BridgeError('ExtensionUnavailable', 'No paired Tapicker Extension is connected', { status: 503 }),
+      )
+    }
+
+    const envelope = createEnvelope(type, data)
+    const responseType = `${type}:res`
+
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(envelope.id)
+        reject(
+          new BridgeError('ExtensionRequestTimeout', `Extension did not respond to ${type}`, {
+            status: 504,
+            details: { timeout },
+          }),
+        )
+      }, timeout)
+
+      this.pendingRequests.set(envelope.id, {
+        type: responseType,
+        timer,
+        resolve: (value) => resolve(value as T),
+        reject,
+      })
+
+      try {
+        this.send(envelope)
+      } catch (error) {
+        clearTimeout(timer)
+        this.pendingRequests.delete(envelope.id)
+        reject(error)
+      }
+    })
+  }
+
+  close(code = 1000, reason = 'Bridge session closed') {
+    if (this.socket.readyState === this.socket.OPEN || this.socket.readyState === this.socket.CONNECTING) {
+      this.socket.close(code, reason)
+    }
+  }
+
+  private async handleMessage(raw: unknown) {
+    const parsed = parseEnvelope(raw)
+    if (!parsed.success) {
+      this.reportError(parsed.error)
+      return
+    }
+
+    const message = parsed.data
+    if (message.type === 'pong') return
+
+    const pending = this.pendingRequests.get(message.id)
+    if (pending && pending.type === message.type) {
+      this.pendingRequests.delete(message.id)
+      clearTimeout(pending.timer)
+      const result = SafeResultSchema.safeParse(message.data)
+      if (!result.success) {
+        pending.reject(
+          new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid response', { status: 502 }),
+        )
+      } else if (result.data.ok) {
+        pending.resolve(result.data.data)
+      } else {
+        pending.reject(
+          new BridgeError(result.data.error.code, result.data.error.message, {
+            status: 502,
+            details: result.data.error.details,
+          }),
+        )
+      }
+      return
+    }
+
+    if (message.type === 'ping') {
+      this.respond(message, 'pong', undefined)
+      return
+    }
+
+    if (message.type === 'extension.hello') {
+      await this.handleHello(message)
+      return
+    }
+
+    if (message.type === 'extension.pair') {
+      await this.handlePair(message)
+      return
+    }
+
+    this.emit('message', message)
+  }
+
+  private async handleHello(message: MessageEnvelope) {
+    const parsed = ExtensionHelloInputSchema.safeParse(message.data)
+    if (!parsed.success) {
+      this.respond(
+        message,
+        `${message.type}:res`,
+        safeError(
+          new BridgeError('InvalidHello', 'Invalid Extension hello', {
+            status: 400,
+            details: parsed.error.issues,
+          }),
+        ),
+      )
+      return
+    }
+
+    const hello = parsed.data
+    this.clientId = hello.clientId
+    this.clientName = hello.clientName
+    this.capabilities = hello.capabilities
+
+    const accepted = Boolean(hello.credential && this.options.verifyCredential(hello.clientId, hello.credential))
+    this.pairingRequired = !accepted
+    const response = BridgeHelloDataSchema.parse({
+      accepted,
+      requiresPairing: !accepted,
+      bridgeVersion: this.options.bridgeVersion,
+      protocolVersion: this.options.protocolVersion,
+      capabilities: this.options.capabilities,
+    })
+
+    this.respond(message, `${message.type}:res`, safeSuccess(response))
+    if (accepted) this.authorize(hello)
+  }
+
+  private async handlePair(message: MessageEnvelope) {
+    const parsed = ExtensionPairInputSchema.safeParse(message.data)
+    if (!parsed.success) {
+      this.respond(
+        message,
+        `${message.type}:res`,
+        safeError(
+          new BridgeError('InvalidPairingRequest', 'Invalid pairing request', {
+            status: 400,
+            details: parsed.error.issues,
+          }),
+        ),
+      )
+      return
+    }
+
+    const input = parsed.data
+    if (!this.clientId || input.clientId !== this.clientId || input.clientName !== this.clientName) {
+      this.respond(
+        message,
+        `${message.type}:res`,
+        safeError(
+          new BridgeError('PairingSessionMismatch', 'Pairing request does not match the Extension hello', {
+            status: 400,
+          }),
+        ),
+      )
+      return
+    }
+
+    try {
+      const credential = await this.options.pair(input, this.options.remoteAddress)
+      const response = BridgePairDataSchema.parse({
+        accepted: true,
+        clientId: input.clientId,
+        credential,
+      })
+      this.respond(message, `${message.type}:res`, safeSuccess(response))
+      this.authorize({ ...input, capabilities: this.capabilities })
+    } catch (error) {
+      this.respond(message, `${message.type}:res`, safeError(error))
+    }
+  }
+
+  private authorize(hello: Pick<ExtensionHelloInput, 'clientId' | 'clientName' | 'capabilities'>) {
+    this.ready = true
+    this.pairingRequired = false
+    this.clientId = hello.clientId
+    this.clientName = hello.clientName
+    this.capabilities = hello.capabilities
+    this.emit('ready', {
+      clientId: this.clientId,
+      clientName: this.clientName,
+      capabilities: this.capabilities,
+    })
+  }
+
+  private respond(request: MessageEnvelope, type: string, data: unknown) {
+    this.send(createEnvelope(type, data, { id: request.id, callback: false }))
+  }
+
+  private send(envelope: MessageEnvelope) {
+    if (this.socket.readyState !== this.socket.OPEN) {
+      throw new BridgeError('ExtensionUnavailable', 'Tapicker Extension WebSocket is not open', { status: 503 })
+    }
+    this.socket.send(JSON.stringify(envelope))
+  }
+
+  private rejectPending(error: unknown) {
+    for (const pending of this.pendingRequests.values()) {
+      clearTimeout(pending.timer)
+      pending.reject(error)
+    }
+    this.pendingRequests.clear()
+  }
+
+  private reportError(error: unknown) {
+    if (this.listenerCount('error') > 0) {
+      this.emit('error', error)
+    }
+  }
+}