@soyeht/soyeht 0.2.9 → 0.2.11

package/README.md

@@ -2,16 +2,24 @@
 
 Channel plugin for connecting the Soyeht Flutter mobile app to an OpenClaw gateway.
 
-## Install in OpenClaw
+## V1 Architecture
 
-After this package is published to npm, install it on the OpenClaw host with:
+The app and the OpenClaw instance communicate over **HTTP + SSE** on a shared network (typically Tailscale).
+
+- **Inbound** (app → plugin): `POST {gatewayUrl}/soyeht/messages/inbound`
+- **Outbound** (plugin → app): `GET {gatewayUrl}/soyeht/events/{accountId}?token=...` (SSE)
+- **Pairing**: QR code scanned by the app, then HTTP handshake
+
+No WebRTC. No public domain required. Tailscale resolves connectivity.
+
+## Install
 
 ```bash
-openclaw plugins install @soyeht/soyeht@0.1.2 --pin
+openclaw plugins install @soyeht/soyeht --pin
 openclaw plugins enable soyeht
 ```
 
-Then verify:
+Verify:
 
 ```bash
 openclaw plugins list
@@ -19,9 +27,42 @@ openclaw plugins info soyeht
 openclaw plugins doctor
 ```
 
-## Minimal configuration
+## Configuration
+
+Set `gatewayUrl` to the URL accessible from the app. With Tailscale, this is your instance's Tailscale IP or MagicDNS hostname:
+
+```bash
+# Using Tailscale IP
+openclaw config set channels.soyeht.gatewayUrl "http://100.x.y.z:18789"
+
+# Or using MagicDNS
+openclaw config set channels.soyeht.gatewayUrl "http://my-machine.tailnet.ts.net:18789"
+
+openclaw config set channels.soyeht.enabled true
+openclaw gateway restart
+```
+
+The plugin will auto-generate a pairing QR on startup if no peers are paired.
+
+### Manual pairing
+
+```bash
+openclaw gateway call soyeht.security.pairing.start '{"accountId": "default", "allowOverwrite": true}'
+```
+
+### Full config reference
 
-Add a Soyeht account under `channels.soyeht.accounts.default`:
+```yaml
+channels:
+  soyeht:
+    enabled: true
+    gatewayUrl: "http://100.x.y.z:18789"  # required — your Tailscale/LAN URL
+    # Optional (only for legacy backend mode, not needed in V1):
+    # backendBaseUrl: "https://your-backend.example"
+    # pluginAuthToken: "your-token"
+```
+
+Or with named accounts:
 
 ```yaml
 channels:
@@ -29,45 +70,47 @@ channels:
     accounts:
       default:
         enabled: true
-        backendBaseUrl: https://your-backend.example
-        pluginAuthToken: your-plugin-auth-token
-        security:
-          enabled: true
+        gatewayUrl: "http://100.x.y.z:18789"
 ```
 
-## Local validation
+## App endpoints
 
-```bash
-npm ci
-npm run validate
-```
+All called by the Flutter app against `{gatewayUrl}`:
 
-## Publish to npm
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/soyeht/pairing/info?t={token}` | Fetch plugin keys for pairing |
+| `POST` | `/soyeht/pairing/pair` | Register peer + start handshake |
+| `POST` | `/soyeht/pairing/finish` | Complete handshake, get streamToken |
+| `POST` | `/soyeht/messages/inbound` | Send encrypted message to agent |
+| `GET` | `/soyeht/events/{accountId}?token={streamToken}` | SSE stream for agent replies |
+| `GET` | `/soyeht/health` | Health check (503 if not ready) |
 
-1. Make sure the package name and scope are available on npm.
-2. Log in:
+## QR format
+
+The compact QR URL emitted by the plugin:
 
-```bash
-npm login
 ```
+soyeht://pair?g={gatewayUrl}&t={pairingToken}&fp={fingerprint}
+```
+
+The app parses the URL, then calls the HTTP pairing endpoints above.
 
-3. Bump the version:
+## Local development
 
 ```bash
-npm version patch
+npm ci
+npm run validate    # typecheck + tests
+npm run test:watch  # vitest in watch mode
 ```
 
-This also syncs `openclaw.plugin.json`.
-
-4. Publish publicly:
+## Publish
 
 ```bash
+npm version patch   # bumps package.json + openclaw.plugin.json
 npm publish
 ```
 
-The package is configured with `publishConfig.access=public`, so the first publish of the scoped package does not need an extra `--access public`.
-
 ## Protocol docs
 
-- [Protocol](docs/PROTOCOL.md)
-- [Flutter agent prompt](docs/FLUTTER_AGENT_PROMPT.md)
+- [Security Protocol](docs/PROTOCOL.md)

package/docs/PROTOCOL.md

@@ -67,13 +67,14 @@ Request params:
 }
 ```
 
-Success payload:
+Success payload (QR V2 — when `gatewayUrl` is configured):
 
 ```json
 {
   "qrPayload": {
-    "version": 1,
+    "version": 2,
     "type": "soyeht_pairing_qr",
+    "gatewayUrl": "http://100.x.y.z:18789",
     "accountId": "default",
     "pairingToken": "<base64url-32-bytes>",
     "expiresAt": 1730000000000,
@@ -88,7 +89,13 @@ Success payload:
 }
 ```
 
-QR signature transcript:
+QR V2 signature transcript:
+
+```text
+pairing_qr_v2|{gatewayUrl}|{accountId}|{pairingToken}|{expiresAt}|{allowOverwrite?1:0}|{pluginIdentityKey}|{pluginDhKey}|{fingerprint}
+```
+
+QR V1 signature transcript (fallback — no `gatewayUrl`):
 
 ```text
 pairing_qr_v1|{accountId}|{pairingToken}|{expiresAt}|{allowOverwrite?1:0}|{pluginIdentityKey}|{pluginDhKey}|{fingerprint}
@@ -96,6 +103,20 @@ pairing_qr_v1|{accountId}|{pairingToken}|{expiresAt}|{allowOverwrite?1:0}|{plugi
 
 The signature is Ed25519 with the plugin identity private key.
 
+### Compact QR URL
+
+On service startup (auto-pairing) and via `pairing.start`, the plugin also emits a compact URL suitable for QR rendering:
+
+```
+soyeht://pair?g={gatewayUrl}&t={pairingToken}&fp={fingerprint}
+```
+
+The app parses this URL, then calls the HTTP pairing endpoints to fetch full key material and complete pairing:
+
+1. `GET {gatewayUrl}/soyeht/pairing/info?t={pairingToken}` — get plugin keys
+2. `POST {gatewayUrl}/soyeht/pairing/pair` — register peer + start handshake
+3. `POST {gatewayUrl}/soyeht/pairing/finish` — complete handshake, get streamToken
+
 ### `soyeht.security.pair`
 
 Purpose:
@@ -373,16 +394,59 @@ Webhook/envelope:
 - `direction_mismatch`
 - `version_mismatch`
 
-## Recommended Client Flow
-
-1. Plugin/host calls `soyeht.security.pairing.start`
-2. Plugin/host renders `qrText` as QR
-3. App scans QR and verifies it
-4. App generates long-term keys if needed
-5. App calls `soyeht.security.pair`
-6. App generates a fresh ephemeral X25519 key + nonce
-7. App calls `soyeht.security.handshake.init`
-8. App verifies `pluginSignature`
-9. App signs the same transcript and calls `soyeht.security.handshake.finish`
-10. App derives the same X3DH session locally and starts Envelope V2 messaging
+## V1 Transport: HTTP + SSE over Tailscale
+
+In V1, the app and plugin communicate over a shared network (Tailscale). All endpoints use the `gatewayUrl` from config (e.g., `http://100.x.y.z:18789`).
+
+### Inbound (app → plugin → agent)
+
+```
+POST {gatewayUrl}/soyeht/messages/inbound
+Content-Type: application/json
+
+{EnvelopeV2 JSON}
+```
+
+The plugin decrypts, responds `200`, then dispatches to the OpenClaw agent pipeline. The agent's reply is encrypted and pushed to the outbound SSE stream.
+
+### Outbound (plugin → app via SSE)
+
+```
+GET {gatewayUrl}/soyeht/events/{accountId}?token={streamToken}
+```
+
+Or with header:
+
+```
+GET {gatewayUrl}/soyeht/events/{accountId}
+Authorization: Bearer {streamToken}
+```
+
+The `streamToken` is returned by `POST /soyeht/pairing/finish` on successful handshake.
+
+SSE events are encrypted EnvelopeV2 payloads. The app decrypts using its ratchet session state.
+
+### Health check
+
+```
+GET {gatewayUrl}/soyeht/health
+```
+
+Returns `200` with state info when ready, `503` when not.
+
+## Recommended Client Flow (V1 — HTTP Pairing)
+
+1. Plugin auto-generates QR on startup (or via `soyeht.security.pairing.start`)
+2. App scans QR: `soyeht://pair?g={gatewayUrl}&t={pairingToken}&fp={fingerprint}`
+3. App calls `GET {gatewayUrl}/soyeht/pairing/info?t={pairingToken}`
+4. App verifies plugin keys and fingerprint
+5. App generates long-term keys if needed
+6. App calls `POST {gatewayUrl}/soyeht/pairing/pair` (registers peer + starts handshake)
+7. App verifies `pluginSignature` from response
+8. App signs the handshake transcript
+9. App calls `POST {gatewayUrl}/soyeht/pairing/finish`
+10. App receives `streamToken` and `sessionExpiresAt`
+11. App derives X3DH session and connects to SSE: `GET {gatewayUrl}/soyeht/events/{accountId}?token={streamToken}`
+12. App sends messages via `POST {gatewayUrl}/soyeht/messages/inbound`
+13. App receives agent replies via SSE stream
 

package/openclaw.plugin.json

@@ -5,7 +5,7 @@
   ],
   "name": "Soyeht",
   "description": "Channel plugin for the Soyeht Flutter mobile app",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soyeht/soyeht",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "OpenClaw channel plugin for the Soyeht Flutter mobile app",
   "type": "module",
   "main": "src/index.ts",

package/src/http.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawPluginApi, PluginRuntimeChannel } from "openclaw/plugin-sdk";
 import { normalizeAccountId, resolveSoyehtAccount } from "./config.js";
@@ -8,14 +9,22 @@ import type { SecurityV2Deps } from "./service.js";
 import { PLUGIN_VERSION } from "./version.js";
 import {
   base64UrlDecode,
+  base64UrlEncode,
   computeFingerprint,
+  ed25519Sign,
   generateX25519KeyPair,
   importEd25519PublicKey,
   importX25519PublicKey,
   ed25519Verify,
   isTimestampValid,
 } from "./crypto.js";
-import { buildPairingProofTranscript } from "./pairing.js";
+import {
+  buildPairingProofTranscript,
+  buildPairingQrTranscript,
+  buildPairingQrTranscriptV2,
+  resolveGatewayUrl,
+} from "./pairing.js";
+import { renderQrTerminal } from "./qr.js";
 import {
   buildHandshakeTranscript,
   signHandshakeTranscript,
@@ -537,6 +546,103 @@ function clearAccountSessionState(v2deps: SecurityV2Deps, accountId: string): vo
   }
 }
 
+// ---------------------------------------------------------------------------
+// GET /soyeht/pairing/start — generate a pairing QR via HTTP (no RPC needed)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_PAIRING_TTL_MS = 90_000;
+
+export function pairingStartHandler(
+  api: OpenClawPluginApi,
+  v2deps: SecurityV2Deps,
+) {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.method !== "GET") {
+      sendJson(res, 405, { ok: false, error: "method_not_allowed" });
+      return;
+    }
+
+    if (!v2deps.ready || !v2deps.identity) {
+      sendJson(res, 503, { ok: false, error: "service_unavailable" });
+      return;
+    }
+
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const accountId = normalizeAccountId(url.searchParams.get("accountId") ?? "default");
+    const allowOverwrite = url.searchParams.get("allowOverwrite") !== "false";
+    const format = url.searchParams.get("format") ?? "json";
+
+    const { allowed } = v2deps.rateLimiter.check(`pairing:start:http:${accountId}`);
+    if (!allowed) {
+      sendJson(res, 429, { ok: false, error: "rate_limited" });
+      return;
+    }
+
+    if (v2deps.peers.has(accountId) && !allowOverwrite) {
+      sendJson(res, 409, { ok: false, error: "peer_already_paired" });
+      return;
+    }
+
+    // Clear stale pairing sessions for this account
+    for (const [token, session] of v2deps.pairingSessions) {
+      if (session.accountId === accountId) {
+        v2deps.pairingSessions.delete(token);
+      }
+    }
+
+    const pairingToken = base64UrlEncode(randomBytes(32));
+    const expiresAt = Date.now() + DEFAULT_PAIRING_TTL_MS;
+    const fingerprint = computeFingerprint(v2deps.identity);
+
+    const cfg = await api.runtime.config.loadConfig();
+    const account = resolveSoyehtAccount(cfg, accountId);
+    const gatewayUrl = resolveGatewayUrl(api, account.gatewayUrl);
+
+    const basePayload = {
+      accountId,
+      pairingToken,
+      expiresAt,
+      allowOverwrite,
+      pluginIdentityKey: v2deps.identity.signKey.publicKeyB64,
+      pluginDhKey: v2deps.identity.dhKey.publicKeyB64,
+      fingerprint,
+    };
+
+    let qrPayload: Record<string, unknown>;
+    if (gatewayUrl) {
+      const transcript = buildPairingQrTranscriptV2({ gatewayUrl, ...basePayload });
+      const signature = base64UrlEncode(ed25519Sign(v2deps.identity.signKey.privateKey, transcript));
+      qrPayload = { version: 2, type: "soyeht_pairing_qr", gatewayUrl, ...basePayload, signature };
+    } else {
+      const transcript = buildPairingQrTranscript(basePayload);
+      const signature = base64UrlEncode(ed25519Sign(v2deps.identity.signKey.privateKey, transcript));
+      qrPayload = { version: 1, type: "soyeht_pairing_qr", ...basePayload, signature };
+    }
+
+    v2deps.pairingSessions.set(pairingToken, {
+      token: pairingToken,
+      accountId,
+      expiresAt,
+      allowOverwrite,
+    });
+
+    const qrUrl = `soyeht://pair?g=${gatewayUrl}&t=${pairingToken}&fp=${fingerprint}`;
+    api.logger.info("[soyeht] Pairing started via HTTP", { accountId, expiresAt });
+
+    if (format === "terminal") {
+      const rendered = renderQrTerminal(qrUrl);
+      const text = rendered
+        ? `\n${rendered}\n\n${qrUrl}\n\nExpires in ${DEFAULT_PAIRING_TTL_MS / 1000}s\n`
+        : `QR too large for terminal.\n\n${qrUrl}\n\nExpires in ${DEFAULT_PAIRING_TTL_MS / 1000}s\n`;
+      res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(text);
+      return;
+    }
+
+    sendJson(res, 200, { ok: true, qrUrl, qrPayload, expiresAt });
+  };
+}
+
 // ---------------------------------------------------------------------------
 // GET /soyeht/pairing/info?t=<pairingToken>
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -15,6 +15,7 @@ import {
   livekitTokenHandler,
   inboundHandler,
   sseHandler,
+  pairingStartHandler,
   pairingInfoHandler,
   pairingPairHandler,
   pairingFinishHandler,
@@ -131,6 +132,11 @@ const soyehtPlugin: OpenClawPluginDefinition = {
     });
 
     // HTTP pairing routes (app pairs via HTTP, no WebSocket needed)
+    api.registerHttpRoute({
+      path: "/soyeht/pairing/start",
+      auth: "plugin",
+      handler: pairingStartHandler(api, v2deps),
+    });
     api.registerHttpRoute({
       path: "/soyeht/pairing/info",
       auth: "plugin",

package/src/outbound-queue.ts

@@ -95,6 +95,19 @@ export function createOutboundQueue(opts: OutboundQueueOptions = {}): OutboundQu
     let waiting: ((value: IteratorResult<QueueEntry>) => void) | null = null;
     let closed = false;
 
+    // Drain backlog: snapshot current queue entries still within TTL.
+    // Done synchronously before registering live subscriber — no race in
+    // single-threaded Node.js, so no duplicates and no missed messages.
+    const now = Date.now();
+    const backlog = queues.get(accountId);
+    if (backlog) {
+      for (const entry of backlog) {
+        if (now - entry.enqueuedAt < ttlMs) {
+          pending.push(entry);
+        }
+      }
+    }
+
     const sub: Subscriber = {
       accountId,
       push(entry: QueueEntry) {

package/src/pairing.ts

@@ -119,7 +119,7 @@ function clearAccountSessionState(v2deps: SecurityV2Deps, accountId: string): vo
 // Resolve the gateway URL for QR V2
 // ---------------------------------------------------------------------------
 
-function resolveGatewayUrl(api: OpenClawPluginApi, configGatewayUrl: string): string {
+export function resolveGatewayUrl(api: OpenClawPluginApi, configGatewayUrl: string): string {
   // 1) Explicit config
   if (configGatewayUrl) return configGatewayUrl;
 

package/src/version.ts

@@ -1 +1 @@
-export const PLUGIN_VERSION = "0.2.9";
+export const PLUGIN_VERSION = "0.2.11";