@tapicker/bridge 1.0.0

package/docs/operations.md

@@ -0,0 +1,85 @@
+# Pairing, Deployment, and Security
+
+## Start the Bridge and connect an Extension
+
+By default, the Bridge binds to `127.0.0.1` and tries ports `9520` through `9530`. Run it in the foreground:
+
+```bash
+tapicker bridge start
+```
+
+Or run it as a daemon:
+
+```bash
+tapicker bridge start --daemon
+tapicker bridge code
+tapicker bridge extensions
+tapicker bridge stop
+```
+
+Startup output includes the selected HTTP, WebSocket, and MCP addresses, plus a four-digit pairing code. In the Extension, open **Settings > General**, enable the Bridge connection, and set its endpoint to the WebSocket address, for example `ws://127.0.0.1:9520/ws`. Enter the displayed code to pair it for the first time.
+
+Paired Extension credentials are stored locally. After a Bridge restart, the Extension reconnects with its saved credentials and does not need another pairing code. The Extension's `/ws` channel is not the HTTP API for agents; see [HTTP API](http-api.md) for commands and [Workflow status events](workflow-watch.md) for live status updates.
+
+## Pairing codes and rate limits
+
+- The current four-digit code is held in memory and regenerated each time the Bridge starts.
+- After a new Extension pairs successfully, the code is invalidated and replaced. Previously paired Extensions reconnect with their own saved credentials and do not consume a new code.
+- Each remote IP can make up to five pairing attempts per 60 seconds. Five incorrect attempts with the current code pause new pairing.
+- To resume pairing after it is paused, run `tapicker bridge code --refresh` on the Bridge host. This generates a new code without disconnecting paired Extensions.
+- `/v1/health`, `/v1/discovery`, `/v1/capabilities`, and `/v1/extensions` never return pairing codes or pairing credentials.
+
+## Data directory
+
+The default directory is `~/.tapicker`. The CLI creates and uses these files:
+
+| File                  | Purpose                                                                   |
+| --------------------- | ------------------------------------------------------------------------- |
+| `paired-clients.json` | Credentials for paired Extensions; restrict access to this file.          |
+| `bridge.pid`          | Process information for a daemon Bridge.                                  |
+| `bridge.log`          | Daemon output log.                                                        |
+| `bridge.sock`         | Local management channel on macOS/Linux; Windows uses a local named pipe. |
+
+Set a different directory with `--data-dir <path>` or `TAPICKER_DATA_DIR`. Use the same custom directory for `bridge start` and later management commands such as `stop`, `code`, and `extensions`. Removing `paired-clients.json` removes saved credentials, so affected Extensions must pair again.
+
+## Configuration
+
+| Setting                 | Purpose                                                                                        |
+| ----------------------- | ---------------------------------------------------------------------------------------------- |
+| `TAPICKER_DATA_DIR`     | Bridge data directory; equivalent to `--data-dir`.                                             |
+| `TAPICKER_BRIDGE_TOKEN` | HTTP Bearer token used by the Bridge and, by default, by `tapicker mcp` when connecting to it. |
+| `TAPICKER_BRIDGE_URL`   | HTTP(S) URL used by the `tapicker mcp` stdio adapter; defaults to `http://127.0.0.1:9520`.     |
+
+Command-line `--token` takes precedence over the corresponding environment variable. Avoid putting tokens in shared shell history or public configuration files.
+
+The HTTP API and `/mcp` allow any web-page Origin by default (`--cors-origin *`). Restrict browser-based callers with a comma-separated allowlist, for example `--cors-origin https://agent.example.com,https://app.example.com`. CORS is not authentication: in the default loopback configuration, no token is required, so web pages may call the local HTTP API. Use an Origin allowlist when that is not desired. Remote deployments must use TLS and a Bearer token.
+
+## Remote deployment
+
+Use TLS for remote Extension and agent connections. When binding to a non-loopback address, the CLI requires a Bearer token, TLS private key, and certificate:
+
+```bash
+tapicker bridge start \
+  --host 0.0.0.0 \
+  --port 9520 \
+  --token 'replace-with-a-long-random-token' \
+  --tls-key ./server.key \
+  --tls-cert ./server.crt
+```
+
+Use these addresses from remote clients:
+
+- Extension: `wss://<host>:9520/ws`
+- MCP: `https://<host>:9520/mcp`
+- HTTP: `https://<host>:9520/...`
+- Workflow status events: `wss://<host>:9520/v1/commands/workflow.watch`
+
+The Bearer token protects HTTP commands, Workflow status queries, MCP, the `workflow.watch` WebSocket handshake, and `/v1/extensions`. `/v1/health`, `/v1/discovery`, and `/v1/capabilities` are public. The Extension's `/ws` uses pairing codes and saved credentials instead of the Bearer token. The Bridge does not provide accounts or centralized client management.
+
+## Troubleshooting
+
+- **A Workflow command requires `clientId`:** Call MCP `extensions_list` or HTTP `GET /v1/extensions`, choose an Extension with `ready: true`, and pass its `clientId`.
+- **No Extension is available:** Check the endpoint and connection indicator under **Settings > General**. Pair once; subsequent connections should use saved credentials.
+- **Pairing is paused:** Run `tapicker bridge code --refresh` on the Bridge host and use the new code.
+- **A management command cannot find the Bridge:** Make sure it uses the same `--data-dir` or `TAPICKER_DATA_DIR` as the Bridge process.
+- **You need to check available commands and parameters:** Query `/v1/capabilities`; see [HTTP API](http-api.md) for request formats.

package/docs/workflow-watch.md

@@ -0,0 +1,86 @@
+# Workflow Status Events over WebSocket
+
+A Workflow is a long-running task. External clients can use `workflow.watch` to open a WebSocket subscription for one Workflow and receive status changes from the Bridge, instead of repeatedly polling the status endpoint.
+
+## Connect and subscribe
+
+The default local URL is `ws://127.0.0.1:9520/v1/commands/workflow.watch`. Use `wss://` when TLS is enabled. If the Bridge has a Bearer token, include `Authorization: Bearer <token>` in the WebSocket handshake.
+
+After connecting, send a Bridge envelope:
+
+```json
+{
+  "id": "request-1",
+  "time": 1720000000000,
+  "type": "workflow.watch",
+  "data": {
+    "clientId": "c0ffee00-0000-4000-8000-000000000001",
+    "input": { "workflowId": "workflow_xxx" }
+  }
+}
+```
+
+You may omit `clientId` only when exactly one ready Extension is connected. If multiple Extensions are ready, specify the target. The Bridge responds with `workflow.watch:res`; on success, the response includes the selected `clientId` and `workflowId`. Each WebSocket watches one Workflow. Closing the connection cancels the subscription, not the Workflow.
+
+After the subscription is accepted, the Bridge sends `workflow.status` events:
+
+```json
+{
+  "clientId": "c0ffee00-0000-4000-8000-000000000001",
+  "workflowId": "workflow_xxx",
+  "state": "running",
+  "updatedAt": "2026-09-30T10:20:30.000Z"
+}
+```
+
+Possible states are `running`, `paused`, `stopping`, `completed`, `stopped`, and `failed`. The Bridge does not buffer or replay events missed while the client is disconnected.
+
+## Watch a Workflow as it starts
+
+To avoid missing early status changes, first connect and wait for a successful `workflow.watch:res`, then call `POST /v1/commands/workflow.start`. The watch response identifies the selected `clientId`; pass that same ID to the start command so both requests target the same Extension.
+
+After reconnecting, restore the subscription and make one `POST /v1/commands/workflow.status` request to obtain the current or most recently persisted state. This is a one-time snapshot check, not a polling loop. Terminal states are `completed`, `stopped`, and `failed`.
+
+The CLI provides `tapicker workflow start <workflowId> --watch` and `tapicker workflow watch <workflowId>`. MCP provides the `workflow_watch` tool. See the [CLI reference](cli.md), [HTTP API](http-api.md), and [MCP guide](mcp.md).
+
+## Node.js example
+
+This example uses the `ws` package. If the Bridge requires a token, the example adds it to the handshake headers:
+
+```js
+import { randomUUID } from 'node:crypto'
+import WebSocket from 'ws'
+
+const url = 'ws://127.0.0.1:9520/v1/commands/workflow.watch'
+const token = process.env.TAPICKER_BRIDGE_TOKEN
+const options = token ? { headers: { Authorization: `Bearer ${token}` } } : undefined
+const watch = new WebSocket(url, options)
+const requestId = randomUUID()
+
+watch.on('open', () => {
+  watch.send(
+    JSON.stringify({
+      id: requestId,
+      time: Date.now(),
+      type: 'workflow.watch',
+      data: {
+        clientId: 'c0ffee00-0000-4000-8000-000000000001',
+        input: { workflowId: 'workflow_xxx' },
+      },
+    }),
+  )
+})
+
+watch.on('message', (raw) => {
+  const message = JSON.parse(raw.toString())
+  if (message.type === 'workflow.watch:res' && message.id === requestId) {
+    if (!message.data.ok) throw new Error(message.data.error.message)
+    console.log('Watching:', message.data.data)
+  }
+  if (message.type === 'workflow.status') console.log(message.data)
+})
+```
+
+## The Extension WebSocket is different
+
+`/v1/commands/workflow.watch` is for external clients and only streams Workflow status. The Extension uses `/ws` on the same port to pair with the Bridge, reconnect, and exchange execution commands. `/ws` is an internal Bridge connection, not an agent command API.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@tapicker/bridge",
+  "version": "1.0.0",
+  "description": "Tapicker local and remote command bridge",
+  "homepage": "https://www.tapicker.com/",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "tapicker": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "src",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
+    "start": "node dist/cli.js bridge start",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/node": "^2.1.0",
+    "@modelcontextprotocol/server": "^2.2.0",
+    "cac": "^6.7.14",
+    "ws": "^8.18.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.13",
+    "prettier": "^3.6.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  }
+}

package/src/bridge/bridge-service.ts

@@ -0,0 +1,291 @@
+import { randomInt, randomUUID, timingSafeEqual } from 'node:crypto'
+import { EventEmitter } from 'node:events'
+import type { WebSocket } from 'ws'
+import { BridgeError } from '../errors.js'
+import { WorkflowStatusDataSchema } from '../protocol/schema.js'
+import type { ExtensionPairInput, WorkflowStatusData } from '../protocol/schema.js'
+import { VERSION, PROTOCOL_VERSION } from '../constants.js'
+import { ExtensionSession } from './extension-session.js'
+import type { ExtensionSessionStatus } from './extension-session.js'
+import type { PairedExtensionIdentity, PairingStatePersistence } from './pairing-state.js'
+
+const PAIRING_WINDOW_MS = 60_000
+const MAX_PAIRING_ATTEMPTS_PER_IP = 5
+const MAX_PAIRING_FAILURES_PER_CODE = 5
+
+export type BridgeServiceOptions = {
+  pairingCode: string
+  capabilities: string[]
+  pairingState?: PairingStatePersistence
+}
+
+export type BridgeWorkflowStatusEvent = WorkflowStatusData & { clientId: string }
+
+type PairingAttemptWindow = {
+  startedAt: number
+  attempts: number
+}
+
+export class BridgeService extends EventEmitter {
+  private readonly sessions = new Set<ExtensionSession>()
+  private readonly sessionsByClientId = new Map<string, ExtensionSession>()
+  private readonly pairedCredentials = new Map<string, string>()
+  private readonly pairingAttempts = new Map<string, PairingAttemptWindow>()
+  private pairingCode: string
+  private pairingFailures = 0
+  private pairingLocked = false
+  private pairingInProgress = false
+  private initialization: Promise<void> | undefined
+
+  constructor(private readonly options: BridgeServiceOptions) {
+    super()
+    this.pairingCode = options.pairingCode
+  }
+
+  initialize() {
+    if (!this.initialization) {
+      this.initialization = this.restorePairingState()
+    }
+    return this.initialization
+  }
+
+  attachExtension(socket: WebSocket, remoteAddress = 'unknown') {
+    const session = new ExtensionSession(socket, {
+      bridgeVersion: VERSION,
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: this.options.capabilities,
+      remoteAddress,
+      verifyCredential: (clientId, credential) => this.verifyCredential(clientId, credential),
+      pair: (input, address) => this.pair(input, address),
+    })
+
+    this.sessions.add(session)
+    session.on('ready', (hello) => {
+      const previousSession = this.sessionsByClientId.get(hello.clientId)
+      this.sessionsByClientId.set(hello.clientId, session)
+      if (previousSession && previousSession !== session) {
+        previousSession.close(1000, 'Replaced by a newer connection for this Extension')
+      }
+      this.emit('extension.ready', hello)
+    })
+    session.on('message', (message) => {
+      const status = session.getStatus()
+      if (status.ready && status.clientId && message.type === 'workflow.status') {
+        const parsed = WorkflowStatusDataSchema.safeParse(message.data)
+        if (parsed.success) {
+          this.emit('workflow.status', {
+            clientId: status.clientId,
+            ...parsed.data,
+          } satisfies BridgeWorkflowStatusEvent)
+        }
+      }
+      this.emit('extension.message', message)
+    })
+    session.on('error', (error) => this.emit('extension.error', error))
+    session.on('close', (details) => {
+      this.sessions.delete(session)
+      const clientId = session.getStatus().clientId
+      if (clientId && this.sessionsByClientId.get(clientId) === session) {
+        this.sessionsByClientId.delete(clientId)
+      }
+      this.emit('extension.close', details)
+    })
+
+    session.start()
+    return session
+  }
+
+  async sendCommand<T>(type: string, data: unknown, clientId?: string) {
+    const session = this.selectCommandSession(type, clientId)
+    return session.request<T>(type, data)
+  }
+
+  async sendCommandWithClientId<T>(type: string, data: unknown, clientId?: string) {
+    const session = this.selectCommandSession(type, clientId)
+    const selectedClientId = session.getStatus().clientId
+    if (!selectedClientId) {
+      throw new BridgeError('ExtensionUnavailable', 'The selected Tapicker Extension has no client ID', { status: 503 })
+    }
+
+    return {
+      clientId: selectedClientId,
+      result: await session.request<T>(type, data),
+    }
+  }
+
+  assertExtensionCapability(type: string, clientId: string) {
+    this.selectCommandSession(type, clientId)
+  }
+
+  resolveCommandClientId(type: string, clientId?: string) {
+    const selectedClientId = this.selectCommandSession(type, clientId).getStatus().clientId
+    if (!selectedClientId) {
+      throw new BridgeError('ExtensionUnavailable', 'The selected Tapicker Extension has no client ID', { status: 503 })
+    }
+    return selectedClientId
+  }
+
+  private selectCommandSession(type: string, clientId?: string) {
+    const readySessions = [...this.sessionsByClientId.entries()].filter(([, session]) => {
+      const status = session.getStatus()
+      return status.connected && status.ready
+    })
+    let session: ExtensionSession | undefined
+
+    if (clientId) {
+      session = this.sessionsByClientId.get(clientId)
+      const status = session?.getStatus()
+      if (!status?.connected || !status.ready) {
+        throw new BridgeError('ExtensionNotConnected', `Tapicker Extension ${clientId} is not connected`, {
+          status: 409,
+          details: { clientId },
+        })
+      }
+    } else if (readySessions.length === 0) {
+      throw new BridgeError('ExtensionUnavailable', 'No paired Tapicker Extension is connected', { status: 503 })
+    } else if (readySessions.length > 1) {
+      throw new BridgeError('ClientIdRequired', 'Specify clientId when multiple Extensions are connected', {
+        status: 409,
+        details: {
+          extensions: readySessions.map(([clientId, readySession]) => ({
+            clientId,
+            clientName: readySession.getStatus().clientName,
+          })),
+        },
+      })
+    } else {
+      session = readySessions[0]?.[1]
+    }
+
+    if (!session) {
+      throw new BridgeError('ExtensionUnavailable', 'No paired Tapicker Extension is connected', { status: 503 })
+    }
+
+    const status = session.getStatus()
+    if (!status.capabilities.includes(type)) {
+      throw new BridgeError('ExtensionCapabilityUnavailable', `Tapicker Extension does not support ${type}`, {
+        status: 409,
+        details: { clientId: status.clientId, clientName: status.clientName, command: type },
+      })
+    }
+
+    return session
+  }
+
+  getExtensionStatuses(): ExtensionSessionStatus[] {
+    return [...this.sessions]
+      .map((session) => session.getStatus())
+      .filter((status) => status.connected)
+      .sort((left, right) => (left.clientName || '').localeCompare(right.clientName || ''))
+  }
+
+  getPairingCode() {
+    return this.pairingLocked ? undefined : this.pairingCode
+  }
+
+  refreshPairingCode() {
+    if (this.pairingInProgress) {
+      throw new BridgeError('PairingUnavailable', 'An Extension is currently being paired; try again shortly', {
+        status: 409,
+      })
+    }
+    this.rotatePairingCode()
+    return this.pairingCode
+  }
+
+  close() {
+    for (const session of this.sessions) {
+      session.close(1000, 'Bridge shutting down')
+    }
+    this.sessions.clear()
+    this.sessionsByClientId.clear()
+  }
+
+  private verifyCredential(clientId: string, credential: string) {
+    const savedCredential = this.pairedCredentials.get(clientId)
+    if (!savedCredential) return false
+    return constantTimeEqual(credential, savedCredential)
+  }
+
+  private async pair(input: ExtensionPairInput, remoteAddress: string) {
+    if (this.pairingLocked) {
+      throw new BridgeError(
+        'PairingRateLimited',
+        'Pairing is locked after too many incorrect codes; run tapicker bridge code --refresh locally',
+        { status: 429, details: { refreshCommand: 'tapicker bridge code --refresh' } },
+      )
+    }
+    if (this.pairingInProgress) {
+      throw new BridgeError('PairingUnavailable', 'Another Extension is currently being paired', { status: 409 })
+    }
+
+    const now = Date.now()
+    for (const [address, attemptWindow] of this.pairingAttempts) {
+      if (now - attemptWindow.startedAt >= PAIRING_WINDOW_MS) {
+        this.pairingAttempts.delete(address)
+      }
+    }
+
+    const current = this.pairingAttempts.get(remoteAddress)
+    const window = !current || now - current.startedAt >= PAIRING_WINDOW_MS ? { startedAt: now, attempts: 0 } : current
+    if (window.attempts >= MAX_PAIRING_ATTEMPTS_PER_IP) {
+      throw new BridgeError('PairingRateLimited', 'Too many pairing attempts; try again in one minute', {
+        status: 429,
+      })
+    }
+
+    window.attempts += 1
+    this.pairingAttempts.set(remoteAddress, window)
+    if (!constantTimeEqual(input.pairingCode, this.pairingCode)) {
+      this.pairingFailures += 1
+      if (this.pairingFailures >= MAX_PAIRING_FAILURES_PER_CODE) {
+        this.pairingLocked = true
+        throw new BridgeError(
+          'PairingRateLimited',
+          'Pairing is locked after too many incorrect codes; run tapicker bridge code --refresh locally',
+          { status: 429, details: { refreshCommand: 'tapicker bridge code --refresh' } },
+        )
+      }
+      throw new BridgeError('InvalidPairingCode', 'The pairing code is incorrect', { status: 401 })
+    }
+
+    this.pairingInProgress = true
+    try {
+      const credential = randomUUID()
+      const identities: PairedExtensionIdentity[] = [...this.pairedCredentials.entries()]
+        .filter(([clientId]) => clientId !== input.clientId)
+        .map(([clientId, savedCredential]) => ({ clientId, credential: savedCredential }))
+      identities.push({ clientId: input.clientId, credential })
+      await this.options.pairingState?.save(identities)
+      this.pairedCredentials.set(input.clientId, credential)
+      this.rotatePairingCode()
+      return credential
+    } finally {
+      this.pairingInProgress = false
+    }
+  }
+
+  private rotatePairingCode() {
+    const previousCode = this.pairingCode
+    do {
+      this.pairingCode = String(randomInt(0, 10_000)).padStart(4, '0')
+    } while (this.pairingCode === previousCode)
+    this.pairingFailures = 0
+    this.pairingLocked = false
+    this.pairingAttempts.clear()
+  }
+
+  private async restorePairingState() {
+    const pairedIdentities = (await this.options.pairingState?.load()) ?? []
+    for (const identity of pairedIdentities) {
+      this.pairedCredentials.set(identity.clientId, identity.credential)
+    }
+  }
+}
+
+function constantTimeEqual(left: string, right: string) {
+  const leftBuffer = Buffer.from(left)
+  const rightBuffer = Buffer.from(right)
+  if (leftBuffer.length !== rightBuffer.length) return false
+  return timingSafeEqual(leftBuffer, rightBuffer)
+}