Authentication - PalanK Agent

Overview

PalanK’s local API does not require authentication tokens. Security is enforced through:

Local-only connections: Only 127.0.0.1 and localhost are allowed
Session-based: Each browser tab attachment creates a unique session

Sessions

Session Creation

When the Chrome extension attaches to a tab, a session is automatically created:

// Event sent from extension to your app
{
  "method": "forwardCDPEvent",
  "params": {
    "method": "Target.attachedToTarget",
    "params": {
      "sessionId": "cb-tab-1",
      "targetInfo": {
        "targetId": "ABC123",
        "type": "page",
        "title": "Google",
        "url": "https://google.com",
        "attached": true
      }
    }
  }
}

Using Session IDs

Include the sessionId in commands to target specific tabs:

{
  "id": 1,
  "method": "forwardCDPCommand",
  "params": {
    "sessionId": "cb-tab-1",
    "method": "Page.navigate",
    "params": {
      "url": "https://example.com"
    }
  }
}

Session Termination

When a tab is detached or closed:

// Event notification
{
  "method": "forwardCDPEvent",
  "params": {
    "method": "Target.detachedFromTarget",
    "params": {
      "sessionId": "cb-tab-1",
      "targetId": "ABC123",
      "reason": "user_detached"
    }
  }
}

Connection Lifecycle

Handshake

Keepalive

The Gateway sends periodic ping messages. Respond with pong:

// Received
{"method": "ping"}

// Send back
{"method": "pong"}

Failure to respond to ping messages may result in connection termination.

Multiple Tabs

You can work with multiple tabs simultaneously:

// Tab 1 session
{
  "id": 1,
  "method": "forwardCDPCommand",
  "params": {
    "sessionId": "cb-tab-1",
    "method": "Page.navigate",
    "params": {"url": "https://site-a.com"}
  }
}

// Tab 2 session
{
  "id": 2,
  "method": "forwardCDPCommand",
  "params": {
    "sessionId": "cb-tab-2",
    "method": "Page.navigate",
    "params": {"url": "https://site-b.com"}
  }
}

Error Handling

No Active Session

{
  "id": 1,
  "error": "No attached tab for method Page.navigate"
}

Solution: Ensure the Chrome extension is attached to a tab before sending commands.

Invalid Session ID

{
  "id": 1,
  "error": "Session not found: cb-tab-99"
}

Solution: Use a valid session ID from a Target.attachedToTarget event.

Connection Lost

If the WebSocket disconnects:

All pending commands will fail
Tabs remain attached in Chrome
Reconnect to resume operations

Best Practices

Track Sessions

Maintain a list of active session IDs from attach/detach events

Handle Disconnects

Implement reconnection logic for robustness

Default Session

Without sessionId, commands go to the first attached tab

Clean Up

Handle detach events to remove stale sessions

​Overview

​Sessions

​Session Creation

​Using Session IDs

​Session Termination

​Connection Lifecycle

​Handshake

​Keepalive

​Multiple Tabs

​Error Handling

​No Active Session

​Invalid Session ID

​Connection Lost

​Best Practices

Track Sessions

Handle Disconnects

Default Session

Clean Up

Overview

Sessions

Session Creation

Using Session IDs

Session Termination

Connection Lifecycle

Handshake

Keepalive

Multiple Tabs

Error Handling

No Active Session

Invalid Session ID

Connection Lost

Best Practices