npm package: @snap-protocol/openclaw-snap-bridge
Description: OpenClaw plugin that bridges enterprise SSO/LDAP identities to SNAP P2TR addresses and relays IM messages
Author: WilliamPenrose
Latest version: 0.2.0

# @snap-protocol/openclaw-snap-bridge

An OpenClaw plugin that bridges enterprise IM identities (Slack, DingTalk, Teams) to SNAP P2TR addresses via the SNAP Bridge protocol. It handles identity binding, certificate lifecycle, and bidirectional message relay over a single WebSocket connection.

## How It Works

```
Enterprise IM (DingTalk/Slack/Teams)
        │
        ▼
┌─────────────────┐     WebSocket      ┌────────────────────────┐
│  Bridge Server   │◄──────────────────►│  This Plugin (Agent)   │
│  (SNAP Bridge)   │  ca/bind           │  ┌──────────────────┐  │
│                  │  ca/cert_request    │  │ BridgeConnection │  │
│  Routes messages │  message/send      │  │ BindingManager   │  │
│  between IM and  │  message/stream    │  │ CertManager      │  │
│  SNAP agents     │  bridge/send       │  │ InboundRouter    │  │
│                  │  tasks/get|cancel   │  │ ResponseHandler  │  │
└─────────────────┘                     └────────────────────────┘
                                                    │
                                                    ▼
                                               OpenClaw Core
```

## Installation

```bash
npm install @snap-protocol/openclaw-snap-bridge
```

Register the plugin in your OpenClaw configuration:

```jsonc
// ~/.openclaw/openclaw.json (plugins section)
{
  "plugins": {
    "entries": {
      "openclaw-snap-bridge": {
        "config": {
          "bridgeUrl": "wss://bridge.example.com/snap-bridge"
        }
      }
    }
  }
}
```

**Local bridge:** If you are running the bridge locally for development, use `ws://127.0.0.1:9090` instead. See [docs/development.md](docs/development.md) for the full local development workflow.

## Configuration

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `bridgeUrl` | Yes | — | WebSocket URL of the SNAP Bridge server |
| `privateKey` | No | auto-generated | 64-character lowercase hex key for BIP-340 Schnorr signing |
| `privateKeyPath` | No | — | Path to key file (takes precedence over `privateKey`) |
| `streamingEnabled` | No | `true` | Advertise `message/stream` capability to the Bridge |

**Private key resolution order:**
1. `privateKeyPath` — reads key from file
2. `privateKey` — uses inline value
3. Neither set — auto-generates and stores at `~/.openclaw/openclaw-snap-bridge/key.hex`

## Quick Start

### Option A: Run the demo (no Bridge Server needed)

The demo starts a local mock Bridge and walks through the full lifecycle:

```bash
npx tsx examples/demo.ts
```

You will see: connection → pairing → certificate issuance → inbound message handling → proactive outbound message. Wait ~45 seconds to observe automatic certificate renewal.

### Option B: Connect to a real Bridge Server

1. Get your Bridge Server URL and a pairing code from your admin
2. Configure the plugin:

```jsonc
{
  "bridgeUrl": "wss://bridge.example.com/snap-bridge"
}
```

3. On first connection, pass the pairing code via the gateway start options. The plugin will:
   - Connect to the Bridge via WebSocket
   - Send `ca/bind` with the pairing code
   - Receive your identity binding (enterprise user ↔ SNAP address)
   - Request and cache a SNAP-IC certificate (auto-renews at 75% lifetime)

4. Once paired, the plugin automatically reconnects and re-binds on disconnection.

## API Overview

The plugin exposes three adapters to OpenClaw:

**Gateway** — Manages the WebSocket lifecycle
- `start({ config, pairingCode })` — Connect and pair with Bridge
- `stop()` — Disconnect and clean up
- `isConnected()` — Connection status

**Outbound** — Send messages to IM users
- `sendText({ text, target })` — Send a proactive message via `bridge/send`

**Config** — Account management
- `listAccountIds()` — List bound identities
- `resolveAccount(cfg, accountId)` — Get binding details for an identity

## Supported Protocol Methods

| Method | Direction | Description |
|--------|-----------|-------------|
| `ca/bind` | Agent → Bridge | Pair agent with enterprise identity |
| `ca/cert_request` | Agent → Bridge | Request/renew SNAP-IC certificate |
| `message/send` | Bridge → Agent | Deliver IM message for sync processing |
| `message/stream` | Bridge → Agent | Deliver IM message for streaming response |
| `bridge/send` | Agent → Bridge | Proactive outbound message to IM user |
| `tasks/get` | Bridge → Agent | Query task status |
| `tasks/cancel` | Bridge → Agent | Cancel a running task |

## Guide

- **[docs/guide.md](docs/guide.md)** — Step-by-step walkthrough for end users connecting to a remote Bridge server
- **[docs/development.md](docs/development.md)** — Local development setup with a local Bridge server

## License

MIT