@soyeht/soyeht 0.1.1

package/README.md

@@ -0,0 +1,73 @@
+# Soyeht OpenClaw Plugin
+
+Channel plugin for connecting the Soyeht Flutter mobile app to an OpenClaw gateway.
+
+## Install in OpenClaw
+
+After this package is published to npm, install it on the OpenClaw host with:
+
+```bash
+openclaw plugins install @soyeht/soyeht@0.1.1 --pin
+openclaw plugins enable soyeht
+```
+
+Then verify:
+
+```bash
+openclaw plugins list
+openclaw plugins info soyeht
+openclaw plugins doctor
+```
+
+## Minimal configuration
+
+Add a Soyeht account under `channels.soyeht.accounts.default`:
+
+```yaml
+channels:
+  soyeht:
+    accounts:
+      default:
+        enabled: true
+        backendBaseUrl: https://your-backend.example
+        pluginAuthToken: your-plugin-auth-token
+        security:
+          enabled: true
+```
+
+## Local validation
+
+```bash
+npm ci
+npm run validate
+```
+
+## Publish to npm
+
+1. Make sure the package name and scope are available on npm.
+2. Log in:
+
+```bash
+npm login
+```
+
+3. Bump the version:
+
+```bash
+npm version patch
+```
+
+This also syncs `openclaw.plugin.json`.
+
+4. Publish publicly:
+
+```bash
+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)

package/docs/PROTOCOL.md

@@ -0,0 +1,388 @@
+# Soyeht Plugin Security Protocol
+
+This document describes the pairing and secure-session contract currently implemented by the plugin.
+
+## Scope
+
+The security flow has 3 phases:
+
+1. QR pairing bootstrap
+2. Two-step authenticated X3DH handshake
+3. Envelope V2 messaging with symmetric and DH ratchet state
+
+The canonical implementation lives in:
+
+- `src/pairing.ts`
+- `src/rpc.ts`
+- `src/x3dh.ts`
+- `src/envelope-v2.ts`
+- `src/ratchet.ts`
+
+## Encoding Rules
+
+- All binary fields are base64url without padding.
+- All timestamps are Unix epoch milliseconds.
+- `accountId` should be normalized to lowercase and trimmed.
+- Nonces must be base64url and decode to 16-64 bytes.
+
+## Long-Term Keys
+
+Plugin:
+
+- Ed25519 identity key pair
+- X25519 static DH key pair
+
+App:
+
+- Ed25519 identity key pair
+- X25519 static DH key pair
+
+The app should generate and persist its long-term keys locally. Do not send or embed app private keys in QR codes.
+
+## Fingerprint
+
+Fingerprint algorithm:
+
+- `SHA-256(signPubRaw || dhPubRaw)`
+- truncate to the first 16 bytes
+- hex encode lowercase
+
+The plugin implementation is in `src/crypto.ts`.
+
+## RPC Methods
+
+### `soyeht.security.pairing.start`
+
+Purpose:
+
+- Called by the host/plugin side to create a short-lived pairing payload for QR rendering.
+
+Request params:
+
+```json
+{
+  "accountId": "default",
+  "allowOverwrite": false,
+  "ttlMs": 90000
+}
+```
+
+Success payload:
+
+```json
+{
+  "qrPayload": {
+    "version": 1,
+    "type": "soyeht_pairing_qr",
+    "accountId": "default",
+    "pairingToken": "<base64url-32-bytes>",
+    "expiresAt": 1730000000000,
+    "allowOverwrite": false,
+    "pluginIdentityKey": "<base64url-32-bytes>",
+    "pluginDhKey": "<base64url-32-bytes>",
+    "fingerprint": "<32-char-hex>",
+    "signature": "<base64url-ed25519-signature>"
+  },
+  "qrText": "{...same JSON stringified...}",
+  "expiresAt": 1730000000000
+}
+```
+
+QR signature transcript:
+
+```text
+pairing_qr_v1|{accountId}|{pairingToken}|{expiresAt}|{allowOverwrite?1:0}|{pluginIdentityKey}|{pluginDhKey}|{fingerprint}
+```
+
+The signature is Ed25519 with the plugin identity private key.
+
+### `soyeht.security.pair`
+
+Purpose:
+
+- Called by the app after scanning the QR to register its public keys and consume the one-time `pairingToken`.
+
+Request params:
+
+```json
+{
+  "accountId": "default",
+  "pairingToken": "<from QR>",
+  "appIdentityKey": "<base64url-ed25519-public-key>",
+  "appDhKey": "<base64url-x25519-public-key>",
+  "appSignature": "<base64url-ed25519-signature>"
+}
+```
+
+App pairing proof transcript:
+
+```text
+pairing_proof_v1|{accountId}|{pairingToken}|{expiresAt}|{appIdentityKey}|{appDhKey}
+```
+
+The app signs this transcript with its Ed25519 identity private key.
+
+Success payload:
+
+```json
+{
+  "accountId": "default",
+  "handshakeRequired": true,
+  "pluginIdentityKey": "<base64url-32-bytes>",
+  "pluginDhKey": "<base64url-32-bytes>",
+  "fingerprint": "<32-char-hex>"
+}
+```
+
+Important behavior:
+
+- `pairingToken` is single-use.
+- Expired tokens are rejected.
+- If `allowOverwrite=true`, existing peer and session state for that account may be replaced.
+- On peer replacement, old session state is cleared.
+
+### `soyeht.security.handshake.init`
+
+Purpose:
+
+- Step 1 of the secure-session bootstrap.
+
+Request params:
+
+```json
+{
+  "accountId": "default",
+  "appEphemeralKey": "<base64url-x25519-public-key>",
+  "nonce": "<base64url-random-16-to-64-bytes>",
+  "timestamp": 1730000000000
+}
+```
+
+Behavior:
+
+- Validates peer exists
+- Validates nonce/timestamp
+- Rejects nonce reuse
+- Generates plugin ephemeral X25519 key
+- Builds the full handshake transcript
+- Signs it with the plugin Ed25519 identity key
+- Stores a pending handshake challenge in memory
+
+Success payload:
+
+```json
+{
+  "version": 2,
+  "phase": "init",
+  "complete": false,
+  "pluginEphemeralKey": "<base64url-x25519-public-key>",
+  "nonce": "<same nonce>",
+  "timestamp": 1730000000000,
+  "serverTimestamp": 1730000000100,
+  "challengeExpiresAt": 1730000030100,
+  "expiresAt": 1730086400100,
+  "pluginSignature": "<base64url-ed25519-signature>"
+}
+```
+
+Full handshake transcript:
+
+```text
+x3dh_v2|{accountId}|{appEphemeralKey}|{pluginEphemeralKey}|{nonce}|{timestamp}|{expiresAt}
+```
+
+### `soyeht.security.handshake.finish`
+
+Purpose:
+
+- Step 2 of the secure-session bootstrap.
+
+Request params:
+
+```json
+{
+  "version": 2,
+  "accountId": "default",
+  "nonce": "<same nonce from init>",
+  "appSignature": "<base64url-ed25519-signature>"
+}
+```
+
+The app signs the full handshake transcript returned implicitly by `handshake.init`:
+
+```text
+x3dh_v2|{accountId}|{appEphemeralKey}|{pluginEphemeralKey}|{nonce}|{timestamp}|{expiresAt}
+```
+
+Success payload:
+
+```json
+{
+  "version": 2,
+  "phase": "finish",
+  "complete": true,
+  "expiresAt": 1730086400100
+}
+```
+
+Important behavior:
+
+- The plugin verifies `appSignature` against the app identity key registered during pairing.
+- The pending handshake must still be unexpired.
+- On success, the plugin creates and stores a ratchet session for that account.
+
+### Legacy alias
+
+`soyeht.security.handshake` is currently registered as a compatibility alias for `soyeht.security.handshake.init`.
+
+New clients should use:
+
+- `soyeht.security.handshake.init`
+- `soyeht.security.handshake.finish`
+
+## App-Side Verification Requirements
+
+After scanning the QR:
+
+1. Parse `qrPayload`
+2. Check `type == "soyeht_pairing_qr"`
+3. Check `expiresAt > now`
+4. Verify the QR signature using `pluginIdentityKey`
+5. Recompute fingerprint from `pluginIdentityKey` + `pluginDhKey` and compare with `fingerprint`
+
+After `handshake.init`:
+
+1. Build the full handshake transcript exactly as above
+2. Verify `pluginSignature` using the plugin Ed25519 identity public key from the paired plugin
+3. Only then sign the transcript with the app Ed25519 identity private key
+4. Send `handshake.finish`
+
+## X3DH Derivation
+
+Plugin/responder side implementation:
+
+- `DH1 = X25519(pluginStaticDhPriv, appEphemeralPub)`
+- `DH2 = X25519(pluginEphemeralPriv, appStaticDhPub)`
+- `DH3 = X25519(pluginEphemeralPriv, appEphemeralPub)`
+- `ikm = DH1 || DH2 || DH3`
+- `root = HKDF-SHA256(ikm, nonceBytes, "soyeht-v2-root", 32)`
+- `pluginSend = HKDF-SHA256(root, empty, "soyeht-v2-chain-send", 32)`
+- `pluginRecv = HKDF-SHA256(root, empty, "soyeht-v2-chain-recv", 32)`
+
+App/initiator side must derive the same root but swap directional chains:
+
+- `DH1 = X25519(appEphemeralPriv, pluginStaticDhPub)`
+- `DH2 = X25519(appStaticDhPriv, pluginEphemeralPub)`
+- `DH3 = X25519(appEphemeralPriv, pluginEphemeralPub)`
+- `ikm = DH1 || DH2 || DH3`
+- `root = HKDF-SHA256(ikm, nonceBytes, "soyeht-v2-root", 32)`
+- `appSend = HKDF-SHA256(root, empty, "soyeht-v2-chain-recv", 32)`
+- `appRecv = HKDF-SHA256(root, empty, "soyeht-v2-chain-send", 32)`
+
+Reference:
+
+- `src/x3dh.ts`
+- `test/protocol-v2-integration.test.ts`
+
+## Envelope V2
+
+Envelope shape:
+
+```json
+{
+  "v": 2,
+  "accountId": "default",
+  "direction": "app_to_plugin",
+  "counter": 0,
+  "timestamp": 1730000000000,
+  "dhRatchetKey": "<optional base64url x25519 public key>",
+  "ciphertext": "<base64url>",
+  "iv": "<base64url 12 bytes>",
+  "tag": "<base64url 16 bytes>"
+}
+```
+
+AAD string:
+
+```text
+{v}|{accountId}|{direction}|{counter}|{timestamp}
+```
+
+Symmetric ratchet step:
+
+- `messageKey = HKDF-SHA256(chainKey, empty, "soyeht-v2-msg-key", 32)`
+- `nextChainKey = HKDF-SHA256(chainKey, empty, "soyeht-v2-chain-advance", 32)`
+
+Encryption:
+
+- AES-256-GCM
+- key = `messageKey`
+- iv = random 12 bytes
+- aad = UTF-8 bytes of the AAD string above
+
+Direction rules:
+
+- App -> plugin envelopes must use `direction = "app_to_plugin"`
+- Plugin -> app envelopes use `direction = "plugin_to_app"`
+
+## App State To Persist
+
+Persist on the app side:
+
+- app Ed25519 identity key pair
+- app X25519 static DH key pair
+- paired plugin public keys
+- fingerprint
+- current ratchet session state
+  - root key
+  - send chain key + counter
+  - recv chain key + counter
+  - current app ephemeral DH key
+  - peer last ephemeral DH key
+  - createdAt / expiresAt
+
+Do not persist used pairing tokens.
+
+## Common Error Codes
+
+Pairing:
+
+- `PAIRING_REQUIRED`
+- `PAIRING_EXPIRED`
+- `PAIRING_ACCOUNT_MISMATCH`
+- `PEER_ALREADY_PAIRED`
+- `INVALID_SIGNATURE`
+- `INVALID_KEY`
+
+Handshake:
+
+- `PEER_NOT_FOUND`
+- `INVALID_NONCE`
+- `NONCE_REUSED`
+- `TIMESTAMP_OUT_OF_RANGE`
+- `HANDSHAKE_NOT_FOUND`
+- `HANDSHAKE_EXPIRED`
+- `INVALID_SIGNATURE`
+
+Webhook/envelope:
+
+- `session_required`
+- `session_expired`
+- `account_mismatch`
+- `counter_mismatch`
+- `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
+

package/openclaw.plugin.json

@@ -0,0 +1,14 @@
+{
+  "id": "soyeht",
+  "channels": [
+    "soyeht"
+  ],
+  "name": "Soyeht",
+  "description": "Channel plugin for the Soyeht Flutter mobile app",
+  "version": "0.1.1",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@soyeht/soyeht",
+  "version": "0.1.1",
+  "description": "OpenClaw channel plugin for the Soyeht Flutter mobile app",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src/",
+    "docs/PROTOCOL.md",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "channel": {
+      "id": "soyeht",
+      "label": "Soyeht",
+      "selectionLabel": "Soyeht (Flutter app)",
+      "blurb": "Connects a Soyeht Flutter app to OpenClaw with QR-based secure pairing."
+    },
+    "install": {
+      "npmSpec": "@soyeht/soyeht",
+      "defaultChoice": "npm"
+    }
+  },
+  "scripts": {
+    "check:package": "node scripts/check-package-metadata.mjs",
+    "validate": "npm run check:package && npm run typecheck && npm test",
+    "pack:check": "npm pack --dry-run",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run validate && npm run pack:check",
+    "version": "node scripts/sync-plugin-manifest-version.mjs"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/channel.ts

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+import type { ResolvedSoyehtAccount } from "./config.js";
+import {
+  resolveSoyehtAccount,
+  listSoyehtAccountIds,
+} from "./config.js";
+import { SoyehtChannelConfigSchema } from "./types.js";
+import {
+  buildOutboundEnvelope,
+  postToBackend,
+} from "./outbound.js";
+import type { SecurityV2Deps } from "./service.js";
+
+export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<ResolvedSoyehtAccount> {
+  return {
+    id: "soyeht",
+
+    meta: {
+      id: "soyeht",
+      label: "Soyeht",
+      selectionLabel: "Soyeht (Mobile App)",
+      docsPath: "/channels/soyeht",
+      blurb:
+        "Connect the Soyeht Flutter mobile app to exchange text, audio, and file messages.",
+      systemImage: "iphone",
+    },
+
+    capabilities: {
+      chatTypes: ["direct"],
+      media: true,
+    },
+
+    reload: {
+      configPrefixes: ["channels.soyeht"],
+    },
+
+    configSchema: {
+      schema: SoyehtChannelConfigSchema,
+    },
+
+    config: {
+      listAccountIds: (cfg) => listSoyehtAccountIds(cfg),
+      resolveAccount: (cfg, accountId) => resolveSoyehtAccount(cfg, accountId),
+      defaultAccountId: () => "default",
+      isEnabled: (account) => account.enabled,
+      isConfigured: (account) => Boolean(account.backendBaseUrl && account.pluginAuthToken),
+      describeAccount: (account) => ({
+        accountId: account.accountId,
+        enabled: account.enabled,
+        configured: Boolean(account.backendBaseUrl && account.pluginAuthToken),
+        backendConfigured: Boolean(account.backendBaseUrl),
+        securityEnabled: account.security.enabled,
+        allowProactive: account.allowProactive,
+      }),
+    },
+
+    outbound: {
+      deliveryMode: "direct",
+
+      async sendText(ctx) {
+        const account = resolveSoyehtAccount(ctx.cfg, ctx.accountId);
+        if (!account.backendBaseUrl) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: "no_backend_url" },
+          };
+        }
+
+        const ratchetSession = v2deps?.sessions.get(account.accountId);
+
+        if (account.security.enabled && !ratchetSession) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: "session_required" },
+          };
+        }
+
+        if (ratchetSession && ratchetSession.expiresAt < Date.now()) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: "session_expired" },
+          };
+        }
+
+        const envelope = buildOutboundEnvelope(account.accountId, ctx.to, {
+          contentType: "text",
+          text: ctx.text,
+        });
+
+        return postToBackend(account.backendBaseUrl, account.pluginAuthToken, envelope, {
+          ratchetSession,
+          dhRatchetCfg: {
+            intervalMessages: account.security.dhRatchetIntervalMessages,
+            intervalMs: account.security.dhRatchetIntervalMs,
+          },
+          onSessionUpdated: (updated) => {
+            v2deps?.sessions.set(account.accountId, updated);
+          },
+          securityEnabled: account.security.enabled,
+        });
+      },
+
+      async sendMedia(ctx) {
+        const account = resolveSoyehtAccount(ctx.cfg, ctx.accountId);
+        if (!account.backendBaseUrl || !ctx.mediaUrl) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: !ctx.mediaUrl ? "no_media_url" : "no_backend_url" },
+          };
+        }
+
+        const ratchetSession = v2deps?.sessions.get(account.accountId);
+
+        if (account.security.enabled && !ratchetSession) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: "session_required" },
+          };
+        }
+
+        if (ratchetSession && ratchetSession.expiresAt < Date.now()) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: "session_expired" },
+          };
+        }
+
+        const envelope = buildOutboundEnvelope(account.accountId, ctx.to, {
+          contentType: "audio",
+          renderStyle: "voice_note",
+          mimeType: "audio/wav",
+          filename: "voice.wav",
+          url: ctx.mediaUrl,
+        });
+
+        return postToBackend(account.backendBaseUrl, account.pluginAuthToken, envelope, {
+          ratchetSession,
+          dhRatchetCfg: {
+            intervalMessages: account.security.dhRatchetIntervalMessages,
+            intervalMs: account.security.dhRatchetIntervalMs,
+          },
+          onSessionUpdated: (updated) => {
+            v2deps?.sessions.set(account.accountId, updated);
+          },
+          securityEnabled: account.security.enabled,
+        });
+      },
+    },
+  };
+}