playwriter 0.1.0 → 0.3.0

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "playwriter",
   "description": "",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,7 +40,7 @@
     "async-sema": "^3.1.1",
     "diff": "^8.0.2",
     "dom-accessibility-api": "^0.7.1",
-    "goke": "^6.6.0",
+    "goke": "^6.12.1",
     "hono": "^4.12.12",
     "picocolors": "^1.1.1",
     "posthtml": "^0.16.7",
@@ -59,7 +59,7 @@
     "build": "rm -rf dist *.tsbuildinfo && mkdir dist && bun scripts/build-client-bundles.ts && tsc && bun scripts/build-extension-bundle.ts && bun scripts/build-resources.ts",
     "watch": "tsc -w",
     "cli": "vite-node src/cli.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc",
     "mcp": "vite-node src/mcp.ts",
     "test": "vitest run -u",
     "test:watch": "vitest"

package/src/cdp-log.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect } from 'vitest'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { createCdpLogger, type CdpLogEntry } from './cdp-log.js'
+
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'cdp-log-test-'))
+}
+
+function makeEntry(i: number): CdpLogEntry {
+  return {
+    timestamp: new Date().toISOString(),
+    direction: 'from-extension',
+    message: { method: `Test.method${i}`, id: i },
+  }
+}
+
+function readIds(logFile: string): number[] {
+  return fs
+    .readFileSync(logFile, 'utf-8')
+    .trim()
+    .split('\n')
+    .filter((l) => {
+      return l.length > 0
+    })
+    .map((l) => {
+      return JSON.parse(l).message.id as number
+    })
+}
+
+describe('CDP log rotation', () => {
+  it('rotates when lineCount exceeds maxEntries, keeping last half', async () => {
+    const tmpDir = makeTmpDir()
+    const logFile = path.join(tmpDir, 'cdp.jsonl')
+    const logger = createCdpLogger({ logFilePath: logFile, maxEntries: 20 })
+
+    // Write 25 entries to trigger rotation (threshold is 20)
+    for (let i = 0; i < 25; i++) {
+      logger.log(makeEntry(i))
+    }
+    await logger.flush()
+
+    const ids = readIds(logFile)
+
+    // Rotation triggers after entry 20 is written (lineCount becomes 21 > 20).
+    // It keeps last 10 (entries 11-20), then entries 21-24 are appended.
+    expect(ids).toMatchInlineSnapshot(`
+      [
+        11,
+        12,
+        13,
+        14,
+        15,
+        16,
+        17,
+        18,
+        19,
+        20,
+        21,
+        22,
+        23,
+        24,
+      ]
+    `)
+
+    fs.rmSync(tmpDir, { recursive: true })
+  })
+
+  it('does not rotate when under maxEntries', async () => {
+    const tmpDir = makeTmpDir()
+    const logFile = path.join(tmpDir, 'cdp.jsonl')
+    const logger = createCdpLogger({ logFilePath: logFile, maxEntries: 50 })
+
+    for (let i = 0; i < 30; i++) {
+      logger.log(makeEntry(i))
+    }
+    await logger.flush()
+
+    const ids = readIds(logFile)
+    expect(ids.length).toBe(30)
+    expect(ids[0]).toBe(0)
+    expect(ids[29]).toBe(29)
+
+    fs.rmSync(tmpDir, { recursive: true })
+  })
+
+  it('handles multiple rotations', async () => {
+    const tmpDir = makeTmpDir()
+    const logFile = path.join(tmpDir, 'cdp.jsonl')
+    const logger = createCdpLogger({ logFilePath: logFile, maxEntries: 10 })
+
+    // Write 35 entries, should trigger multiple rotations
+    for (let i = 0; i < 35; i++) {
+      logger.log(makeEntry(i))
+    }
+    await logger.flush()
+
+    const ids = readIds(logFile)
+
+    // File should never exceed maxEntries
+    expect(ids.length).toBeLessThanOrEqual(15)
+    expect(ids.length).toBeGreaterThanOrEqual(5)
+
+    // Last entry should always be the most recent
+    expect(ids[ids.length - 1]).toBe(34)
+    // No entries from the very beginning should survive multiple rotations
+    expect(ids[0]).toBeGreaterThan(10)
+
+    fs.rmSync(tmpDir, { recursive: true })
+  })
+
+  it('uses atomic rename for rotation', async () => {
+    const tmpDir = makeTmpDir()
+    const logFile = path.join(tmpDir, 'cdp.jsonl')
+    const logger = createCdpLogger({ logFilePath: logFile, maxEntries: 10 })
+
+    for (let i = 0; i < 15; i++) {
+      logger.log(makeEntry(i))
+    }
+    await logger.flush()
+
+    // Temp file should not remain after successful rotation
+    expect(fs.existsSync(`${logFile}.tmp`)).toBe(false)
+
+    const ids = readIds(logFile)
+    expect(ids[ids.length - 1]).toBe(14)
+
+    fs.rmSync(tmpDir, { recursive: true })
+  })
+})

package/src/cdp-log.ts

@@ -12,6 +12,8 @@ export type CdpLogEntry = {
 
 export type CdpLogger = {
   log(entry: CdpLogEntry): void
+  /** Wait for all pending writes (and any in-flight rotation) to complete */
+  flush(): Promise<void>
   logFilePath: string
 }
 
@@ -41,10 +43,20 @@ function createTruncatingReplacer({ maxStringLength }: { maxStringLength: number
   }
 }
 
+const DEFAULT_MAX_ENTRIES = 10_000
+
+function resolvePositiveInt(value: number | undefined, fallback: number): number {
+  if (value == null || !Number.isFinite(value) || value < 2) {
+    return fallback
+  }
+  return Math.floor(value)
+}
+
 export function createCdpLogger({
   logFilePath,
   maxStringLength,
-}: { logFilePath?: string; maxStringLength?: number } = {}): CdpLogger {
+  maxEntries,
+}: { logFilePath?: string; maxStringLength?: number; maxEntries?: number } = {}): CdpLogger {
   const resolvedLogFilePath = logFilePath || LOG_CDP_FILE_PATH
   const logDir = path.dirname(resolvedLogFilePath)
   if (!fs.existsSync(logDir)) {
@@ -53,16 +65,46 @@ export function createCdpLogger({
   fs.writeFileSync(resolvedLogFilePath, '')
 
   let queue: Promise<void> = Promise.resolve()
+  let lineCount = 0
   const maxLength = maxStringLength ?? DEFAULT_MAX_STRING_LENGTH
+  const envMaxEntries = Number(process.env.PLAYWRITER_CDP_LOG_MAX_ENTRIES)
+  const resolvedMaxEntries = resolvePositiveInt(maxEntries, resolvePositiveInt(envMaxEntries, DEFAULT_MAX_ENTRIES))
+  // Keep half the entries after rotation so we don't rotate on every write
+  const keepAfterRotation = Math.floor(resolvedMaxEntries / 2)
+
+  // Atomic rotation: write to temp file then rename to avoid corruption on crash
+  const rotate = async (): Promise<void> => {
+    try {
+      const content = await fs.promises.readFile(resolvedLogFilePath, 'utf-8')
+      const lines = content.split('\n').filter((l) => {
+        return l.length > 0
+      })
+      const kept = lines.slice(-keepAfterRotation)
+      const tmpPath = `${resolvedLogFilePath}.tmp`
+      await fs.promises.writeFile(tmpPath, kept.join('\n') + '\n')
+      await fs.promises.rename(tmpPath, resolvedLogFilePath)
+      lineCount = kept.length
+    } catch {
+      // If rotation fails (disk error, permissions), keep logging without rotation.
+      // lineCount stays high so rotation will be retried on next write.
+    }
+  }
 
   const log = (entry: CdpLogEntry): void => {
     const replacer = createTruncatingReplacer({ maxStringLength: maxLength })
     const line = JSON.stringify(entry, replacer)
-    queue = queue.then(() => fs.promises.appendFile(resolvedLogFilePath, `${line}\n`))
+    queue = queue.then(async () => {
+      await fs.promises.appendFile(resolvedLogFilePath, `${line}\n`)
+      lineCount++
+      if (lineCount > resolvedMaxEntries) {
+        await rotate()
+      }
+    })
   }
 
   return {
     log,
+    flush: () => queue,
     logFilePath: resolvedLogFilePath,
   }
 }

package/src/cdp-relay.ts

@@ -1,6 +1,6 @@
 import { Hono } from 'hono'
 import { cors } from 'hono/cors'
-import { serve } from '@hono/node-server'
+import { createAdaptorServer } from '@hono/node-server'
 import { getConnInfo } from '@hono/node-server/conninfo'
 import { createNodeWebSocket } from '@hono/node-ws'
 import type { WSContext } from 'hono/ws'
@@ -523,8 +523,9 @@ export async function startPlayWriterCDPRelayServer({
 
   // Auto-create initial tab when PLAYWRITER_AUTO_ENABLE is set and no targets exist.
   // This allows Playwright to connect and immediately have a page to work with.
-  async function maybeAutoCreateInitialTab(extensionId: string): Promise<void> {
-    if (!process.env.PLAYWRITER_AUTO_ENABLE) {
+  async function maybeAutoCreateInitialTab(options: { extensionId: string; autoEnable: boolean }): Promise<void> {
+    const { extensionId, autoEnable } = options
+    if (!autoEnable && !process.env.PLAYWRITER_AUTO_ENABLE) {
       return
     }
     const conn = getExtensionConnection(extensionId)
@@ -654,12 +655,14 @@ export async function startPlayWriterCDPRelayServer({
     params,
     sessionId,
     source,
+    autoEnable,
   }: {
     extensionId: string | null
     method: CDPCommand['method'] | (string & {})
     params: CDPCommand['params']
     sessionId?: CDPCommand['sessionId']
     source?: CDPCommand['source']
+    autoEnable: boolean
   }) {
     const conn = getExtensionConnection(extensionId)
     const connectedTargets = conn?.connectedTargets || new Map<string, relayState.ConnectedTarget>()
@@ -699,7 +702,7 @@ export async function startPlayWriterCDPRelayServer({
           break
         }
         if (conn) {
-          await maybeAutoCreateInitialTab(conn.id)
+          await maybeAutoCreateInitialTab({ extensionId: conn.id, autoEnable })
         }
         // Forward auto-attach so Chrome emits iframe Target.attachedToTarget events.
         // Playwright relies on these (with parentFrameId) when reconnecting over CDP.
@@ -856,6 +859,87 @@ export async function startPlayWriterCDPRelayServer({
       allowMethods: ['GET', 'POST', 'HEAD', 'OPTIONS'],
     }),
   )
+  // Host header validation to prevent DNS rebinding attacks.
+  // DNS rebinding is worse than a simple cross-origin request: the attacker
+  // serves a page from http://evil.com:19988, then rebinds the DNS to
+  // 127.0.0.1. The browser now considers requests to our relay as same-origin,
+  // so Sec-Fetch-Site is "same-origin", CORS doesn't apply, and JSON POSTs
+  // don't need preflight. This bypasses all our other defenses.
+  // By rejecting any Host that isn't a known localhost value we kill DNS
+  // rebinding at the root. When a valid token is provided (remote access), we
+  // allow through regardless of Host since remote clients use real hostnames.
+  const ALLOWED_HOSTS = new Set([
+    'localhost',
+    '127.0.0.1',
+    '[::1]',
+    '::1',
+  ])
+
+  // Parse the Host header into just the hostname, handling IPv6 brackets and
+  // port suffixes. Returns null for missing or malformed values.
+  function parseHostname(hostHeader: string | undefined): string | null {
+    const value = hostHeader?.trim().toLowerCase()
+    if (!value) {
+      return null
+    }
+    // IPv6 in brackets: [::1] or [::1]:19988
+    if (value.startsWith('[')) {
+      const closingBracket = value.indexOf(']')
+      if (closingBracket === -1) {
+        return null
+      }
+      const host = value.slice(0, closingBracket + 1)
+      const rest = value.slice(closingBracket + 1)
+      if (rest && !/^:\d+$/.test(rest)) {
+        return null
+      }
+      return host
+    }
+    // Bare ::1 without brackets (uncommon but possible)
+    if (value === '::1') {
+      return '::1'
+    }
+    // hostname or hostname:port
+    const colonIndex = value.indexOf(':')
+    if (colonIndex === -1) {
+      return value
+    }
+    const host = value.slice(0, colonIndex)
+    const portPart = value.slice(colonIndex + 1)
+    if (!/^\d+$/.test(portPart)) {
+      return null
+    }
+    return host || null
+  }
+
+  function hasValidToken(c: { req: { header: (name: string) => string | undefined; url: string } }): boolean {
+    if (!token) {
+      return false
+    }
+    const authHeader = c.req.header('authorization') || ''
+    const bearerToken = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null
+    const queryToken = new URL(c.req.url, 'http://localhost').searchParams.get('token')
+    return bearerToken === token || queryToken === token
+  }
+
+  app.use('*', async (c, next) => {
+    const hostname = parseHostname(c.req.header('host'))
+    if (hostname && ALLOWED_HOSTS.has(hostname)) {
+      return next()
+    }
+    // Remote clients with a valid token are allowed regardless of Host
+    if (hasValidToken(c)) {
+      return next()
+    }
+    // Missing Host header from non-browser clients (curl without Host) is fine
+    // in local mode since they're not browser-based DNS rebinding attacks
+    if (!hostname && !token) {
+      return next()
+    }
+    logger?.log(pc.red(`Rejecting request with unexpected Host header: ${c.req.header('host')} (DNS rebinding protection)`))
+    return c.text('Forbidden - Invalid Host header', 403)
+  })
+
   const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app })
 
   const getCdpWsUrl = (c: { req: { header: (name: string) => string | undefined } }) => {
@@ -1028,6 +1112,7 @@ export async function startPlayWriterCDPRelayServer({
       const clientId = c.req.param('clientId') || 'default'
       const url = new URL(c.req.url, 'http://localhost')
       const requestedExtensionId = url.searchParams.get('extensionId')
+      const autoEnable = url.searchParams.get('autoEnable') === '1'
       // When extensionId is explicit, resolve directly. Otherwise use fallback which
       // handles single-extension and uniquely-active-extension cases (#52).
       const resolvedExtension = requestedExtensionId
@@ -1119,6 +1204,7 @@ export async function startPlayWriterCDPRelayServer({
               params,
               sessionId,
               source,
+              autoEnable,
             })
 
             if (method === 'Target.setAutoAttach' && !sessionId) {
@@ -1755,7 +1841,7 @@ export async function startPlayWriterCDPRelayServer({
       const { ExecutorManager } = await import('./executor.js')
       // Pass config instead of URL so executor can generate unique client IDs for each connection
       executorManager = new ExecutorManager({
-        cdpConfig: { host: '127.0.0.1', port },
+        cdpConfig: { host: '127.0.0.1', port, token },
         logger: logger || { log: console.error, error: console.error },
       })
     }
@@ -1763,20 +1849,24 @@ export async function startPlayWriterCDPRelayServer({
   }
 
   // ============================================================================
-  // Security middleware for privileged HTTP routes (/cli/*, /recording/*)
+  // Security middleware for privileged HTTP routes (/cli/*, /recording/*, /mcp-log)
   //
   // CORS alone does NOT prevent cross-origin POST attacks. Browsers skip the
   // preflight for "simple" requests (POST + Content-Type: text/plain), so a
   // malicious website can fire-and-forget a POST to localhost:19988/cli/execute
   // and the code executes before CORS even enters the picture.
   //
-  // Two layers of defense:
+  // Three layers of defense:
   // 1. Sec-Fetch-Site: browsers set this forbidden header on every request.
   //    If present and not "same-origin"/"none", it's a cross-origin browser
   //    request → reject. Node.js clients don't send it → unaffected.
   // 2. Content-Type must be application/json on POST. This forces a CORS
   //    preflight as a fallback, which our CORS policy already blocks.
-  // 3. When token mode is enabled (remote access), require the token.
+  // 3. When token mode is enabled (remote access), require the token on EVERY
+  //    request, including loopback. Tunnel agents (traforo, ngrok, cloudflared)
+  //    forward public traffic from 127.0.0.1, so a loopback bypass would be
+  //    a full auth bypass. In-process callers attach the token themselves
+  //    via PLAYWRITER_TOKEN env (set by the `serve` command at startup).
   // ============================================================================
   const privilegedRouteMiddleware = async (
     c: Parameters<Parameters<typeof app.use>[1]>[0],
@@ -1801,7 +1891,14 @@ export async function startPlayWriterCDPRelayServer({
       }
     }
 
-    // When token mode is enabled (remote/serve mode), require authentication.
+    // When token mode is enabled (remote/serve mode), require authentication
+    // on EVERY request, including loopback. Earlier versions bypassed the
+    // check for 127.0.0.1/::1 to spare in-process callers, but that's unsafe:
+    // when the relay is fronted by a tunnel agent (traforo, ngrok, cloudflared,
+    // etc.) running as a local process, every public request reaches the relay
+    // from 127.0.0.1 and would skip auth. In-process callers must instead
+    // attach the token themselves — they read PLAYWRITER_TOKEN from env, which
+    // the `serve` command sets at startup.
     if (token) {
       const authHeader = c.req.header('authorization') || ''
       const bearerToken = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null
@@ -1818,6 +1915,7 @@ export async function startPlayWriterCDPRelayServer({
 
   app.use('/cli/*', privilegedRouteMiddleware)
   app.use('/recording/*', privilegedRouteMiddleware)
+  app.use('/mcp-log', privilegedRouteMiddleware)
 
   app.post('/cli/execute', async (c) => {
     try {
@@ -1885,6 +1983,7 @@ export async function startPlayWriterCDPRelayServer({
   app.post('/cli/session/new', async (c) => {
     const body = (await c.req.json().catch(() => ({}))) as {
       extensionId?: string | null
+      autoEnable?: boolean
       cwd?: string
       /** Direct CDP WebSocket URL — bypasses extension, connects straight to Chrome */
       cdpEndpoint?: string
@@ -1938,6 +2037,7 @@ export async function startPlayWriterCDPRelayServer({
     const executor = manager.getExecutor({
       sessionId,
       cwd,
+      cdpConfig: { host: '127.0.0.1', port, token, extensionId: conn.stableKey, autoEnable: body.autoEnable === true },
       sessionMetadata: {
         extensionId: conn.stableKey,
         browser: conn.info.browser || null,
@@ -2053,9 +2153,26 @@ export async function startPlayWriterCDPRelayServer({
     return c.json(result)
   })
 
-  const server = serve({ fetch: app.fetch, port, hostname: host })
+  // Use createAdaptorServer instead of serve() so we control the listen()
+  // timing. This lets us inject WebSocket upgrade handlers before binding and
+  // await the bind to surface EADDRINUSE as a catchable error (issue #75).
+  const server = createAdaptorServer({ fetch: app.fetch, hostname: host })
   injectWebSocket(server)
 
+  await new Promise<void>((resolve, reject) => {
+    const onListening = () => {
+      server.off('error', onError)
+      resolve()
+    }
+    const onError = (error: Error) => {
+      server.off('listening', onListening)
+      reject(error)
+    }
+    server.once('listening', onListening)
+    server.once('error', onError)
+    server.listen(port, host)
+  })
+
   const wsHost = `ws://${host}:${port}`
   const cdpEndpoint = `${wsHost}/cdp`
   const extensionEndpoint = `${wsHost}/extension`

package/src/cli-help.test.ts

@@ -38,4 +38,26 @@ describe('playwriter cli help', () => {
     expect(stdout).toContain('--replace')
     expect(stderr).toBe('')
   }, 30000)
+
+  test('unknown command exits with code 1', async () => {
+    try {
+      await runCli(['run'])
+      expect.unreachable('should have thrown')
+    } catch (error: any) {
+      expect(error.code).toBe(1)
+      expect(error.stderr).toContain('Unknown command: run')
+      expect(error.stderr).toContain('playwriter --help')
+    }
+  }, 30000)
+
+  test('unknown subcommand exits with code 1', async () => {
+    try {
+      await runCli(['session', 'nonexistent'])
+      expect.unreachable('should have thrown')
+    } catch (error: any) {
+      expect(error.code).toBe(1)
+      expect(error.stdout).toContain('Unknown command: session nonexistent')
+      expect(error.stdout).toContain('session new')
+    }
+  }, 30000)
 })