@contextableai/clawg-ui 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.1 (2026-02-05)
+
+### Fixed
+- Return HTTP 429 `rate_limit` error when max pending pairing requests (3) is reached, instead of returning an empty pairing code
+
+## 0.2.0 (2026-02-04)
+
+### Added
+- **Device pairing authentication** - Secure per-device access control
+  - HMAC-signed device tokens (no master token exposure)
+  - Pairing approval workflow (`openclaw pairing approve clawg-ui <code>`)
+  - New CLI command: `openclaw clawg-ui devices` - List approved devices
+
+### Changed
+- **Breaking:** Direct bearer token authentication using `OPENCLAW_GATEWAY_TOKEN` is now deprecated and no longer supported. All clients must use device pairing.
+
+### Security
+- Device tokens are HMAC-signed and do not expose the gateway's master secret
+- Pending pairing requests expire after 1 hour (max 3 per channel)
+- Each device requires explicit approval by the gateway owner
+
 ## 0.1.1 (2026-02-03)
 
 ### Changed

package/README.md

@@ -22,7 +22,7 @@ Then restart the gateway. The plugin auto-registers the `/v1/clawg-ui` endpoint
 
 The plugin registers as an OpenClaw channel and adds an HTTP route at `/v1/clawg-ui`. When an AG-UI client POSTs a `RunAgentInput` payload, the plugin:
 
-1. Authenticates the request using the gateway bearer token
+1. Authenticates the request using device pairing (see [Authentication](#authentication))
 2. Parses the AG-UI messages into an OpenClaw inbound context
 3. Routes to the appropriate agent via the gateway's standard routing
 4. Dispatches the message through the reply pipeline (same path as Telegram, Teams, etc.)
@@ -31,9 +31,9 @@ The plugin registers as an OpenClaw channel and adds an HTTP route at `/v1/clawg
 ```
 AG-UI Client                        OpenClaw Gateway
     |                                      |
-    |  POST /v1/agui (RunAgentInput)       |
+    |  POST /v1/clawg-ui (RunAgentInput)   |
     |------------------------------------->|
-    |                                      |  Auth (bearer token)
+    |                                      |  Auth (device token)
     |                                      |  Route to agent
     |                                      |  Dispatch inbound message
     |                                      |
@@ -60,15 +60,16 @@ AG-UI Client                        OpenClaw Gateway
 ### Prerequisites
 
 - OpenClaw gateway running (`openclaw gateway run`)
-- A gateway auth token configured (`OPENCLAW_GATEWAY_TOKEN` env var or `gateway.auth.token` in config)
+- A paired device token (see [Authentication](#authentication))
 
 ### curl
 
 ```bash
+# Using your device token (obtained through pairing)
 curl -N -X POST http://localhost:18789/v1/clawg-ui \
   -H "Content-Type: application/json" \
   -H "Accept: text/event-stream" \
-  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -H "Authorization: Bearer $CLAWG_UI_DEVICE_TOKEN" \
   -d '{
     "threadId": "thread-1",
     "runId": "run-1",
@@ -83,10 +84,13 @@ curl -N -X POST http://localhost:18789/v1/clawg-ui \
 ```typescript
 import { HttpAgent } from "@ag-ui/client";
 
+// Device token obtained through the pairing flow
+const deviceToken = process.env.CLAWG_UI_DEVICE_TOKEN;
+
 const agent = new HttpAgent({
   url: "http://localhost:18789/v1/clawg-ui",
   headers: {
-    Authorization: `Bearer ${process.env.OPENCLAW_GATEWAY_TOKEN}`,
+    Authorization: `Bearer ${deviceToken}`,
   },
 });
 
@@ -108,12 +112,15 @@ for await (const event of stream) {
 ```tsx
 import { CopilotKit } from "@copilotkit/react-core";
 
+// Device token obtained through the pairing flow
+const deviceToken = process.env.CLAWG_UI_DEVICE_TOKEN;
+
 function App() {
   return (
     <CopilotKit
       runtimeUrl="http://localhost:18789/v1/clawg-ui"
       headers={{
-        Authorization: `Bearer ${process.env.OPENCLAW_GATEWAY_TOKEN}`,
+        Authorization: `Bearer ${deviceToken}`,
       }}
     >
       {/* your app */}
@@ -162,24 +169,130 @@ The response is an SSE stream. Each event is a `data:` line containing a JSON ob
 
 ## Authentication
 
-The endpoint uses the same bearer token as the OpenClaw gateway. Set it via:
+clawg-ui uses **device pairing** to authenticate clients. This provides secure, per-device access control without exposing the gateway's master token.
+
+### Device Pairing Flow
+
+```
+┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
+│  Gateway Owner  │      │  OpenClaw Server │      │   AG-UI Client  │
+└────────┬────────┘      └────────┬─────────┘      └────────┬────────┘
+         │                        │                         │
+         │                        │  1. POST (no auth)      │
+         │                        │<────────────────────────│
+         │                        │                         │
+         │                        │  2. Return device token │
+         │                        │     + pairing code      │
+         │                        │────────────────────────>│
+         │                        │     403 pairing_pending │
+         │                        │     { pairingCode, token }
+         │                        │                         │
+         │              3. Share pairing code (out of band) │
+         │<─────────────────────────────────────────────────│
+         │                        │                         │
+    4. Approve device             │                         │
+         │  openclaw pairing approve clawg-ui ABCD1234      │
+         │───────────────────────>│                         │
+         │                        │                         │
+         │                        │  5. POST with device token
+         │                        │<────────────────────────│
+         │                        │     Authorization: Bearer <token>
+         │                        │                         │
+         │                        │  6. Success - SSE stream│
+         │                        │────────────────────────>│
+         │                        │                         │
+```
+
+### Step-by-Step Setup
+
+#### 1. Client initiates pairing
+
+The client sends a POST request without any authorization header:
+
+```bash
+curl -X POST http://localhost:18789/v1/clawg-ui \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Response (403):
+
+```json
+{
+  "error": {
+    "type": "pairing_pending",
+    "message": "Device pending approval",
+    "pairing": {
+      "pairingCode": "ABCD1234",
+      "token": "MmRlOTA0ODIt...b71d",
+      "instructions": "Save this token for use as a Bearer token and ask the owner to approve: openclaw pairing approve clawg-ui ABCD1234"
+    }
+  }
+}
+```
+
+The client must save the `token` for future requests.
 
-- Environment variable: `OPENCLAW_GATEWAY_TOKEN`
-- Config file: `gateway.auth.token`
+#### 2. Approve the device (gateway owner)
 
-Pass it in the `Authorization` header:
+The client shares the `pairingCode` with the gateway owner, who approves it:
 
+```bash
+# List pending pairing requests
+openclaw pairing list clawg-ui
+
+# Approve the device
+openclaw pairing approve clawg-ui ABCD1234
 ```
-Authorization: Bearer <token>
+
+#### 3. Client uses Bearer token
+
+Once approved, the client uses their Bearer token for all requests:
+
+```bash
+curl -N -X POST http://localhost:18789/v1/clawg-ui \
+  -H "Authorization: Bearer MmRlOTA0ODIt...b71d" \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Hello"}]}'
 ```
 
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `openclaw clawg-ui devices` | List approved devices |
+| `openclaw pairing list clawg-ui` | List pending pairing requests awaiting approval |
+| `openclaw pairing approve clawg-ui <code>` | Approve a device by its pairing code |
+
+### Error Responses
+
+| Status | Type | Meaning |
+|--------|------|---------|
+| 401 | `unauthorized` | Invalid device token |
+| 403 | `pairing_pending` | No auth (initiates pairing) or valid token but device not yet approved |
+
+### Deprecated: Direct Bearer Token
+
+> **Deprecated:** Previous versions (0.1.x) allowed using the gateway's master token (`OPENCLAW_GATEWAY_TOKEN`) directly. This approach is **no longer supported**. All clients must now use device pairing.
+>
+> Old (deprecated):
+> ```
+> Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN
+> ```
+>
+> New (required):
+> ```
+> POST without Authorization header  # Initiates pairing
+> Authorization: Bearer <device-token>  # After approval
+> ```
+
 ## Agent routing
 
 The plugin uses OpenClaw's standard agent routing. By default, messages route to the `main` agent. To target a specific agent, set the `X-OpenClaw-Agent-Id` header:
 
 ```bash
 curl -N -X POST http://localhost:18789/v1/clawg-ui \
-  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -H "Authorization: Bearer $CLAWG_UI_DEVICE_TOKEN" \
   -H "X-OpenClaw-Agent-Id: my-agent" \
   -d '{"messages":[{"role":"user","content":"Hello"}]}'
 ```
@@ -188,11 +301,12 @@ curl -N -X POST http://localhost:18789/v1/clawg-ui \
 
 Non-streaming errors return JSON:
 
-| Status | Meaning |
-|---|---|
-| 400 | Invalid request (missing messages, bad JSON) |
-| 401 | Unauthorized (missing or invalid token) |
-| 405 | Method not allowed (only POST accepted) |
+| Status | Type | Meaning |
+|---|---|---|
+| 400 | `invalid_request_error` | Invalid request (missing messages, bad JSON) |
+| 401 | `unauthorized` | Invalid device token |
+| 403 | `pairing_pending` | No auth header (initiates pairing) or valid token but device not yet approved |
+| 405 | — | Method not allowed (only POST accepted) |
 
 Streaming errors emit a `RUN_ERROR` event and close the connection.
 

package/index.ts

@@ -1,4 +1,5 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { Command } from "commander";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { randomUUID } from "node:crypto";
 import { EventType } from "@ag-ui/core";
@@ -82,6 +83,31 @@ const plugin = {
         });
       }
     });
+
+    // CLI commands for device management
+    api.registerCli(
+      ({ program }: { program: Command }) => {
+        const clawgUi = program
+          .command("clawg-ui")
+          .description("CLAWG-UI (AG-UI) channel commands");
+
+        clawgUi
+          .command("devices")
+          .description("List approved devices")
+          .action(async () => {
+            const devices = await api.runtime.channel.pairing.readAllowFromStore("clawg-ui");
+            if (devices.length === 0) {
+              console.log("No approved devices.");
+              return;
+            }
+            console.log("Approved devices:");
+            for (const deviceId of devices) {
+              console.log(`  ${deviceId}`);
+            }
+          });
+      },
+      { commands: ["clawg-ui"] },
+    );
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextableai/clawg-ui",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "AG-UI protocol channel plugin for OpenClaw — connect CopilotKit and AG-UI clients to your OpenClaw gateway",
   "type": "module",
   "license": "MIT",

package/src/channel.ts

@@ -30,4 +30,8 @@ export const aguiChannelPlugin: ChannelPlugin<ResolvedAguiAccount> = {
     }),
     defaultAccountId: () => "default",
   },
+  pairing: {
+    idLabel: "clawgUiDeviceId",
+    normalizeAllowEntry: (entry: string) => entry.replace(/^clawg-ui:/i, "").toLowerCase(),
+  },
 };

package/src/http-handler.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { randomUUID } from "node:crypto";
+import { randomUUID, createHmac, timingSafeEqual } from "node:crypto";
 import { EventType } from "@ag-ui/core";
 import type { RunAgentInput, Message } from "@ag-ui/core";
 import { EventEncoder } from "@ag-ui/encoder";
@@ -13,6 +13,7 @@ import {
   clearClientToolCalled,
   clearClientToolNames,
 } from "./tool-store.js";
+import { aguiChannelPlugin } from "./channel.js";
 
 // ---------------------------------------------------------------------------
 // Lightweight HTTP helpers (no internal imports needed)
@@ -32,7 +33,7 @@ function sendMethodNotAllowed(res: ServerResponse) {
 }
 
 function sendUnauthorized(res: ServerResponse) {
-  sendJson(res, 401, { error: { message: "Unauthorized", type: "unauthorized" } });
+  sendJson(res, 401, { error: { message: "Authentication required", type: "unauthorized" } });
 }
 
 function readJsonBody(req: IncomingMessage, maxBytes: number): Promise<unknown> {
@@ -67,6 +68,51 @@ function getBearerToken(req: IncomingMessage): string | undefined {
   return raw.slice(7).trim() || undefined;
 }
 
+// ---------------------------------------------------------------------------
+// HMAC-signed device token utilities
+// ---------------------------------------------------------------------------
+
+function createDeviceToken(secret: string, deviceId: string): string {
+  const encodedId = Buffer.from(deviceId).toString("base64url");
+  const signature = createHmac("sha256", secret).update(deviceId).digest("hex").slice(0, 32);
+  return `${encodedId}.${signature}`;
+}
+
+function verifyDeviceToken(token: string, secret: string): string | null {
+  const dotIndex = token.indexOf(".");
+  if (dotIndex <= 0 || dotIndex >= token.length - 1) {
+    return null;
+  }
+
+  const encodedId = token.slice(0, dotIndex);
+  const providedSig = token.slice(dotIndex + 1);
+
+  try {
+    const deviceId = Buffer.from(encodedId, "base64url").toString("utf-8");
+
+    // Validate it looks like a UUID
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(deviceId)) {
+      return null;
+    }
+
+    const expectedSig = createHmac("sha256", secret).update(deviceId).digest("hex").slice(0, 32);
+
+    // Constant-time comparison
+    if (providedSig.length !== expectedSig.length) {
+      return null;
+    }
+    const providedBuf = Buffer.from(providedSig);
+    const expectedBuf = Buffer.from(expectedSig);
+    if (!timingSafeEqual(providedBuf, expectedBuf)) {
+      return null;
+    }
+
+    return deviceId;
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Extract text from AG-UI messages
 // ---------------------------------------------------------------------------
@@ -134,35 +180,19 @@ function buildBodyFromMessages(messages: Message[]): {
 }
 
 // ---------------------------------------------------------------------------
-// Token-based auth check against gateway config
+// Gateway secret resolution
 // ---------------------------------------------------------------------------
 
-function authenticateRequest(
-  req: IncomingMessage,
-  api: OpenClawPluginApi,
-): boolean {
-  const token = getBearerToken(req);
-  if (!token) {
-    return false;
-  }
-  // Read the configured gateway token from config
+function getGatewaySecret(api: OpenClawPluginApi): string | null {
   const gatewayAuth = api.config.gateway?.auth;
-  const configuredToken =
+  const secret =
     (gatewayAuth as Record<string, unknown> | undefined)?.token ??
     process.env.OPENCLAW_GATEWAY_TOKEN ??
     process.env.CLAWDBOT_GATEWAY_TOKEN;
-  if (typeof configuredToken !== "string" || !configuredToken) {
-    return false;
+  if (typeof secret === "string" && secret) {
+    return secret;
   }
-  // Constant-time comparison
-  if (token.length !== configuredToken.length) {
-    return false;
-  }
-  let mismatch = 0;
-  for (let i = 0; i < token.length; i++) {
-    mismatch |= token.charCodeAt(i) ^ configuredToken.charCodeAt(i);
-  }
-  return mismatch === 0;
+  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -182,11 +212,95 @@ export function createAguiHttpHandler(api: OpenClawPluginApi) {
       return;
     }
 
-    // Auth
-    if (!authenticateRequest(req, api)) {
+    // Get gateway secret for HMAC operations
+    const gatewaySecret = getGatewaySecret(api);
+    if (!gatewaySecret) {
+      sendJson(res, 500, {
+        error: { message: "Gateway not configured", type: "server_error" },
+      });
+      return;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Authentication: No auth (pairing initiation) or Device token
+    // ---------------------------------------------------------------------------
+    let deviceId: string;
+
+    const bearerToken = getBearerToken(req);
+
+    if (!bearerToken) {
+      // No auth header: initiate pairing
+      // Generate new device ID
+      deviceId = randomUUID();
+
+      // Add to pending via OpenClaw pairing API - returns a pairing code for approval
+      const { code: pairingCode } = await runtime.channel.pairing.upsertPairingRequest({
+        channel: "clawg-ui",
+        id: deviceId,
+        pairingAdapter: aguiChannelPlugin.pairing,
+      });
+
+      // Rate limit reached - max pending requests exceeded
+      if (!pairingCode) {
+        sendJson(res, 429, {
+          error: {
+            type: "rate_limit",
+            message: "Too many pending pairing requests. Please wait for existing requests to expire (10 minutes) or ask the owner to approve/reject them.",
+          },
+        });
+        return;
+      }
+
+      // Generate signed device token
+      const deviceToken = createDeviceToken(gatewaySecret, deviceId);
+
+      // Return pairing pending response with device token and pairing code
+      sendJson(res, 403, {
+        error: {
+          type: "pairing_pending",
+          message: "Device pending approval",
+          pairing: {
+            pairingCode,
+            token: deviceToken,
+            instructions: `Save this token for use as a Bearer token and ask the owner to approve: openclaw pairing approve clawg-ui ${pairingCode}`,
+          },
+        },
+      });
+      return;
+    }
+
+    // Device token flow: verify HMAC signature, extract device ID
+    const extractedDeviceId = verifyDeviceToken(bearerToken, gatewaySecret);
+    if (!extractedDeviceId) {
       sendUnauthorized(res);
       return;
     }
+    deviceId = extractedDeviceId;
+
+    // ---------------------------------------------------------------------------
+    // Pairing check: verify device is approved
+    // ---------------------------------------------------------------------------
+    const storeAllowFrom = await runtime.channel.pairing
+      .readAllowFromStore("clawg-ui")
+      .catch(() => []);
+    const normalizedAllowFrom = storeAllowFrom.map((e) =>
+      e.replace(/^clawg-ui:/i, "").toLowerCase(),
+    );
+    const allowed = normalizedAllowFrom.includes(deviceId.toLowerCase());
+
+    if (!allowed) {
+      sendJson(res, 403, {
+        error: {
+          type: "pairing_pending",
+          message: "Device pending approval. Ask the owner to approve using the pairing code from your initial pairing response.",
+        },
+      });
+      return;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Device approved - proceed with request
+    // ---------------------------------------------------------------------------
 
     // Parse body
     let body: unknown;
@@ -257,12 +371,12 @@ export function createAguiHttpHandler(api: OpenClawPluginApi) {
     const messageId = `msg-${randomUUID()}`;
     let messageStarted = false;
 
-    const writeEvent = (event: Record<string, unknown>) => {
+    const writeEvent = (event: { type: EventType } & Record<string, unknown>) => {
       if (closed) {
         return;
       }
       try {
-        res.write(encoder.encode(event));
+        res.write(encoder.encode(event as Parameters<typeof encoder.encode>[0]));
       } catch {
         // Client may have disconnected
         closed = true;
@@ -316,13 +430,13 @@ export function createAguiHttpHandler(api: OpenClawPluginApi) {
       Body: envelopedBody,
       RawBody: messageBody,
       CommandBody: messageBody,
-      From: `clawg-ui:${threadId}`,
+      From: `clawg-ui:${deviceId}`,
       To: "clawg-ui",
       SessionKey: sessionKey,
       ChatType: "direct",
       ConversationLabel: "AG-UI",
       SenderName: "AG-UI Client",
-      SenderId: `clawg-ui-${threadId}`,
+      SenderId: deviceId,
       Provider: "clawg-ui" as const,
       Surface: "clawg-ui" as const,
       MessageSid: runId,