@soyeht/soyeht 0.1.1

package/src/service.ts

@@ -0,0 +1,177 @@
+import { readFile, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import type { OpenClawPluginApi, OpenClawPluginService, OpenClawPluginServiceContext } from "openclaw/plugin-sdk";
+import {
+  createNonceCache,
+  createRateLimiter,
+  type NonceCache,
+  type RateLimiter,
+} from "./security.js";
+import { loadOrGenerateIdentity, loadPeers, loadSessions, saveSession } from "./identity.js";
+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";
+
+const HEARTBEAT_INTERVAL_MS = 60_000; // 60s
+
+// ---------------------------------------------------------------------------
+// V2 deps (lazy — filled by service.start())
+// ---------------------------------------------------------------------------
+
+export type SecurityV2Deps = {
+  identity: IdentityBundle | null;
+  peers: Map<string, PeerIdentity>;
+  sessions: Map<string, RatchetState>;
+  pairingSessions: Map<string, PairingSession>;
+  pendingHandshakes: Map<string, PendingHandshake>;
+  nonceCache: NonceCache;
+  rateLimiter: RateLimiter;
+  ready: boolean;
+  stateDir?: string;
+};
+
+export type PairingSession = {
+  token: string;
+  accountId: string;
+  expiresAt: number;
+  allowOverwrite: boolean;
+};
+
+export type PendingHandshake = {
+  key: string;
+  accountId: string;
+  nonce: string;
+  appEphemeralKey: string;
+  pluginEphemeralKey: X25519KeyPair;
+  transcript: Buffer;
+  challengeExpiresAt: number;
+  sessionExpiresAt: number;
+};
+
+export function createSecurityV2Deps(): SecurityV2Deps {
+  return {
+    identity: null,
+    peers: new Map(),
+    sessions: new Map(),
+    pairingSessions: new Map(),
+    pendingHandshakes: new Map(),
+    nonceCache: createNonceCache(),
+    rateLimiter: createRateLimiter(),
+    ready: false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+export function createSoyehtService(
+  api: OpenClawPluginApi,
+  v2deps?: SecurityV2Deps,
+): OpenClawPluginService {
+  let heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+
+  return {
+    id: "soyeht",
+
+    async start(ctx?: OpenClawPluginServiceContext) {
+      if (v2deps && ctx?.stateDir) {
+        try {
+          v2deps.stateDir = ctx.stateDir;
+          v2deps.identity = await loadOrGenerateIdentity(ctx.stateDir);
+
+          // Detect identity change — clear stale peers/sessions if fingerprint changed
+          const currentFp = computeFingerprint(v2deps.identity);
+          const fpPath = join(ctx.stateDir, "soyeht-security", ".fingerprint");
+          const storedFp = await readFile(fpPath, "utf8").catch(() => null);
+          if (storedFp && storedFp !== currentFp) {
+            v2deps.peers.clear();
+            v2deps.sessions.clear();
+            // Delete stale files from disk so they are not reloaded
+            const peersDir = join(ctx.stateDir, "soyeht-security", "peers");
+            const sessionsDir = join(ctx.stateDir, "soyeht-security", "sessions");
+            await rm(peersDir, { recursive: true, force: true }).catch(() => {});
+            await rm(sessionsDir, { recursive: true, force: true }).catch(() => {});
+            api.logger.warn("[soyeht] Identity changed — cleared peers and sessions from memory and disk");
+          }
+          await writeFile(fpPath, currentFp, "utf8").catch(() => {});
+
+          const peers = await loadPeers(ctx.stateDir);
+          peers.forEach((p, id) => v2deps.peers.set(id, p));
+          const sessions = await loadSessions(ctx.stateDir);
+          sessions.forEach((s, id) => v2deps.sessions.set(id, s));
+        } catch (err) {
+          api.logger.error("[soyeht] Failed to load V2 state", { err });
+        }
+      }
+      if (v2deps) v2deps.ready = true;
+
+      api.logger.info("[soyeht] Service started");
+
+      heartbeatTimer = setInterval(async () => {
+        api.logger.debug("[soyeht] Heartbeat tick");
+        if (v2deps) {
+          const now = Date.now();
+          v2deps.nonceCache.prune();
+          v2deps.rateLimiter.prune();
+          for (const [token, session] of v2deps.pairingSessions) {
+            if (session.expiresAt <= now) {
+              v2deps.pairingSessions.delete(token);
+            }
+          }
+          for (const [key, pending] of v2deps.pendingHandshakes) {
+            if (pending.challengeExpiresAt <= now) {
+              v2deps.pendingHandshakes.delete(key);
+            }
+          }
+          // Persist sessions
+          if (v2deps.stateDir) {
+            for (const [, s] of v2deps.sessions) {
+              await saveSession(v2deps.stateDir, s).catch((err) => {
+                api.logger.error("[soyeht] Failed to persist session", { accountId: s.accountId, err });
+              });
+            }
+          }
+        }
+      }, HEARTBEAT_INTERVAL_MS);
+
+      if (heartbeatTimer && typeof heartbeatTimer === "object" && "unref" in heartbeatTimer) {
+        heartbeatTimer.unref();
+      }
+    },
+
+    async stop(ctx?: OpenClawPluginServiceContext) {
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = undefined;
+      }
+
+      // Persist final state
+      const stateDir = v2deps?.stateDir ?? ctx?.stateDir;
+      if (v2deps && stateDir) {
+        for (const [, s] of v2deps.sessions) {
+          await saveSession(stateDir, s).catch((err) => {
+            api.logger.error("[soyeht] Failed to persist session on stop", { accountId: s.accountId, err });
+          });
+        }
+      }
+
+      // Zeroize sensitive material
+      if (v2deps) {
+        for (const s of v2deps.sessions.values()) {
+          zeroBuffer(s.rootKey);
+          zeroBuffer(s.sending.chainKey);
+          zeroBuffer(s.receiving.chainKey);
+        }
+        v2deps.sessions.clear();
+        v2deps.peers.clear();
+        v2deps.pairingSessions.clear();
+        v2deps.pendingHandshakes.clear();
+        v2deps.ready = false;
+      }
+
+      api.logger.info("[soyeht] Service stopped");
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,213 @@
+import { Type, type Static } from "@sinclair/typebox";
+
+// ---------------------------------------------------------------------------
+// Account config schema (per-account settings under channels.soyeht.accounts.*)
+// ---------------------------------------------------------------------------
+
+export const SoyehtAccountConfigSchema = Type.Object({
+  enabled: Type.Optional(Type.Boolean()),
+  backendBaseUrl: Type.Optional(Type.String()),
+  pluginAuthToken: Type.Optional(Type.String()),
+  allowProactive: Type.Optional(Type.Boolean()),
+  audio: Type.Optional(
+    Type.Object({
+      transcribeInbound: Type.Optional(Type.Boolean()),
+      ttsOutbound: Type.Optional(Type.Boolean()),
+    }),
+  ),
+  files: Type.Optional(
+    Type.Object({
+      acceptInbound: Type.Optional(Type.Boolean()),
+      maxBytes: Type.Optional(Type.Number()),
+    }, { additionalProperties: false }),
+  ),
+  security: Type.Optional(
+    Type.Object({
+      enabled: Type.Optional(Type.Boolean()),
+      timestampToleranceMs: Type.Optional(Type.Number()),
+      dhRatchetIntervalMessages: Type.Optional(Type.Number()),
+      dhRatchetIntervalMs: Type.Optional(Type.Number()),
+      sessionMaxAgeMs: Type.Optional(Type.Number()),
+      rateLimit: Type.Optional(
+        Type.Object({
+          maxRequests: Type.Optional(Type.Number()),
+          windowMs: Type.Optional(Type.Number()),
+        }, { additionalProperties: false }),
+      ),
+    }, { additionalProperties: false }),
+  ),
+}, { additionalProperties: false });
+
+export type SoyehtAccountConfig = Static<typeof SoyehtAccountConfigSchema>;
+
+export const SoyehtChannelConfigSchema = Type.Object({
+  accounts: Type.Optional(Type.Record(Type.String(), SoyehtAccountConfigSchema)),
+}, { additionalProperties: false });
+
+export type SoyehtChannelConfig = Static<typeof SoyehtChannelConfigSchema>;
+
+// ---------------------------------------------------------------------------
+// Outbound message payloads
+// ---------------------------------------------------------------------------
+
+export const TextMessagePayloadSchema = Type.Object({
+  contentType: Type.Literal("text"),
+  text: Type.String({ minLength: 1 }),
+});
+
+export type TextMessagePayload = Static<typeof TextMessagePayloadSchema>;
+
+export const AudioMessagePayloadSchema = Type.Object({
+  contentType: Type.Literal("audio"),
+  renderStyle: Type.Literal("voice_note"),
+  mimeType: Type.String(),
+  filename: Type.String(),
+  durationMs: Type.Optional(Type.Number()),
+  url: Type.String(),
+  transcript: Type.Optional(Type.String()),
+});
+
+export type AudioMessagePayload = Static<typeof AudioMessagePayloadSchema>;
+
+export const FileMessagePayloadSchema = Type.Object({
+  contentType: Type.Literal("file"),
+  mimeType: Type.String(),
+  filename: Type.String(),
+  sizeBytes: Type.Optional(Type.Number()),
+  url: Type.String(),
+});
+
+export type FileMessagePayload = Static<typeof FileMessagePayloadSchema>;
+
+// ---------------------------------------------------------------------------
+// Outbound envelope (wraps any payload for backend delivery)
+// ---------------------------------------------------------------------------
+
+export const OutboundEnvelopeSchema = Type.Object({
+  accountId: Type.String(),
+  sessionId: Type.String(),
+  deliveryId: Type.String(),
+  timestamp: Type.Number(),
+  message: Type.Union([
+    TextMessagePayloadSchema,
+    AudioMessagePayloadSchema,
+    FileMessagePayloadSchema,
+  ]),
+});
+
+export type OutboundEnvelope = Static<typeof OutboundEnvelopeSchema>;
+
+// ---------------------------------------------------------------------------
+// Delivery ack (webhook response from backend)
+// ---------------------------------------------------------------------------
+
+export const DeliveryAckSchema = Type.Object({
+  deliveryId: Type.String(),
+  status: Type.Union([Type.Literal("delivered"), Type.Literal("failed")]),
+  error: Type.Optional(Type.String()),
+});
+
+export type DeliveryAck = Static<typeof DeliveryAckSchema>;
+
+// ---------------------------------------------------------------------------
+// Security schemas
+// ---------------------------------------------------------------------------
+
+export const HandshakeInitV2Schema = Type.Object({
+  version: Type.Literal(2),
+  accountId: Type.String(),
+  appEphemeralKey: Type.String(),   // X25519 pub raw b64url
+  nonce: Type.String(),
+  timestamp: Type.Number(),
+});
+
+export type HandshakeInitV2 = Static<typeof HandshakeInitV2Schema>;
+
+export const HandshakeResponseV2Schema = Type.Object({
+  version: Type.Literal(2),
+  phase: Type.Literal("init"),
+  complete: Type.Boolean(),
+  pluginEphemeralKey: Type.String(), // X25519 pub raw b64url
+  nonce: Type.String(),
+  timestamp: Type.Number(),
+  serverTimestamp: Type.Number(),
+  challengeExpiresAt: Type.Number(),
+  expiresAt: Type.Number(),
+  pluginSignature: Type.String(),    // Ed25519 sig over transcript, b64url
+});
+
+export type HandshakeResponseV2 = Static<typeof HandshakeResponseV2Schema>;
+
+export const EnvelopeV2Schema = Type.Object({
+  v: Type.Literal(2),
+  accountId: Type.String(),
+  direction: Type.Union([Type.Literal("plugin_to_app"), Type.Literal("app_to_plugin")]),
+  counter: Type.Number(),
+  timestamp: Type.Number(),
+  dhRatchetKey: Type.Optional(Type.String()),
+  ciphertext: Type.String(),
+  iv: Type.String(),
+  tag: Type.String(),
+});
+
+export type EnvelopeV2Type = Static<typeof EnvelopeV2Schema>;
+
+export const PairRequestSchema = Type.Object({
+  accountId: Type.String(),
+  pairingToken: Type.String(),
+  appIdentityKey: Type.String(), // Ed25519 pub raw b64url
+  appDhKey: Type.String(),       // X25519 pub raw b64url
+  appSignature: Type.String(),   // Ed25519 signature over pairing proof transcript
+});
+
+export type PairRequest = Static<typeof PairRequestSchema>;
+
+export const PairingQrPayloadSchema = Type.Object({
+  version: Type.Literal(1),
+  type: Type.Literal("soyeht_pairing_qr"),
+  accountId: Type.String(),
+  pairingToken: Type.String(),
+  expiresAt: Type.Number(),
+  allowOverwrite: Type.Boolean(),
+  pluginIdentityKey: Type.String(),
+  pluginDhKey: Type.String(),
+  fingerprint: Type.String(),
+  signature: Type.String(),
+});
+
+export type PairingQrPayload = Static<typeof PairingQrPayloadSchema>;
+
+export const HandshakeFinishV2Schema = Type.Object({
+  version: Type.Literal(2),
+  accountId: Type.String(),
+  nonce: Type.String(),
+  appSignature: Type.String(),
+});
+
+export type HandshakeFinishV2 = Static<typeof HandshakeFinishV2Schema>;
+
+// ---------------------------------------------------------------------------
+// Channel capabilities
+// ---------------------------------------------------------------------------
+
+export const SOYEHT_CAPABILITIES = {
+  chatTypes: ["direct"] as const,
+  media: true,
+  livekit: false,
+  voiceContractVersion: 1,
+  pipeline: "stt->llm->tts" as const,
+  supportedContentTypes: ["text", "audio", "file"] as const,
+  security: {
+    version: 2,
+    pairingMode: "qr_token" as const,
+    handshakeMode: "two_step" as const,
+    fingerprintAlgorithm: "SHA256-trunc-16bytes-hex",
+    algorithms: {
+      keyAgreement: "X3DH (X25519)",
+      keyDerivation: "HKDF-SHA256",
+      authentication: "Ed25519",
+      encryption: "AES-256-GCM",
+      ratchet: "Double Ratchet (symmetric + DH)",
+    },
+  },
+} as const;

package/src/version.ts

@@ -0,0 +1 @@
+export const PLUGIN_VERSION = "0.1.1";

package/src/x3dh.ts

@@ -0,0 +1,105 @@
+import type { KeyObject } from "node:crypto";
+import {
+  computeSharedSecret,
+  hkdfDerive,
+  hkdfDeriveSync,
+  ed25519Sign,
+  ed25519Verify,
+  base64UrlEncode,
+  base64UrlDecode,
+  type X25519KeyPair,
+} from "./crypto.js";
+
+// ---------------------------------------------------------------------------
+// X3DH key agreement (plugin is always the responder)
+//
+// Triple DH (from plugin/responder perspective):
+//   DH1 = X25519(pluginStaticDhPriv, appEphemeralPub)
+//   DH2 = X25519(pluginEphemeralPriv, appStaticDhPub)
+//   DH3 = X25519(pluginEphemeralPriv, appEphemeralPub)
+//   ikm  = DH1 || DH2 || DH3
+//   root = HKDF(ikm, nonce_bytes, "soyeht-v2-root", 32)
+//   send = HKDF(root, 0x, "soyeht-v2-chain-send", 32)  [plugin→app]
+//   recv = HKDF(root, 0x, "soyeht-v2-chain-recv", 32)  [app→plugin]
+// ---------------------------------------------------------------------------
+
+export type X3DHResult = {
+  rootKey: Buffer;
+  sendChainKey: Buffer; // plugin's send = app's recv
+  recvChainKey: Buffer; // plugin's recv = app's send
+};
+
+export async function performX3DH(params: {
+  myStaticDhKey: X25519KeyPair;    // plugin's static DH key pair
+  myEphemeralKey: X25519KeyPair;   // plugin's ephemeral DH key pair (just generated)
+  peerStaticDhPub: KeyObject;      // app's static DH pub (from pairing)
+  peerEphemeralPub: KeyObject;     // app's ephemeral DH pub (from handshake init)
+  nonce: string;                   // handshake nonce (b64url) — used as HKDF salt
+}): Promise<X3DHResult> {
+  const { myStaticDhKey, myEphemeralKey, peerStaticDhPub, peerEphemeralPub, nonce } = params;
+
+  const dh1 = computeSharedSecret(myStaticDhKey.privateKey, peerEphemeralPub);
+  const dh2 = computeSharedSecret(myEphemeralKey.privateKey, peerStaticDhPub);
+  const dh3 = computeSharedSecret(myEphemeralKey.privateKey, peerEphemeralPub);
+
+  const ikm = Buffer.concat([dh1, dh2, dh3]);
+  const salt = base64UrlDecode(nonce);
+
+  const rootKey = await hkdfDerive(ikm, salt, "soyeht-v2-root", 32);
+
+  const empty = Buffer.alloc(0);
+  const sendChainKey = hkdfDeriveSync(rootKey, empty, "soyeht-v2-chain-send", 32);
+  const recvChainKey = hkdfDeriveSync(rootKey, empty, "soyeht-v2-chain-recv", 32);
+
+  // Zero intermediate secrets
+  dh1.fill(0);
+  dh2.fill(0);
+  dh3.fill(0);
+  ikm.fill(0);
+
+  return { rootKey, sendChainKey, recvChainKey };
+}
+
+// ---------------------------------------------------------------------------
+// Handshake transcripts
+//
+// The app signs a subset (it doesn't know pluginEphKey or expiresAt yet).
+// The plugin signs the full transcript after generating its ephemeral key.
+// ---------------------------------------------------------------------------
+
+/** What the app signs — only values known at request time. */
+export function buildAppHandshakeTranscript(params: {
+  accountId: string;
+  appEphKeyB64: string;
+  nonce: string;
+  timestamp: number;
+}): Buffer {
+  const { accountId, appEphKeyB64, nonce, timestamp } = params;
+  return Buffer.from(`x3dh_v2|${accountId}|${appEphKeyB64}|${nonce}|${timestamp}`, "utf8");
+}
+
+/** Full transcript — signed by the plugin, verified by the app. */
+export function buildHandshakeTranscript(params: {
+  accountId: string;
+  appEphKeyB64: string;
+  pluginEphKeyB64: string;
+  nonce: string;
+  timestamp: number;
+  expiresAt: number;
+}): Buffer {
+  const { accountId, appEphKeyB64, pluginEphKeyB64, nonce, timestamp, expiresAt } = params;
+  const str = `x3dh_v2|${accountId}|${appEphKeyB64}|${pluginEphKeyB64}|${nonce}|${timestamp}|${expiresAt}`;
+  return Buffer.from(str, "utf8");
+}
+
+export function signHandshakeTranscript(privKey: KeyObject, transcript: Buffer): string {
+  return base64UrlEncode(ed25519Sign(privKey, transcript));
+}
+
+export function verifyHandshakeTranscript(
+  pubKey: KeyObject,
+  transcript: Buffer,
+  sigB64: string,
+): boolean {
+  return ed25519Verify(pubKey, transcript, base64UrlDecode(sigB64));
+}