@soyeht/soyeht 0.1.1 → 0.2.0

package/README.md

@@ -7,7 +7,7 @@ Channel plugin for connecting the Soyeht Flutter mobile app to an OpenClaw gatew
 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 install @soyeht/soyeht@0.1.2 --pin
 openclaw plugins enable soyeht
 ```
 

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soyeht/soyeht",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "OpenClaw channel plugin for the Soyeht Flutter mobile app",
   "type": "module",
   "main": "src/index.ts",
@@ -38,9 +38,6 @@
     "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",

package/src/channel.ts

@@ -10,8 +10,38 @@ import {
   buildOutboundEnvelope,
   postToBackend,
 } from "./outbound.js";
+import { encryptEnvelopeV2 } from "./envelope-v2.js";
 import type { SecurityV2Deps } from "./service.js";
 
+// ---------------------------------------------------------------------------
+// Transport mode detection
+// ---------------------------------------------------------------------------
+
+type TransportMode = "direct" | "backend";
+
+function resolveTransportMode(
+  account: ResolvedSoyehtAccount,
+  v2deps?: SecurityV2Deps,
+): TransportMode {
+  const hasSession = v2deps?.sessions.has(account.accountId) ?? false;
+  const hasBackend = Boolean(account.backendBaseUrl && account.pluginAuthToken);
+  const hasSseSubscribers = v2deps?.outboundQueue.hasSubscribers(account.accountId) ?? false;
+
+  // Direct mode: active session + SSE client connected (or queue available)
+  if (hasSession && (hasSseSubscribers || !hasBackend)) {
+    return "direct";
+  }
+  // Backend mode: backend configured
+  if (hasBackend) {
+    return "backend";
+  }
+  // Default: direct (even without SSE subscriber — messages queue for later pickup)
+  if (hasSession) {
+    return "direct";
+  }
+  return "backend";
+}
+
 export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<ResolvedSoyehtAccount> {
   return {
     id: "soyeht",
@@ -44,15 +74,26 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
       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,
-      }),
+      isConfigured: (account) => {
+        // Direct mode: active V2 session is sufficient
+        const hasSession = v2deps?.sessions.has(account.accountId) ?? false;
+        if (hasSession) return true;
+        // Backend mode: backendBaseUrl + pluginAuthToken
+        return Boolean(account.backendBaseUrl && account.pluginAuthToken);
+      },
+      describeAccount: (account) => {
+        const mode = resolveTransportMode(account, v2deps);
+        return {
+          accountId: account.accountId,
+          enabled: account.enabled,
+          configured: Boolean(account.backendBaseUrl && account.pluginAuthToken) ||
+            (v2deps?.sessions.has(account.accountId) ?? false),
+          backendConfigured: Boolean(account.backendBaseUrl),
+          securityEnabled: account.security.enabled,
+          allowProactive: account.allowProactive,
+          transportMode: mode,
+        };
+      },
     },
 
     outbound: {
@@ -60,14 +101,6 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
 
       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) {
@@ -86,11 +119,25 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
           };
         }
 
+        const mode = resolveTransportMode(account, v2deps);
         const envelope = buildOutboundEnvelope(account.accountId, ctx.to, {
           contentType: "text",
           text: ctx.text,
         });
 
+        if (mode === "direct" && ratchetSession && v2deps) {
+          return enqueueOutbound(account, envelope, ratchetSession, v2deps);
+        }
+
+        // Backend mode (or no session for direct)
+        if (!account.backendBaseUrl) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: "no_backend_url" },
+          };
+        }
+
         return postToBackend(account.backendBaseUrl, account.pluginAuthToken, envelope, {
           ratchetSession,
           dhRatchetCfg: {
@@ -106,11 +153,11 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
 
       async sendMedia(ctx) {
         const account = resolveSoyehtAccount(ctx.cfg, ctx.accountId);
-        if (!account.backendBaseUrl || !ctx.mediaUrl) {
+        if (!ctx.mediaUrl) {
           return {
             channel: "soyeht",
             messageId: randomUUID(),
-            meta: { error: true, reason: !ctx.mediaUrl ? "no_media_url" : "no_backend_url" },
+            meta: { error: true, reason: "no_media_url" },
           };
         }
 
@@ -132,6 +179,7 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
           };
         }
 
+        const mode = resolveTransportMode(account, v2deps);
         const envelope = buildOutboundEnvelope(account.accountId, ctx.to, {
           contentType: "audio",
           renderStyle: "voice_note",
@@ -140,6 +188,19 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
           url: ctx.mediaUrl,
         });
 
+        if (mode === "direct" && ratchetSession && v2deps) {
+          return enqueueOutbound(account, envelope, ratchetSession, v2deps);
+        }
+
+        // Backend mode
+        if (!account.backendBaseUrl) {
+          return {
+            channel: "soyeht",
+            messageId: randomUUID(),
+            meta: { error: true, reason: "no_backend_url" },
+          };
+        }
+
         return postToBackend(account.backendBaseUrl, account.pluginAuthToken, envelope, {
           ratchetSession,
           dhRatchetCfg: {
@@ -155,3 +216,44 @@ export function createSoyehtChannel(v2deps?: SecurityV2Deps): ChannelPlugin<Reso
     },
   };
 }
+
+// ---------------------------------------------------------------------------
+// Encrypt + enqueue for direct mode (outbound via SSE)
+// ---------------------------------------------------------------------------
+
+import type { OutboundEnvelope } from "./types.js";
+import type { RatchetState } from "./ratchet.js";
+
+function enqueueOutbound(
+  account: ResolvedSoyehtAccount,
+  envelope: OutboundEnvelope,
+  ratchetSession: RatchetState,
+  v2deps: SecurityV2Deps,
+): { channel: string; messageId: string; meta?: Record<string, unknown> } {
+  if (ratchetSession.expiresAt < Date.now()) {
+    return {
+      channel: "soyeht",
+      messageId: envelope.deliveryId,
+      meta: { error: true, reason: "session_expired" },
+    };
+  }
+
+  const { envelope: v2env, updatedSession } = encryptEnvelopeV2({
+    session: ratchetSession,
+    accountId: envelope.accountId,
+    plaintext: JSON.stringify(envelope),
+    dhRatchetCfg: {
+      intervalMessages: account.security.dhRatchetIntervalMessages,
+      intervalMs: account.security.dhRatchetIntervalMs,
+    },
+  });
+  v2deps.sessions.set(account.accountId, updatedSession);
+
+  const entry = v2deps.outboundQueue.enqueue(account.accountId, v2env);
+
+  return {
+    channel: "soyeht",
+    messageId: envelope.deliveryId,
+    meta: { transportMode: "direct", queueEntryId: entry.id },
+  };
+}

package/src/config.ts

@@ -23,6 +23,7 @@ export type ResolvedSoyehtAccount = {
   enabled: boolean;
   backendBaseUrl: string;
   pluginAuthToken: string;
+  gatewayUrl: string;
   allowProactive: boolean;
   audio: {
     transcribeInbound: boolean;
@@ -133,6 +134,8 @@ export function resolveSoyehtAccount(
         : "",
     pluginAuthToken:
       typeof raw["pluginAuthToken"] === "string" ? raw["pluginAuthToken"] : "",
+    gatewayUrl:
+      typeof raw["gatewayUrl"] === "string" ? raw["gatewayUrl"] : "",
     allowProactive:
       typeof raw["allowProactive"] === "boolean" ? raw["allowProactive"] : false,
     audio: {

package/src/http.ts

@@ -43,6 +43,67 @@ async function readRawBodyBuffer(req: IncomingMessage): Promise<Buffer> {
 
 export { readRawBodyBuffer };
 
+// ---------------------------------------------------------------------------
+// Shared: process an inbound EnvelopeV2 (validate + decrypt + update session)
+// ---------------------------------------------------------------------------
+
+export type ProcessInboundResult =
+  | { ok: true; plaintext: string; accountId: string; envelope: EnvelopeV2 }
+  | { ok: false; status: number; error: string };
+
+export function processInboundEnvelope(
+  api: OpenClawPluginApi,
+  v2deps: SecurityV2Deps,
+  envelope: EnvelopeV2,
+  hintedAccountId?: string,
+): ProcessInboundResult {
+  const envelopeAccountId = normalizeAccountId(envelope.accountId);
+  if (hintedAccountId && hintedAccountId !== envelopeAccountId) {
+    return { ok: false, status: 401, error: "account_mismatch" };
+  }
+
+  const accountId = hintedAccountId ?? envelopeAccountId;
+  const session = v2deps.sessions.get(accountId);
+  if (!session) {
+    return { ok: false, status: 401, error: "session_required" };
+  }
+
+  if (session.expiresAt < Date.now()) {
+    return { ok: false, status: 401, error: "session_expired" };
+  }
+
+  if (session.accountId !== envelopeAccountId) {
+    return { ok: false, status: 401, error: "account_mismatch" };
+  }
+
+  const validation = validateEnvelopeV2(envelope, session);
+  if (!validation.valid) {
+    api.logger.warn("[soyeht] Envelope validation failed", { error: validation.error, accountId });
+    return { ok: false, status: 401, error: validation.error };
+  }
+
+  // Deep-clone session before decryption so in-place Buffer mutations
+  // cannot corrupt the stored session on failure.
+  const sessionClone = cloneRatchetSession(session);
+
+  let plaintext: string;
+  let updatedSession;
+  try {
+    const result = decryptEnvelopeV2({ session: sessionClone, envelope });
+    plaintext = result.plaintext;
+    updatedSession = result.updatedSession;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "decryption_failed";
+    api.logger.warn("[soyeht] Envelope decryption failed", { error: msg, accountId });
+    return { ok: false, status: 401, error: msg };
+  }
+
+  // Update session
+  v2deps.sessions.set(accountId, updatedSession);
+
+  return { ok: true, plaintext, accountId, envelope };
+}
+
 // ---------------------------------------------------------------------------
 // GET /soyeht/health
 // ---------------------------------------------------------------------------
@@ -54,7 +115,7 @@ export function healthHandler(_api: OpenClawPluginApi) {
 }
 
 // ---------------------------------------------------------------------------
-// POST /soyeht/webhook/deliver
+// POST /soyeht/webhook/deliver (legacy backend mode)
 // ---------------------------------------------------------------------------
 
 export function webhookHandler(
@@ -89,7 +150,6 @@ export function webhookHandler(
     try {
       const rawBody = await readRawBodyBuffer(req);
 
-      // Parse the envelope
       let envelope: EnvelopeV2;
       try {
         envelope = JSON.parse(rawBody.toString("utf8")) as EnvelopeV2;
@@ -98,60 +158,76 @@ export function webhookHandler(
         return;
       }
 
-      const envelopeAccountId = normalizeAccountId(envelope.accountId);
-      if (hintedAccountId && hintedAccountId !== envelopeAccountId) {
-        sendJson(res, 401, { ok: false, error: "account_mismatch" });
+      const result = processInboundEnvelope(api, v2deps, envelope, hintedAccountId);
+      if (!result.ok) {
+        sendJson(res, result.status, { ok: false, error: result.error });
         return;
       }
 
-      const accountId = hintedAccountId ?? envelopeAccountId;
-      const session = v2deps.sessions.get(accountId);
-      if (!session) {
-        sendJson(res, 401, { ok: false, error: "session_required" });
-        return;
-      }
+      api.logger.info("[soyeht] Webhook delivery received", { accountId: result.accountId });
+      sendJson(res, 200, { ok: true, received: true });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "unknown_error";
+      sendJson(res, 400, { ok: false, error: message });
+    }
+  };
+}
 
-      if (session.expiresAt < Date.now()) {
-        sendJson(res, 401, { ok: false, error: "session_expired" });
-        return;
-      }
+// ---------------------------------------------------------------------------
+// POST /soyeht/messages/inbound (direct mode — app → plugin → agent)
+// ---------------------------------------------------------------------------
+
+export function inboundHandler(
+  api: OpenClawPluginApi,
+  v2deps: SecurityV2Deps,
+) {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.method !== "POST") {
+      sendJson(res, 405, { ok: false, error: "method_not_allowed" });
+      return;
+    }
+
+    if (!v2deps.ready) {
+      sendJson(res, 503, { ok: false, error: "service_unavailable" });
+      return;
+    }
 
-      if (session.accountId !== envelopeAccountId) {
-        sendJson(res, 401, { ok: false, error: "account_mismatch" });
+    try {
+      const rawBody = await readRawBodyBuffer(req);
+
+      let envelope: EnvelopeV2;
+      try {
+        envelope = JSON.parse(rawBody.toString("utf8")) as EnvelopeV2;
+      } catch {
+        sendJson(res, 400, { ok: false, error: "invalid_json" });
         return;
       }
 
-      // Validate envelope (trust only the parsed body — no header overrides)
-      const validation = validateEnvelopeV2(envelope, session);
-      if (!validation.valid) {
-        api.logger.warn("[soyeht] Webhook validation failed", { error: validation.error, accountId });
-        sendJson(res, 401, { ok: false, error: validation.error });
+      const envelopeAccountId = normalizeAccountId(envelope.accountId);
+
+      // Rate limit per-account
+      const { allowed, retryAfterMs } = v2deps.rateLimiter.check(`inbound:${envelopeAccountId}`);
+      if (!allowed) {
+        res.setHeader("Retry-After", String(Math.ceil((retryAfterMs ?? 60_000) / 1000)));
+        sendJson(res, 429, { ok: false, error: "rate_limited" });
         return;
       }
 
-      // Deep-clone session before decryption so in-place Buffer mutations
-      // (rootKey.fill(0), chainKey.fill(0)) cannot corrupt the stored session on failure.
-      const sessionClone = cloneRatchetSession(session);
-
-      // Decrypt
-      let plaintext: string;
-      let updatedSession;
-      try {
-        const result = decryptEnvelopeV2({ session: sessionClone, envelope });
-        plaintext = result.plaintext;
-        updatedSession = result.updatedSession;
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : "decryption_failed";
-        api.logger.warn("[soyeht] Webhook decryption failed", { error: msg, accountId });
-        sendJson(res, 401, { ok: false, error: msg });
+      const result = processInboundEnvelope(api, v2deps, envelope);
+      if (!result.ok) {
+        sendJson(res, result.status, { ok: false, error: result.error });
         return;
       }
 
-      // Update session
-      v2deps.sessions.set(accountId, updatedSession);
+      // TODO: Push decrypted message to OpenClaw agent pipeline.
+      // The exact API depends on the OpenClaw runtime (e.g. api.channel.pushInbound()).
+      // For now the message is decrypted and the session is updated;
+      // wiring to the agent conversation will be done when the runtime API is known.
+      api.logger.info("[soyeht] Inbound message received (direct mode)", {
+        accountId: result.accountId,
+      });
 
-      api.logger.info("[soyeht] Webhook delivery received", { accountId });
-      sendJson(res, 200, { ok: true, received: true });
+      sendJson(res, 200, { ok: true, received: true, accountId: result.accountId });
     } catch (err) {
       const message = err instanceof Error ? err.message : "unknown_error";
       sendJson(res, 400, { ok: false, error: message });
@@ -159,6 +235,112 @@ export function webhookHandler(
   };
 }
 
+// ---------------------------------------------------------------------------
+// GET /soyeht/events/:accountId (SSE — plugin → app outbound stream)
+// ---------------------------------------------------------------------------
+
+const SSE_KEEPALIVE_MS = 30_000;
+
+export function sseHandler(
+  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) {
+      sendJson(res, 503, { ok: false, error: "service_unavailable" });
+      return;
+    }
+
+    // Extract accountId from URL: /soyeht/events/<accountId>
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const pathParts = url.pathname.split("/").filter(Boolean);
+    // Expected: ["soyeht", "events", "<accountId>"]
+    const accountId = pathParts.length >= 3 ? normalizeAccountId(pathParts[2]) : undefined;
+    if (!accountId) {
+      sendJson(res, 400, { ok: false, error: "missing_account_id" });
+      return;
+    }
+
+    // Auth: validate stream token from Authorization header or query param
+    const authHeader = req.headers.authorization ?? "";
+    const bearerMatch = authHeader.match(/^Bearer\s+(.+)$/i);
+    const token = bearerMatch?.[1] ?? url.searchParams.get("token") ?? "";
+
+    if (!token) {
+      sendJson(res, 401, { ok: false, error: "stream_token_required" });
+      return;
+    }
+
+    const tokenInfo = v2deps.outboundQueue.validateStreamToken(token);
+    if (!tokenInfo) {
+      sendJson(res, 401, { ok: false, error: "invalid_stream_token" });
+      return;
+    }
+
+    if (tokenInfo.accountId !== accountId) {
+      sendJson(res, 403, { ok: false, error: "token_account_mismatch" });
+      return;
+    }
+
+    // Verify active session exists
+    const session = v2deps.sessions.get(accountId);
+    if (!session || session.expiresAt < Date.now()) {
+      sendJson(res, 401, { ok: false, error: "session_required" });
+      return;
+    }
+
+    // SSE headers
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no",
+    });
+    res.write(`retry: 3000\n\n`);
+
+    api.logger.info("[soyeht] SSE client connected", { accountId });
+
+    // Subscribe to outbound queue
+    const subscription = v2deps.outboundQueue.subscribe(accountId);
+
+    // Keepalive ping
+    const keepalive = setInterval(() => {
+      if (!res.destroyed) {
+        res.write(`: ping\n\n`);
+      }
+    }, SSE_KEEPALIVE_MS);
+    if (typeof keepalive === "object" && "unref" in keepalive) {
+      keepalive.unref();
+    }
+
+    // Client disconnect
+    const onClose = () => {
+      clearInterval(keepalive);
+      subscription.unsubscribe();
+      api.logger.info("[soyeht] SSE client disconnected", { accountId });
+    };
+
+    req.on("close", onClose);
+    res.on("close", onClose);
+
+    // Stream messages
+    try {
+      for await (const entry of subscription) {
+        if (res.destroyed) break;
+        const data = JSON.stringify(entry.data);
+        res.write(`id: ${entry.id}\ndata: ${data}\n\n`);
+      }
+    } catch {
+      // subscription closed or error — clean up handled by onClose
+    }
+  };
+}
+
 // ---------------------------------------------------------------------------
 // POST /soyeht/livekit/token — stub
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -13,6 +13,8 @@ import {
   healthHandler,
   webhookHandler,
   livekitTokenHandler,
+  inboundHandler,
+  sseHandler,
 } from "./http.js";
 import {
   createSoyehtService,
@@ -71,7 +73,7 @@ const soyehtPlugin: OpenClawPluginDefinition = {
 
   configSchema: emptyPluginConfigSchema,
 
-  async register(api) {
+  register(api) {
     // V2 deps — identity/sessions loaded in service.start()
     const v2deps = createSecurityV2Deps();
 
@@ -110,6 +112,19 @@ const soyehtPlugin: OpenClawPluginDefinition = {
       handler: livekitTokenHandler(api),
     });
 
+    // Direct mode routes (app ↔ plugin)
+    api.registerHttpRoute({
+      path: "/soyeht/messages/inbound",
+      auth: "plugin",
+      handler: inboundHandler(api, v2deps),
+    });
+    api.registerHttpRoute({
+      path: "/soyeht/events",
+      auth: "plugin",
+      match: "prefix",
+      handler: sseHandler(api, v2deps),
+    });
+
     // Background service (manages state lifecycle)
     api.registerService(createSoyehtService(api, v2deps));