@soyeht/soyeht 0.1.1

package/src/http.ts

@@ -0,0 +1,175 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { normalizeAccountId } from "./config.js";
+import { decryptEnvelopeV2, validateEnvelopeV2, type EnvelopeV2 } from "./envelope-v2.js";
+import { cloneRatchetSession } from "./ratchet.js";
+import type { SecurityV2Deps } from "./service.js";
+import { PLUGIN_VERSION } from "./version.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  const json = JSON.stringify(body);
+  res.writeHead(status, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(json),
+  });
+  res.end(json);
+}
+
+const MAX_BODY_BYTES = 1024 * 1024; // 1 MB
+
+async function readRawBodyBuffer(req: IncomingMessage): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let totalBytes = 0;
+
+    req.on("data", (chunk: Buffer) => {
+      totalBytes += chunk.length;
+      if (totalBytes > MAX_BODY_BYTES) {
+        req.destroy();
+        reject(new Error("body_too_large"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+export { readRawBodyBuffer };
+
+// ---------------------------------------------------------------------------
+// GET /soyeht/health
+// ---------------------------------------------------------------------------
+
+export function healthHandler(_api: OpenClawPluginApi) {
+  return async (_req: IncomingMessage, res: ServerResponse) => {
+    sendJson(res, 200, { ok: true, plugin: "soyeht", version: PLUGIN_VERSION });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// POST /soyeht/webhook/deliver
+// ---------------------------------------------------------------------------
+
+export function webhookHandler(
+  api: OpenClawPluginApi,
+  v2deps?: SecurityV2Deps,
+) {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.method !== "POST") {
+      sendJson(res, 405, { ok: false, error: "method_not_allowed" });
+      return;
+    }
+
+    const headers = req.headers ?? {};
+    const headerAccountIdRaw = (headers["x-soyeht-account-id"] as string | undefined)?.trim();
+    const hintedAccountId = headerAccountIdRaw ? normalizeAccountId(headerAccountIdRaw) : undefined;
+
+    if (!v2deps?.ready) {
+      sendJson(res, 503, { ok: false, error: "service_unavailable" });
+      return;
+    }
+
+    // Rate limit per-account
+    if (v2deps.rateLimiter) {
+      const { allowed, retryAfterMs } = v2deps.rateLimiter.check(`webhook:${hintedAccountId ?? "_unknown"}`);
+      if (!allowed) {
+        res.setHeader("Retry-After", String(Math.ceil((retryAfterMs ?? 60_000) / 1000)));
+        sendJson(res, 429, { ok: false, error: "rate_limited" });
+        return;
+      }
+    }
+
+    try {
+      const rawBody = await readRawBodyBuffer(req);
+
+      // Parse the envelope
+      let envelope: EnvelopeV2;
+      try {
+        envelope = JSON.parse(rawBody.toString("utf8")) as EnvelopeV2;
+      } catch {
+        sendJson(res, 400, { ok: false, error: "invalid_json" });
+        return;
+      }
+
+      const envelopeAccountId = normalizeAccountId(envelope.accountId);
+      if (hintedAccountId && hintedAccountId !== envelopeAccountId) {
+        sendJson(res, 401, { ok: false, error: "account_mismatch" });
+        return;
+      }
+
+      const accountId = hintedAccountId ?? envelopeAccountId;
+      const session = v2deps.sessions.get(accountId);
+      if (!session) {
+        sendJson(res, 401, { ok: false, error: "session_required" });
+        return;
+      }
+
+      if (session.expiresAt < Date.now()) {
+        sendJson(res, 401, { ok: false, error: "session_expired" });
+        return;
+      }
+
+      if (session.accountId !== envelopeAccountId) {
+        sendJson(res, 401, { ok: false, error: "account_mismatch" });
+        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 });
+        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 });
+        return;
+      }
+
+      // Update session
+      v2deps.sessions.set(accountId, updatedSession);
+
+      api.logger.info("[soyeht] Webhook delivery received", { 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 });
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// POST /soyeht/livekit/token — stub
+// ---------------------------------------------------------------------------
+
+export function livekitTokenHandler(_api: OpenClawPluginApi) {
+  return async (_req: IncomingMessage, res: ServerResponse) => {
+    sendJson(res, 501, {
+      ok: false,
+      error: "not_enabled",
+      pipeline: "stt->llm->tts",
+      availableIn: "v2",
+    });
+  };
+}

package/src/identity.ts

@@ -0,0 +1,157 @@
+import { mkdir, readFile, writeFile, readdir, unlink, chmod } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  ed25519GenerateKeyPair,
+  generateX25519KeyPair,
+  exportPrivateKeyPkcs8,
+  exportPublicKeyRaw,
+  importEd25519PublicKey,
+  importX25519PublicKey,
+  importPrivateKeyPkcs8,
+  base64UrlEncode,
+  base64UrlDecode,
+  type Ed25519KeyPair,
+  type X25519KeyPair,
+} from "./crypto.js";
+import type { RatchetState } from "./ratchet.js";
+import { serializeSession, deserializeSession } from "./ratchet.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type IdentityBundle = {
+  signKey: Ed25519KeyPair;
+  dhKey: X25519KeyPair;
+};
+
+export type PeerIdentity = {
+  accountId: string;
+  identityKeyB64: string; // Ed25519 pub raw b64url (32 bytes)
+  dhKeyB64: string;       // X25519 pub raw b64url (32 bytes)
+};
+
+// ---------------------------------------------------------------------------
+// Account ID validation — reject path traversal attempts
+// ---------------------------------------------------------------------------
+
+const SAFE_ACCOUNT_ID = /^[a-zA-Z0-9_-]+$/;
+
+function validateAccountId(accountId: string): void {
+  if (!SAFE_ACCOUNT_ID.test(accountId)) {
+    throw new Error(`Invalid accountId for file operation: ${accountId}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+function secDir(stateDir: string): string {
+  return join(stateDir, "soyeht-security");
+}
+
+// ---------------------------------------------------------------------------
+// Identity load / generate
+// ---------------------------------------------------------------------------
+
+export async function loadOrGenerateIdentity(stateDir: string): Promise<IdentityBundle> {
+  const dir = secDir(stateDir);
+  await mkdir(dir, { recursive: true });
+  const identityPath = join(dir, "identity.json");
+
+  try {
+    const raw = JSON.parse(await readFile(identityPath, "utf8")) as Record<string, unknown>;
+    const signPriv = importPrivateKeyPkcs8(base64UrlDecode(raw["signPriv"] as string));
+    const signPubB64 = raw["signPub"] as string;
+    const signPub = importEd25519PublicKey(signPubB64);
+    const dhPriv = importPrivateKeyPkcs8(base64UrlDecode(raw["dhPriv"] as string));
+    const dhPubB64 = raw["dhPub"] as string;
+    const dhPub = importX25519PublicKey(dhPubB64);
+    const dhPubRaw = base64UrlDecode(dhPubB64);
+    return {
+      signKey: { publicKey: signPub, privateKey: signPriv, publicKeyB64: signPubB64 },
+      dhKey: { publicKey: dhPub, privateKey: dhPriv, publicKeyRaw: dhPubRaw, publicKeyB64: dhPubB64 },
+    };
+  } catch {
+    // Generate fresh identity
+    const signKp = ed25519GenerateKeyPair();
+    const dhKp = generateX25519KeyPair();
+    const data = {
+      signPub: signKp.publicKeyB64,
+      signPriv: base64UrlEncode(exportPrivateKeyPkcs8(signKp.privateKey)),
+      dhPub: dhKp.publicKeyB64,
+      dhPriv: base64UrlEncode(exportPrivateKeyPkcs8(dhKp.privateKey)),
+    };
+    await writeFile(identityPath, JSON.stringify(data, null, 2), "utf8");
+    try { await chmod(identityPath, 0o600); } catch { /* no-op on Windows */ }
+    return { signKey: signKp, dhKey: dhKp };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Peer store
+// ---------------------------------------------------------------------------
+
+export async function savePeer(stateDir: string, peer: PeerIdentity): Promise<void> {
+  validateAccountId(peer.accountId);
+  const dir = join(secDir(stateDir), "peers");
+  await mkdir(dir, { recursive: true });
+  const filePath = join(dir, `${peer.accountId}.json`);
+  await writeFile(filePath, JSON.stringify(peer, null, 2), "utf8");
+  try { await chmod(filePath, 0o600); } catch { /* no-op on Windows */ }
+}
+
+export async function loadPeers(stateDir: string): Promise<Map<string, PeerIdentity>> {
+  const dir = join(secDir(stateDir), "peers");
+  const map = new Map<string, PeerIdentity>();
+  try {
+    const files = await readdir(dir);
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      try {
+        const peer = JSON.parse(await readFile(join(dir, file), "utf8")) as PeerIdentity;
+        map.set(peer.accountId, peer);
+      } catch { /* skip corrupt */ }
+    }
+  } catch { /* dir not exist */ }
+  return map;
+}
+
+// ---------------------------------------------------------------------------
+// Session store
+// ---------------------------------------------------------------------------
+
+export async function saveSession(stateDir: string, session: RatchetState): Promise<void> {
+  validateAccountId(session.accountId);
+  const dir = join(secDir(stateDir), "sessions");
+  await mkdir(dir, { recursive: true });
+  const filePath = join(dir, `${session.accountId}.json`);
+  await writeFile(filePath, JSON.stringify(serializeSession(session), null, 2), "utf8");
+  try { await chmod(filePath, 0o600); } catch { /* no-op on Windows */ }
+}
+
+export async function loadSessions(stateDir: string): Promise<Map<string, RatchetState>> {
+  const dir = join(secDir(stateDir), "sessions");
+  const map = new Map<string, RatchetState>();
+  try {
+    const files = await readdir(dir);
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      try {
+        const raw = JSON.parse(await readFile(join(dir, file), "utf8"));
+        const session = deserializeSession(raw);
+        if (session.expiresAt < Date.now()) continue; // skip expired
+        map.set(session.accountId, session);
+      } catch { /* skip corrupt */ }
+    }
+  } catch { /* dir not exist */ }
+  return map;
+}
+
+export async function deleteSession(stateDir: string, accountId: string): Promise<void> {
+  validateAccountId(accountId);
+  try {
+    await unlink(join(secDir(stateDir), "sessions", `${accountId}.json`));
+  } catch { /* ignore */ }
+}

package/src/index.ts

@@ -0,0 +1,120 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { createSoyehtChannel } from "./channel.js";
+import {
+  handleStatus,
+  handleCapabilities,
+  handleNotify,
+  handleLiveKitPrepare,
+  handleSecurityHandshake,
+  handleSecurityHandshakeFinish,
+  handleSecurityRotate,
+} from "./rpc.js";
+import {
+  healthHandler,
+  webhookHandler,
+  livekitTokenHandler,
+} from "./http.js";
+import {
+  createSoyehtService,
+  createSecurityV2Deps,
+} from "./service.js";
+import {
+  handleSecurityIdentity,
+  handleSecurityPair,
+  handleSecurityPairingStart,
+} from "./pairing.js";
+import { PLUGIN_VERSION } from "./version.js";
+
+type OpenClawPluginDefinition = {
+  id?: string;
+  name?: string;
+  description?: string;
+  version?: string;
+  configSchema?: {
+    safeParse(value: unknown): { success: boolean; data?: unknown; error?: unknown };
+    jsonSchema: Record<string, unknown>;
+  };
+  register?: (api: OpenClawPluginApi) => void | Promise<void>;
+};
+
+const emptyPluginConfigSchema = {
+  safeParse(value: unknown) {
+    if (value === undefined) {
+      return { success: true, data: undefined };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return {
+        success: false,
+        error: { issues: [{ path: [], message: "expected config object" }] },
+      };
+    }
+    if (Object.keys(value as Record<string, unknown>).length > 0) {
+      return {
+        success: false,
+        error: { issues: [{ path: [], message: "config must be empty" }] },
+      };
+    }
+    return { success: true, data: value };
+  },
+  jsonSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {},
+  },
+};
+
+const soyehtPlugin: OpenClawPluginDefinition = {
+  id: "soyeht",
+  name: "Soyeht",
+  description: "Channel plugin for the Soyeht Flutter mobile app",
+  version: PLUGIN_VERSION,
+
+  configSchema: emptyPluginConfigSchema,
+
+  async register(api) {
+    // V2 deps — identity/sessions loaded in service.start()
+    const v2deps = createSecurityV2Deps();
+
+    // Channel
+    api.registerChannel({ plugin: createSoyehtChannel(v2deps) });
+
+    // Gateway RPC methods
+    api.registerGatewayMethod("soyeht.status", handleStatus(api));
+    api.registerGatewayMethod("soyeht.capabilities", handleCapabilities(api));
+    api.registerGatewayMethod("soyeht.notify", handleNotify(api, v2deps));
+    api.registerGatewayMethod("soyeht.livekit.prepare", handleLiveKitPrepare(api));
+
+    // Security RPC
+    api.registerGatewayMethod("soyeht.security.identity", handleSecurityIdentity(api, v2deps));
+    api.registerGatewayMethod("soyeht.security.pairing.start", handleSecurityPairingStart(api, v2deps));
+    api.registerGatewayMethod("soyeht.security.pair", handleSecurityPair(api, v2deps));
+    api.registerGatewayMethod("soyeht.security.handshake.init", handleSecurityHandshake(api, v2deps));
+    api.registerGatewayMethod("soyeht.security.handshake.finish", handleSecurityHandshakeFinish(api, v2deps));
+    api.registerGatewayMethod("soyeht.security.handshake", handleSecurityHandshake(api, v2deps));
+    api.registerGatewayMethod("soyeht.security.rotate", handleSecurityRotate(api, v2deps));
+
+    // HTTP routes
+    api.registerHttpRoute({
+      path: "/soyeht/health",
+      auth: "plugin",
+      handler: healthHandler(api),
+    });
+    api.registerHttpRoute({
+      path: "/soyeht/webhook/deliver",
+      auth: "plugin",
+      handler: webhookHandler(api, v2deps),
+    });
+    api.registerHttpRoute({
+      path: "/soyeht/livekit/token",
+      auth: "plugin",
+      handler: livekitTokenHandler(api),
+    });
+
+    // Background service (manages state lifecycle)
+    api.registerService(createSoyehtService(api, v2deps));
+
+    api.logger.info("[soyeht] Plugin registered");
+  },
+};
+
+export default soyehtPlugin;

package/src/media.ts

@@ -0,0 +1,100 @@
+import type { PluginRuntime, OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveSoyehtAccount } from "./config.js";
+
+// ---------------------------------------------------------------------------
+// STT — transcribe inbound audio
+// ---------------------------------------------------------------------------
+
+export type TranscribeResult = {
+  text: string | undefined;
+  skipped: boolean;
+};
+
+export async function transcribeInboundAudio(params: {
+  runtime: PluginRuntime;
+  cfg: OpenClawConfig;
+  filePath: string;
+  mime?: string;
+  accountId?: string;
+}): Promise<TranscribeResult> {
+  const account = resolveSoyehtAccount(params.cfg, params.accountId);
+
+  if (!account.audio.transcribeInbound) {
+    return { text: undefined, skipped: true };
+  }
+
+  const result = await params.runtime.stt.transcribeAudioFile({
+    filePath: params.filePath,
+    cfg: params.cfg,
+    mime: params.mime,
+  });
+
+  return { text: result.text, skipped: false };
+}
+
+// ---------------------------------------------------------------------------
+// TTS — generate outbound speech
+// ---------------------------------------------------------------------------
+
+export type TtsResult = {
+  success: boolean;
+  audioBuffer?: Buffer;
+  mimeType: string;
+  error?: string;
+};
+
+export async function generateOutboundTts(params: {
+  runtime: PluginRuntime;
+  cfg: OpenClawConfig;
+  text: string;
+  accountId?: string;
+}): Promise<TtsResult> {
+  const account = resolveSoyehtAccount(params.cfg, params.accountId);
+
+  if (!account.audio.ttsOutbound) {
+    return { success: false, mimeType: "audio/wav", error: "tts_disabled" };
+  }
+
+  const result = await params.runtime.tts.textToSpeechTelephony({
+    text: params.text,
+    cfg: params.cfg,
+  });
+
+  return {
+    success: result.success,
+    audioBuffer: result.audioBuffer,
+    mimeType: result.outputFormat === "mp3" ? "audio/mpeg" : "audio/wav",
+    error: result.error,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// File validation
+// ---------------------------------------------------------------------------
+
+export type FileValidationResult = {
+  allowed: boolean;
+  reason?: string;
+};
+
+export function validateInboundFile(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+  sizeBytes: number;
+  mimeType: string;
+}): FileValidationResult {
+  const account = resolveSoyehtAccount(params.cfg, params.accountId);
+
+  if (!account.files.acceptInbound) {
+    return { allowed: false, reason: "files_disabled" };
+  }
+
+  if (params.sizeBytes > account.files.maxBytes) {
+    return {
+      allowed: false,
+      reason: `file_too_large: ${params.sizeBytes} > ${account.files.maxBytes}`,
+    };
+  }
+
+  return { allowed: true };
+}