@soyeht/soyeht 0.1.1 → 0.2.0

package/src/outbound-queue.ts

@@ -0,0 +1,230 @@
+import { randomBytes } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type QueueEntry = {
+  id: string;
+  accountId: string;
+  data: unknown; // EnvelopeV2 JSON
+  enqueuedAt: number;
+};
+
+type Subscriber = {
+  accountId: string;
+  push: (entry: QueueEntry) => void;
+  closed: boolean;
+};
+
+export type StreamTokenInfo = {
+  accountId: string;
+  expiresAt: number;
+};
+
+// ---------------------------------------------------------------------------
+// OutboundQueue — in-memory, bounded, per-accountId
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_PER_ACCOUNT = 1000;
+const DEFAULT_TTL_MS = 3_600_000; // 1 hour
+
+export type OutboundQueueOptions = {
+  maxPerAccount?: number;
+  ttlMs?: number;
+};
+
+export type OutboundQueue = {
+  enqueue(accountId: string, data: unknown): QueueEntry;
+  subscribe(accountId: string): AsyncIterable<QueueEntry> & { unsubscribe: () => void };
+  hasSubscribers(accountId: string): boolean;
+  prune(): number;
+  clear(): void;
+
+  // Stream token management (for SSE auth)
+  createStreamToken(accountId: string, expiresAt: number): string;
+  validateStreamToken(token: string): StreamTokenInfo | null;
+  revokeStreamTokensForAccount(accountId: string): void;
+};
+
+export function createOutboundQueue(opts: OutboundQueueOptions = {}): OutboundQueue {
+  const maxPerAccount = opts.maxPerAccount ?? DEFAULT_MAX_PER_ACCOUNT;
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+
+  const queues = new Map<string, QueueEntry[]>();
+  const subscribers = new Map<string, Set<Subscriber>>();
+  const streamTokens = new Map<string, StreamTokenInfo>();
+
+  function enqueue(accountId: string, data: unknown): QueueEntry {
+    const entry: QueueEntry = {
+      id: randomBytes(16).toString("hex"),
+      accountId,
+      data,
+      enqueuedAt: Date.now(),
+    };
+
+    let q = queues.get(accountId);
+    if (!q) {
+      q = [];
+      queues.set(accountId, q);
+    }
+    q.push(entry);
+
+    // FIFO overflow
+    while (q.length > maxPerAccount) {
+      q.shift();
+    }
+
+    // Push to live subscribers
+    const subs = subscribers.get(accountId);
+    if (subs) {
+      for (const sub of subs) {
+        if (!sub.closed) {
+          sub.push(entry);
+        }
+      }
+    }
+
+    return entry;
+  }
+
+  function subscribe(accountId: string): AsyncIterable<QueueEntry> & { unsubscribe: () => void } {
+    const pending: QueueEntry[] = [];
+    let waiting: ((value: IteratorResult<QueueEntry>) => void) | null = null;
+    let closed = false;
+
+    const sub: Subscriber = {
+      accountId,
+      push(entry: QueueEntry) {
+        if (closed) return;
+        if (waiting) {
+          const resolve = waiting;
+          waiting = null;
+          resolve({ value: entry, done: false });
+        } else {
+          pending.push(entry);
+        }
+      },
+      closed: false,
+    };
+
+    let subs = subscribers.get(accountId);
+    if (!subs) {
+      subs = new Set();
+      subscribers.set(accountId, subs);
+    }
+    subs.add(sub);
+
+    function unsubscribe() {
+      closed = true;
+      sub.closed = true;
+      const s = subscribers.get(accountId);
+      if (s) {
+        s.delete(sub);
+        if (s.size === 0) subscribers.delete(accountId);
+      }
+      if (waiting) {
+        waiting({ value: undefined as unknown as QueueEntry, done: true });
+        waiting = null;
+      }
+    }
+
+    return {
+      unsubscribe,
+      [Symbol.asyncIterator]() {
+        return {
+          next(): Promise<IteratorResult<QueueEntry>> {
+            if (closed) {
+              return Promise.resolve({ value: undefined as unknown as QueueEntry, done: true });
+            }
+            if (pending.length > 0) {
+              return Promise.resolve({ value: pending.shift()!, done: false });
+            }
+            return new Promise<IteratorResult<QueueEntry>>((resolve) => {
+              waiting = resolve;
+            });
+          },
+          return(): Promise<IteratorResult<QueueEntry>> {
+            unsubscribe();
+            return Promise.resolve({ value: undefined as unknown as QueueEntry, done: true });
+          },
+        };
+      },
+    };
+  }
+
+  function hasSubscribers(accountId: string): boolean {
+    const subs = subscribers.get(accountId);
+    return Boolean(subs && subs.size > 0);
+  }
+
+  function prune(): number {
+    const now = Date.now();
+    let pruned = 0;
+    for (const [accountId, q] of queues) {
+      const before = q.length;
+      const filtered = q.filter((e) => now - e.enqueuedAt < ttlMs);
+      pruned += before - filtered.length;
+      if (filtered.length === 0) {
+        queues.delete(accountId);
+      } else if (filtered.length !== before) {
+        queues.set(accountId, filtered);
+      }
+    }
+
+    // Prune expired stream tokens
+    for (const [token, info] of streamTokens) {
+      if (info.expiresAt < now) {
+        streamTokens.delete(token);
+      }
+    }
+
+    return pruned;
+  }
+
+  function clear(): void {
+    queues.clear();
+    for (const subs of subscribers.values()) {
+      for (const sub of subs) {
+        sub.closed = true;
+      }
+    }
+    subscribers.clear();
+    streamTokens.clear();
+  }
+
+  function createStreamToken(accountId: string, expiresAt: number): string {
+    const token = randomBytes(32).toString("hex");
+    streamTokens.set(token, { accountId, expiresAt });
+    return token;
+  }
+
+  function validateStreamToken(token: string): StreamTokenInfo | null {
+    const info = streamTokens.get(token);
+    if (!info) return null;
+    if (info.expiresAt < Date.now()) {
+      streamTokens.delete(token);
+      return null;
+    }
+    return info;
+  }
+
+  function revokeStreamTokensForAccount(accountId: string): void {
+    for (const [token, info] of streamTokens) {
+      if (info.accountId === accountId) {
+        streamTokens.delete(token);
+      }
+    }
+  }
+
+  return {
+    enqueue,
+    subscribe,
+    hasSubscribers,
+    prune,
+    clear,
+    createStreamToken,
+    validateStreamToken,
+    revokeStreamTokensForAccount,
+  };
+}

package/src/pairing.ts

@@ -10,7 +10,7 @@ import {
   importEd25519PublicKey,
   importX25519PublicKey,
 } from "./crypto.js";
-import { normalizeAccountId } from "./config.js";
+import { normalizeAccountId, resolveSoyehtAccount } from "./config.js";
 import { deleteSession, savePeer, type PeerIdentity } from "./identity.js";
 import { zeroBuffer } from "./ratchet.js";
 import type { SecurityV2Deps } from "./service.js";
@@ -26,6 +26,7 @@ function clampPairingTtlMs(value: unknown): number {
   return Math.min(Math.max(Math.trunc(value), MIN_PAIRING_TTL_MS), MAX_PAIRING_TTL_MS);
 }
 
+// V1 transcript (backward compat — no gatewayUrl)
 export function buildPairingQrTranscript(params: {
   accountId: string;
   pairingToken: string;
@@ -50,6 +51,33 @@ export function buildPairingQrTranscript(params: {
   );
 }
 
+// V2 transcript — includes gatewayUrl
+export function buildPairingQrTranscriptV2(params: {
+  gatewayUrl: string;
+  accountId: string;
+  pairingToken: string;
+  expiresAt: number;
+  allowOverwrite: boolean;
+  pluginIdentityKey: string;
+  pluginDhKey: string;
+  fingerprint: string;
+}): Buffer {
+  const {
+    gatewayUrl,
+    accountId,
+    pairingToken,
+    expiresAt,
+    allowOverwrite,
+    pluginIdentityKey,
+    pluginDhKey,
+    fingerprint,
+  } = params;
+  return Buffer.from(
+    `pairing_qr_v2|${gatewayUrl}|${accountId}|${pairingToken}|${expiresAt}|${allowOverwrite ? 1 : 0}|${pluginIdentityKey}|${pluginDhKey}|${fingerprint}`,
+    "utf8",
+  );
+}
+
 export function buildPairingProofTranscript(params: {
   accountId: string;
   pairingToken: string;
@@ -64,11 +92,11 @@ export function buildPairingProofTranscript(params: {
   );
 }
 
-function signPairingQrPayload(
+function signTranscript(
   privateKey: Parameters<typeof ed25519Sign>[0],
-  payload: Parameters<typeof buildPairingQrTranscript>[0],
+  transcript: Buffer,
 ): string {
-  return base64UrlEncode(ed25519Sign(privateKey, buildPairingQrTranscript(payload)));
+  return base64UrlEncode(ed25519Sign(privateKey, transcript));
 }
 
 function clearAccountSessionState(v2deps: SecurityV2Deps, accountId: string): void {
@@ -87,6 +115,27 @@ function clearAccountSessionState(v2deps: SecurityV2Deps, accountId: string): vo
   }
 }
 
+// ---------------------------------------------------------------------------
+// Resolve the gateway URL for QR V2
+// ---------------------------------------------------------------------------
+
+function resolveGatewayUrl(api: OpenClawPluginApi, configGatewayUrl: string): string {
+  // 1) Explicit config
+  if (configGatewayUrl) return configGatewayUrl;
+
+  // 2) Attempt auto-detection from runtime (if available)
+  const runtime = api.runtime as Record<string, unknown>;
+  if (typeof runtime["gatewayUrl"] === "string" && runtime["gatewayUrl"]) {
+    return runtime["gatewayUrl"];
+  }
+  if (typeof runtime["baseUrl"] === "string" && runtime["baseUrl"]) {
+    return runtime["baseUrl"];
+  }
+
+  // 3) Empty — the app will need to be configured manually
+  return "";
+}
+
 // ---------------------------------------------------------------------------
 // soyeht.security.identity — expose plugin public keys
 // ---------------------------------------------------------------------------
@@ -124,7 +173,7 @@ export function handleSecurityIdentity(
 // ---------------------------------------------------------------------------
 
 export function handleSecurityPairingStart(
-  _api: OpenClawPluginApi,
+  api: OpenClawPluginApi,
   v2deps: SecurityV2Deps,
 ): GatewayRequestHandler {
   return async ({ params, respond }) => {
@@ -163,9 +212,13 @@ export function handleSecurityPairingStart(
     const pairingToken = base64UrlEncode(randomBytes(32));
     const expiresAt = Date.now() + ttlMs;
     const fingerprint = computeFingerprint(v2deps.identity);
-    const payload = {
-      version: 1 as const,
-      type: "soyeht_pairing_qr" as const,
+
+    // Resolve gatewayUrl for QR V2
+    const cfg = await api.runtime.config.loadConfig();
+    const account = resolveSoyehtAccount(cfg, accountId);
+    const gatewayUrl = resolveGatewayUrl(api, account.gatewayUrl);
+
+    const basePayload = {
       accountId,
       pairingToken,
       expiresAt,
@@ -174,8 +227,31 @@ export function handleSecurityPairingStart(
       pluginDhKey: v2deps.identity.dhKey.publicKeyB64,
       fingerprint,
     };
-    const signature = signPairingQrPayload(v2deps.identity.signKey.privateKey, payload);
-    const qrPayload = { ...payload, signature };
+
+    let qrPayload: Record<string, unknown>;
+
+    if (gatewayUrl) {
+      // QR V2 — includes gatewayUrl
+      const transcript = buildPairingQrTranscriptV2({ gatewayUrl, ...basePayload });
+      const signature = signTranscript(v2deps.identity.signKey.privateKey, transcript);
+      qrPayload = {
+        version: 2,
+        type: "soyeht_pairing_qr",
+        gatewayUrl,
+        ...basePayload,
+        signature,
+      };
+    } else {
+      // QR V1 fallback — no gatewayUrl available
+      const transcript = buildPairingQrTranscript(basePayload);
+      const signature = signTranscript(v2deps.identity.signKey.privateKey, transcript);
+      qrPayload = {
+        version: 1,
+        type: "soyeht_pairing_qr",
+        ...basePayload,
+        signature,
+      };
+    }
 
     v2deps.pairingSessions.set(pairingToken, {
       token: pairingToken,

package/src/rpc.ts

@@ -9,11 +9,11 @@ import {
   normalizeAccountId,
 } from "./config.js";
 import {
-  deliverTextMessage,
   postToBackend,
   buildOutboundEnvelope,
   type PostToBackendOptions,
 } from "./outbound.js";
+import { encryptEnvelopeV2 } from "./envelope-v2.js";
 import type { TextMessagePayload } from "./types.js";
 import {
   base64UrlDecode,
@@ -115,14 +115,6 @@ export function handleNotify(
       return;
     }
 
-    if (!account.backendBaseUrl || !account.pluginAuthToken) {
-      respond(false, undefined, {
-        code: "NOT_CONFIGURED",
-        message: "Account is not fully configured",
-      });
-      return;
-    }
-
     const to = params["to"] as string;
     const text = params["text"] as string;
     if (!to || !text) {
@@ -133,54 +125,67 @@ export function handleNotify(
       return;
     }
 
-    if (account.security.enabled && v2deps) {
+    // Direct mode: encrypt and enqueue if V2 session exists
+    if (v2deps) {
       const ratchetSession = v2deps.sessions.get(account.accountId);
-      if (!ratchetSession) {
-        respond(false, undefined, {
-          code: "SESSION_REQUIRED",
-          message: "V2 session required for secure delivery",
+      if (ratchetSession) {
+        if (ratchetSession.expiresAt < Date.now()) {
+          respond(false, undefined, {
+            code: "SESSION_EXPIRED",
+            message: "V2 session has expired, re-handshake required",
+          });
+          return;
+        }
+
+        const message: TextMessagePayload = { contentType: "text", text };
+        const envelope = buildOutboundEnvelope(account.accountId, to, message);
+        const { envelope: v2env, updatedSession } = encryptEnvelopeV2({
+          session: ratchetSession,
+          accountId: account.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);
+        respond(true, {
+          deliveryId: envelope.deliveryId,
+          meta: { transportMode: "direct", queueEntryId: entry.id },
         });
         return;
       }
 
-      if (ratchetSession.expiresAt < Date.now()) {
+      if (account.security.enabled) {
         respond(false, undefined, {
-          code: "SESSION_EXPIRED",
-          message: "V2 session has expired, re-handshake required",
+          code: "SESSION_REQUIRED",
+          message: "V2 session required for secure delivery",
         });
         return;
       }
+    }
 
-      const message: TextMessagePayload = { contentType: "text", text };
-      const envelope = buildOutboundEnvelope(account.accountId, to, message);
-      const opts: PostToBackendOptions = {
-        ratchetSession,
-        dhRatchetCfg: {
-          intervalMessages: account.security.dhRatchetIntervalMessages,
-          intervalMs: account.security.dhRatchetIntervalMs,
-        },
-        onSessionUpdated: (updated) => v2deps.sessions.set(account.accountId, updated),
-        securityEnabled: true,
-      };
-      const result = await postToBackend(
-        account.backendBaseUrl,
-        account.pluginAuthToken,
-        envelope,
-        opts,
-      );
-      respond(true, { deliveryId: result.messageId, meta: result.meta });
+    // Backend mode fallback
+    if (!account.backendBaseUrl || !account.pluginAuthToken) {
+      respond(false, undefined, {
+        code: "NOT_CONFIGURED",
+        message: "Account is not fully configured (no session and no backend)",
+      });
       return;
     }
 
-    const result = await deliverTextMessage({
-      backendBaseUrl: account.backendBaseUrl,
-      pluginAuthToken: account.pluginAuthToken,
-      accountId: account.accountId,
-      sessionId: to,
-      to,
-      text,
-    });
-
+    const message: TextMessagePayload = { contentType: "text", text };
+    const envelope = buildOutboundEnvelope(account.accountId, to, message);
+    const opts: PostToBackendOptions = {
+      securityEnabled: false,
+    };
+    const result = await postToBackend(
+      account.backendBaseUrl,
+      account.pluginAuthToken,
+      envelope,
+      opts,
+    );
     respond(true, { deliveryId: result.messageId, meta: result.meta });
   };
 }
@@ -456,6 +461,10 @@ export function handleSecurityHandshakeFinish(
       });
     }
 
+    // Revoke old stream tokens and issue a fresh one for SSE auth
+    v2deps.outboundQueue.revokeStreamTokensForAccount(accountId);
+    const streamToken = v2deps.outboundQueue.createStreamToken(accountId, pending.sessionExpiresAt);
+
     api.logger.info("[soyeht] V2 handshake completed", { accountId });
 
     respond(true, {
@@ -463,6 +472,7 @@ export function handleSecurityHandshakeFinish(
       phase: "finish",
       complete: true,
       expiresAt: pending.sessionExpiresAt,
+      streamToken,
     });
   };
 }

package/src/service.ts

@@ -12,6 +12,7 @@ import { zeroBuffer } from "./ratchet.js";
 import { computeFingerprint, type X25519KeyPair } from "./crypto.js";
 import type { IdentityBundle, PeerIdentity } from "./identity.js";
 import type { RatchetState } from "./ratchet.js";
+import { createOutboundQueue, type OutboundQueue } from "./outbound-queue.js";
 
 const HEARTBEAT_INTERVAL_MS = 60_000; // 60s
 
@@ -27,6 +28,7 @@ export type SecurityV2Deps = {
   pendingHandshakes: Map<string, PendingHandshake>;
   nonceCache: NonceCache;
   rateLimiter: RateLimiter;
+  outboundQueue: OutboundQueue;
   ready: boolean;
   stateDir?: string;
 };
@@ -58,6 +60,7 @@ export function createSecurityV2Deps(): SecurityV2Deps {
     pendingHandshakes: new Map(),
     nonceCache: createNonceCache(),
     rateLimiter: createRateLimiter(),
+    outboundQueue: createOutboundQueue(),
     ready: false,
   };
 }
@@ -115,6 +118,7 @@ export function createSoyehtService(
           const now = Date.now();
           v2deps.nonceCache.prune();
           v2deps.rateLimiter.prune();
+          v2deps.outboundQueue.prune();
           for (const [token, session] of v2deps.pairingSessions) {
             if (session.expiresAt <= now) {
               v2deps.pairingSessions.delete(token);
@@ -168,6 +172,7 @@ export function createSoyehtService(
         v2deps.peers.clear();
         v2deps.pairingSessions.clear();
         v2deps.pendingHandshakes.clear();
+        v2deps.outboundQueue.clear();
         v2deps.ready = false;
       }