@soyeht/soyeht 0.1.1

package/src/rpc.ts

@@ -0,0 +1,503 @@
+import type {
+  GatewayRequestHandler,
+  OpenClawPluginApi,
+} from "openclaw/plugin-sdk";
+import { SOYEHT_CAPABILITIES } from "./types.js";
+import {
+  resolveSoyehtAccount,
+  listSoyehtAccountIds,
+  normalizeAccountId,
+} from "./config.js";
+import {
+  deliverTextMessage,
+  postToBackend,
+  buildOutboundEnvelope,
+  type PostToBackendOptions,
+} from "./outbound.js";
+import type { TextMessagePayload } from "./types.js";
+import {
+  base64UrlDecode,
+  generateX25519KeyPair,
+  importEd25519PublicKey,
+  importX25519PublicKey,
+  isTimestampValid,
+} from "./crypto.js";
+import {
+  buildHandshakeTranscript,
+  performX3DH,
+  signHandshakeTranscript,
+  verifyHandshakeTranscript,
+} from "./x3dh.js";
+import { saveSession } from "./identity.js";
+import { zeroBuffer, type RatchetState } from "./ratchet.js";
+import type { SecurityV2Deps } from "./service.js";
+import { PLUGIN_VERSION } from "./version.js";
+
+const MIN_HANDSHAKE_TOLERANCE_MS = 30_000;
+const MAX_HANDSHAKE_TOLERANCE_MS = 120_000;
+
+function buildPendingHandshakeKey(accountId: string, nonce: string): string {
+  return `${accountId}:${nonce}`;
+}
+
+function isWellFormedNonce(nonce: string): boolean {
+  try {
+    const decoded = base64UrlDecode(nonce);
+    return decoded.length >= 16 && decoded.length <= 64;
+  } catch {
+    return false;
+  }
+}
+
+function clearExistingSession(v2deps: SecurityV2Deps, accountId: string): void {
+  const existing = v2deps.sessions.get(accountId);
+  if (!existing) return;
+  zeroBuffer(existing.rootKey);
+  zeroBuffer(existing.sending.chainKey);
+  zeroBuffer(existing.receiving.chainKey);
+  v2deps.sessions.delete(accountId);
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.status
+// ---------------------------------------------------------------------------
+
+export function handleStatus(api: OpenClawPluginApi): GatewayRequestHandler {
+  return async ({ respond }) => {
+    const cfg = await api.runtime.config.loadConfig();
+    const accountIds = listSoyehtAccountIds(cfg);
+    const accounts = accountIds.map((id) => {
+      const account = resolveSoyehtAccount(cfg, id);
+      return {
+        accountId: id,
+        enabled: account.enabled,
+        configured: Boolean(account.backendBaseUrl && account.pluginAuthToken),
+      };
+    });
+
+    respond(true, {
+      plugin: "soyeht",
+      version: PLUGIN_VERSION,
+      accounts,
+      capabilities: SOYEHT_CAPABILITIES,
+    });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.capabilities
+// ---------------------------------------------------------------------------
+
+export function handleCapabilities(_api: OpenClawPluginApi): GatewayRequestHandler {
+  return async ({ respond }) => {
+    respond(true, SOYEHT_CAPABILITIES);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.notify — proactive outbound text
+// ---------------------------------------------------------------------------
+
+export function handleNotify(
+  api: OpenClawPluginApi,
+  v2deps?: SecurityV2Deps,
+): GatewayRequestHandler {
+  return async ({ params, respond }) => {
+    const cfg = await api.runtime.config.loadConfig();
+    const accountId = (params["accountId"] as string) ?? undefined;
+    const account = resolveSoyehtAccount(cfg, accountId);
+
+    if (!account.allowProactive) {
+      respond(false, undefined, {
+        code: "PROACTIVE_DISABLED",
+        message: "Proactive notifications are disabled for this account",
+      });
+      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) {
+      respond(false, undefined, {
+        code: "INVALID_PARAMS",
+        message: "Missing required params: to, text",
+      });
+      return;
+    }
+
+    if (account.security.enabled && v2deps) {
+      const ratchetSession = v2deps.sessions.get(account.accountId);
+      if (!ratchetSession) {
+        respond(false, undefined, {
+          code: "SESSION_REQUIRED",
+          message: "V2 session required for secure delivery",
+        });
+        return;
+      }
+
+      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 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 });
+      return;
+    }
+
+    const result = await deliverTextMessage({
+      backendBaseUrl: account.backendBaseUrl,
+      pluginAuthToken: account.pluginAuthToken,
+      accountId: account.accountId,
+      sessionId: to,
+      to,
+      text,
+    });
+
+    respond(true, { deliveryId: result.messageId, meta: result.meta });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.livekit.prepare — V2 stub
+// ---------------------------------------------------------------------------
+
+export function handleLiveKitPrepare(_api: OpenClawPluginApi): GatewayRequestHandler {
+  return async ({ respond }) => {
+    respond(true, {
+      enabled: false,
+      reason: "livekit_not_enabled",
+      voiceContractVersion: 1,
+      pipeline: "stt->llm->tts",
+    });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.security.handshake(.init) — step 1 of a two-step authenticated X3DH
+// ---------------------------------------------------------------------------
+
+export function handleSecurityHandshake(
+  api: OpenClawPluginApi,
+  v2deps: SecurityV2Deps,
+): GatewayRequestHandler {
+  return async ({ params, respond }) => {
+    if (!v2deps.ready) {
+      respond(false, undefined, { code: "NOT_READY", message: "Service not ready" });
+      return;
+    }
+    if (!v2deps.identity) {
+      respond(false, undefined, { code: "NO_IDENTITY", message: "Identity not initialized" });
+      return;
+    }
+
+    const accountId = normalizeAccountId(params["accountId"] as string | undefined);
+    const cfg = await api.runtime.config.loadConfig();
+    const account = resolveSoyehtAccount(cfg, accountId);
+    const { allowed } = v2deps.rateLimiter.check(`handshake:init:${accountId}`, account.security.rateLimit);
+    if (!allowed) {
+      respond(false, undefined, { code: "RATE_LIMITED", message: "Too many requests" });
+      return;
+    }
+
+    const appEphemeralKey = params["appEphemeralKey"] as string | undefined;
+    const nonce = params["nonce"] as string | undefined;
+    const timestamp = params["timestamp"] as number | undefined;
+
+    if (!appEphemeralKey || !nonce || typeof timestamp !== "number") {
+      respond(false, undefined, {
+        code: "INVALID_PARAMS",
+        message: "Missing required params: accountId, appEphemeralKey, nonce, timestamp",
+      });
+      return;
+    }
+
+    if (!isWellFormedNonce(nonce)) {
+      respond(false, undefined, { code: "INVALID_NONCE", message: "nonce_must_be_base64url_16_to_64_bytes" });
+      return;
+    }
+
+    const peer = v2deps.peers.get(accountId);
+    if (!peer) {
+      respond(false, undefined, {
+        code: "PEER_NOT_FOUND",
+        message: "Peer not registered. Complete QR pairing first.",
+      });
+      return;
+    }
+
+    try {
+      importX25519PublicKey(appEphemeralKey);
+    } catch {
+      respond(false, undefined, { code: "INVALID_KEY", message: "Invalid appEphemeralKey" });
+      return;
+    }
+
+    const handshakeTolerance = Math.min(account.security.timestampToleranceMs, MAX_HANDSHAKE_TOLERANCE_MS);
+    const tolerance = Math.max(handshakeTolerance, MIN_HANDSHAKE_TOLERANCE_MS);
+    if (!isTimestampValid(timestamp, tolerance)) {
+      respond(false, undefined, { code: "TIMESTAMP_OUT_OF_RANGE", message: "timestamp_out_of_range" });
+      return;
+    }
+
+    if (!v2deps.nonceCache.add(`handshake:${accountId}:${nonce}`)) {
+      respond(false, undefined, { code: "NONCE_REUSED", message: "nonce_reused" });
+      return;
+    }
+
+    for (const [key, pending] of v2deps.pendingHandshakes) {
+      if (pending.accountId === accountId) {
+        v2deps.pendingHandshakes.delete(key);
+      }
+    }
+
+    const now = Date.now();
+    const challengeExpiresAt = now + tolerance;
+    const sessionExpiresAt = now + account.security.sessionMaxAgeMs;
+    const pluginEphemeralKey = generateX25519KeyPair();
+    const transcript = buildHandshakeTranscript({
+      accountId,
+      appEphKeyB64: appEphemeralKey,
+      pluginEphKeyB64: pluginEphemeralKey.publicKeyB64,
+      nonce,
+      timestamp,
+      expiresAt: sessionExpiresAt,
+    });
+    const pluginSignature = signHandshakeTranscript(
+      v2deps.identity.signKey.privateKey,
+      transcript,
+    );
+
+    const pendingKey = buildPendingHandshakeKey(accountId, nonce);
+    v2deps.pendingHandshakes.set(pendingKey, {
+      key: pendingKey,
+      accountId,
+      nonce,
+      appEphemeralKey,
+      pluginEphemeralKey,
+      transcript,
+      challengeExpiresAt,
+      sessionExpiresAt,
+    });
+
+    api.logger.info("[soyeht] V2 handshake init accepted", { accountId });
+
+    respond(true, {
+      version: 2,
+      phase: "init",
+      complete: false,
+      pluginEphemeralKey: pluginEphemeralKey.publicKeyB64,
+      nonce,
+      timestamp,
+      serverTimestamp: now,
+      challengeExpiresAt,
+      expiresAt: sessionExpiresAt,
+      pluginSignature,
+    });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.security.handshake.finish — step 2 of the authenticated X3DH
+// ---------------------------------------------------------------------------
+
+export function handleSecurityHandshakeFinish(
+  api: OpenClawPluginApi,
+  v2deps: SecurityV2Deps,
+): GatewayRequestHandler {
+  return async ({ params, respond }) => {
+    if (!v2deps.ready) {
+      respond(false, undefined, { code: "NOT_READY", message: "Service not ready" });
+      return;
+    }
+    if (!v2deps.identity) {
+      respond(false, undefined, { code: "NO_IDENTITY", message: "Identity not initialized" });
+      return;
+    }
+
+    const accountId = normalizeAccountId(params["accountId"] as string | undefined);
+    const nonce = params["nonce"] as string | undefined;
+    const appSignature = params["appSignature"] as string | undefined;
+    if (!nonce || !appSignature) {
+      respond(false, undefined, {
+        code: "INVALID_PARAMS",
+        message: "Missing required params: accountId, nonce, appSignature",
+      });
+      return;
+    }
+
+    const cfg = await api.runtime.config.loadConfig();
+    const account = resolveSoyehtAccount(cfg, accountId);
+    const { allowed } = v2deps.rateLimiter.check(`handshake:finish:${accountId}`, account.security.rateLimit);
+    if (!allowed) {
+      respond(false, undefined, { code: "RATE_LIMITED", message: "Too many requests" });
+      return;
+    }
+
+    const pendingKey = buildPendingHandshakeKey(accountId, nonce);
+    const pending = v2deps.pendingHandshakes.get(pendingKey);
+    if (!pending) {
+      respond(false, undefined, {
+        code: "HANDSHAKE_NOT_FOUND",
+        message: "No pending handshake found. Start a new handshake first.",
+      });
+      return;
+    }
+
+    if (pending.challengeExpiresAt <= Date.now()) {
+      v2deps.pendingHandshakes.delete(pendingKey);
+      respond(false, undefined, {
+        code: "HANDSHAKE_EXPIRED",
+        message: "Pending handshake expired. Start a new handshake first.",
+      });
+      return;
+    }
+
+    const peer = v2deps.peers.get(accountId);
+    if (!peer) {
+      respond(false, undefined, {
+        code: "PEER_NOT_FOUND",
+        message: "Peer not registered. Complete QR pairing first.",
+      });
+      return;
+    }
+
+    let appIdentityPub;
+    try {
+      appIdentityPub = importEd25519PublicKey(peer.identityKeyB64);
+    } catch {
+      respond(false, undefined, {
+        code: "INVALID_PEER_KEY",
+        message: "Stored peer identity key is invalid",
+      });
+      return;
+    }
+
+    if (!verifyHandshakeTranscript(appIdentityPub, pending.transcript, appSignature)) {
+      respond(false, undefined, { code: "INVALID_SIGNATURE", message: "App signature verification failed" });
+      return;
+    }
+
+    let appEphemeralPub;
+    try {
+      appEphemeralPub = importX25519PublicKey(pending.appEphemeralKey);
+    } catch {
+      v2deps.pendingHandshakes.delete(pendingKey);
+      respond(false, undefined, { code: "INVALID_KEY", message: "Stored appEphemeralKey is invalid" });
+      return;
+    }
+
+    let peerStaticDhPub;
+    try {
+      peerStaticDhPub = importX25519PublicKey(peer.dhKeyB64);
+    } catch {
+      respond(false, undefined, {
+        code: "INVALID_PEER_KEY",
+        message: "Stored peer DH key is invalid",
+      });
+      return;
+    }
+
+    const x3dhResult = await performX3DH({
+      myStaticDhKey: v2deps.identity.dhKey,
+      myEphemeralKey: pending.pluginEphemeralKey,
+      peerStaticDhPub,
+      peerEphemeralPub: appEphemeralPub,
+      nonce,
+    });
+
+    clearExistingSession(v2deps, accountId);
+
+    const session: RatchetState = {
+      accountId,
+      rootKey: x3dhResult.rootKey,
+      sending: { chainKey: x3dhResult.sendChainKey, counter: 0 },
+      receiving: { chainKey: x3dhResult.recvChainKey, counter: 0 },
+      myCurrentEphDhKey: pending.pluginEphemeralKey,
+      peerLastEphDhKeyB64: pending.appEphemeralKey,
+      dhRatchetSendCount: 0,
+      dhRatchetRecvCount: 0,
+      createdAt: Date.now(),
+      expiresAt: pending.sessionExpiresAt,
+    };
+
+    v2deps.sessions.set(accountId, session);
+    v2deps.pendingHandshakes.delete(pendingKey);
+    if (v2deps.stateDir) {
+      await saveSession(v2deps.stateDir, session).catch((err) => {
+        api.logger.error("[soyeht] Failed to persist session", { accountId, err });
+      });
+    }
+
+    api.logger.info("[soyeht] V2 handshake completed", { accountId });
+
+    respond(true, {
+      version: 2,
+      phase: "finish",
+      complete: true,
+      expiresAt: pending.sessionExpiresAt,
+    });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.security.rotate.v2 — re-establish V2 session
+// ---------------------------------------------------------------------------
+
+export function handleSecurityRotate(
+  api: OpenClawPluginApi,
+  v2deps: SecurityV2Deps,
+): GatewayRequestHandler {
+  return async (ctx) => {
+    if (!v2deps.ready) {
+      ctx.respond(false, undefined, { code: "NOT_READY", message: "Service not ready" });
+      return;
+    }
+
+    const accountId = normalizeAccountId(ctx.params["accountId"] as string | undefined);
+    const cfg = await api.runtime.config.loadConfig();
+    const account = resolveSoyehtAccount(cfg, accountId);
+    const { allowed } = v2deps.rateLimiter.check(`rotate:${accountId}`, account.security.rateLimit);
+    if (!allowed) {
+      ctx.respond(false, undefined, { code: "RATE_LIMITED", message: "Too many requests" });
+      return;
+    }
+
+    if (!v2deps.sessions.has(accountId)) {
+      ctx.respond(false, undefined, {
+        code: "NO_ACTIVE_SESSION",
+        message: "No active V2 session",
+      });
+      return;
+    }
+
+    return handleSecurityHandshake(api, v2deps)(ctx);
+  };
+}

package/src/security.ts

@@ -0,0 +1,158 @@
+// ---------------------------------------------------------------------------
+// Nonce cache — replay protection
+// ---------------------------------------------------------------------------
+
+export type NonceCacheOptions = {
+  maxAge?: number;   // ms, default 600_000 (10 min)
+  maxSize?: number;  // default 100_000
+  pruneIntervalMs?: number; // default 60_000
+};
+
+export type NonceCache = {
+  add(nonce: string): boolean; // returns false if already seen
+  has(nonce: string): boolean;
+  prune(): void;
+  dispose(): void;
+  readonly size: number;
+};
+
+export function createNonceCache(opts: NonceCacheOptions = {}): NonceCache {
+  const maxAge = opts.maxAge ?? 600_000;
+  const maxSize = opts.maxSize ?? 100_000;
+  const pruneIntervalMs = opts.pruneIntervalMs ?? 60_000;
+
+  const cache = new Map<string, number>(); // nonce → timestamp
+  let pruneTimer: ReturnType<typeof setInterval> | undefined;
+
+  if (pruneIntervalMs > 0) {
+    pruneTimer = setInterval(() => prune(), pruneIntervalMs);
+    if (pruneTimer && typeof pruneTimer === "object" && "unref" in pruneTimer) {
+      pruneTimer.unref();
+    }
+  }
+
+  function prune(): void {
+    const cutoff = Date.now() - maxAge;
+    for (const [nonce, ts] of cache) {
+      if (ts < cutoff) cache.delete(nonce);
+    }
+  }
+
+  function add(nonce: string): boolean {
+    if (cache.has(nonce)) return false;
+    if (cache.size >= maxSize) prune();
+    if (cache.size >= maxSize) {
+      // Still full after prune — evict oldest
+      const oldest = cache.keys().next().value!;
+      cache.delete(oldest);
+    }
+    cache.set(nonce, Date.now());
+    return true;
+  }
+
+  return {
+    add,
+    has: (nonce) => cache.has(nonce),
+    prune,
+    dispose() {
+      if (pruneTimer) {
+        clearInterval(pruneTimer);
+        pruneTimer = undefined;
+      }
+      cache.clear();
+    },
+    get size() { return cache.size; },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Rate limiter — sliding window per key
+// ---------------------------------------------------------------------------
+
+export type RateLimiterOptions = {
+  maxRequests?: number;  // default 60
+  windowMs?: number;     // default 60_000 (1 min)
+  lockoutMs?: number;    // default 300_000 (5 min)
+};
+
+export type RateLimiterCheckOptions = {
+  maxRequests?: number;
+  windowMs?: number;
+  lockoutMs?: number;
+};
+
+export type RateLimiter = {
+  check(key: string, opts?: RateLimiterCheckOptions): { allowed: boolean; retryAfterMs?: number };
+  prune(): void;
+  dispose(): void;
+};
+
+type RateLimiterEntry = {
+  timestamps: number[];
+  lockedUntil?: number;
+};
+
+export function createRateLimiter(opts: RateLimiterOptions = {}): RateLimiter {
+  const maxRequests = opts.maxRequests ?? 60;
+  const windowMs = opts.windowMs ?? 60_000;
+  const lockoutMs = opts.lockoutMs ?? 300_000;
+
+  const entries = new Map<string, RateLimiterEntry>();
+
+  function check(key: string, overrides?: RateLimiterCheckOptions): { allowed: boolean; retryAfterMs?: number } {
+    const effectiveMax = overrides?.maxRequests ?? maxRequests;
+    const effectiveWindow = overrides?.windowMs ?? windowMs;
+    const effectiveLockout = overrides?.lockoutMs ?? lockoutMs;
+
+    const now = Date.now();
+    let entry = entries.get(key);
+
+    if (entry?.lockedUntil && now < entry.lockedUntil) {
+      return { allowed: false, retryAfterMs: entry.lockedUntil - now };
+    }
+
+    if (!entry) {
+      entry = { timestamps: [] };
+      entries.set(key, entry);
+    }
+
+    // Clear lockout if expired
+    if (entry.lockedUntil && now >= entry.lockedUntil) {
+      entry.lockedUntil = undefined;
+      entry.timestamps = [];
+    }
+
+    // Remove timestamps outside window
+    const cutoff = now - effectiveWindow;
+    entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+
+    if (entry.timestamps.length >= effectiveMax) {
+      entry.lockedUntil = now + effectiveLockout;
+      return { allowed: false, retryAfterMs: effectiveLockout };
+    }
+
+    entry.timestamps.push(now);
+    return { allowed: true };
+  }
+
+  function prune(): void {
+    const now = Date.now();
+    for (const [key, entry] of entries) {
+      if (entry.lockedUntil && now >= entry.lockedUntil) {
+        entries.delete(key);
+        continue;
+      }
+      const cutoff = now - windowMs;
+      entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+      if (entry.timestamps.length === 0 && !entry.lockedUntil) {
+        entries.delete(key);
+      }
+    }
+  }
+
+  return {
+    check,
+    prune,
+    dispose() { entries.clear(); },
+  };
+}