@soyeht/soyeht 0.1.1

package/src/config.ts

@@ -0,0 +1,203 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+// Inlined from openclaw/plugin-sdk to avoid transitive dependency resolution at runtime.
+function listConfiguredAccountIds(params: {
+  accounts: Record<string, unknown> | undefined;
+  normalizeAccountId: (accountId: string) => string;
+}): string[] {
+  if (!params.accounts) return [];
+  const ids = new Set<string>();
+  for (const key of Object.keys(params.accounts)) {
+    if (!key) continue;
+    ids.add(params.normalizeAccountId(key));
+  }
+  return [...ids];
+}
+
+// ---------------------------------------------------------------------------
+// Resolved account type — all fields have concrete defaults
+// ---------------------------------------------------------------------------
+
+export type ResolvedSoyehtAccount = {
+  accountId: string;
+  enabled: boolean;
+  backendBaseUrl: string;
+  pluginAuthToken: string;
+  allowProactive: boolean;
+  audio: {
+    transcribeInbound: boolean;
+    ttsOutbound: boolean;
+  };
+  files: {
+    acceptInbound: boolean;
+    maxBytes: number;
+  };
+  security: {
+    enabled: boolean;
+    timestampToleranceMs: number;
+    dhRatchetIntervalMessages: number;
+    dhRatchetIntervalMs: number;
+    sessionMaxAgeMs: number;
+    rateLimit: {
+      maxRequests: number;
+      windowMs: number;
+    };
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CONFIG_ROOT = "channels.soyeht" as const;
+const DEFAULT_ACCOUNT_ID = "default";
+const DEFAULT_MAX_FILE_BYTES = 25 * 1024 * 1024; // 25 MB
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readConfigSection(cfg: OpenClawConfig): Record<string, unknown> | undefined {
+  const raw = cfg as Record<string, unknown>;
+  const channels = raw["channels"] as Record<string, unknown> | undefined;
+  return channels?.["soyeht"] as Record<string, unknown> | undefined;
+}
+
+function readAccountsSection(
+  cfg: OpenClawConfig,
+): Record<string, unknown> | undefined {
+  const section = readConfigSection(cfg);
+  return section?.["accounts"] as Record<string, unknown> | undefined;
+}
+
+function readAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+): Record<string, unknown> {
+  const accounts = readAccountsSection(cfg);
+  if (!accounts) return {};
+  const entry = accounts[accountId];
+  return entry && typeof entry === "object" ? (entry as Record<string, unknown>) : {};
+}
+
+// ---------------------------------------------------------------------------
+// enforceHttps — reject non-https backend URLs (allow http only for localhost)
+// ---------------------------------------------------------------------------
+
+function enforceHttps(url: string): string {
+  if (!url) return url;
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol === "https:") return url;
+    // Allow http for localhost/127.x development
+    if (parsed.protocol === "http:" && (parsed.hostname === "localhost" || parsed.hostname.startsWith("127."))) {
+      return url;
+    }
+    // Reject non-https for remote hosts — return empty to mark as unconfigured
+    return "";
+  } catch {
+    return "";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// normalizeAccountId
+// ---------------------------------------------------------------------------
+
+export function normalizeAccountId(id?: string | null): string {
+  const trimmed = (id ?? "").trim().toLowerCase();
+  return trimmed || DEFAULT_ACCOUNT_ID;
+}
+
+// ---------------------------------------------------------------------------
+// resolveSoyehtAccount
+// ---------------------------------------------------------------------------
+
+export function resolveSoyehtAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): ResolvedSoyehtAccount {
+  const normalizedId = normalizeAccountId(accountId);
+  const raw = readAccountConfig(cfg, normalizedId);
+  const audioRaw = (raw["audio"] as Record<string, unknown>) ?? {};
+  const filesRaw = (raw["files"] as Record<string, unknown>) ?? {};
+  const securityRaw = (raw["security"] as Record<string, unknown>) ?? {};
+  const rateLimitRaw = (securityRaw["rateLimit"] as Record<string, unknown>) ?? {};
+
+  return {
+    accountId: normalizedId,
+    enabled: typeof raw["enabled"] === "boolean" ? raw["enabled"] : true,
+    backendBaseUrl:
+      typeof raw["backendBaseUrl"] === "string"
+        ? enforceHttps(raw["backendBaseUrl"])
+        : "",
+    pluginAuthToken:
+      typeof raw["pluginAuthToken"] === "string" ? raw["pluginAuthToken"] : "",
+    allowProactive:
+      typeof raw["allowProactive"] === "boolean" ? raw["allowProactive"] : false,
+    audio: {
+      transcribeInbound:
+        typeof audioRaw["transcribeInbound"] === "boolean"
+          ? audioRaw["transcribeInbound"]
+          : true,
+      ttsOutbound:
+        typeof audioRaw["ttsOutbound"] === "boolean"
+          ? audioRaw["ttsOutbound"]
+          : false,
+    },
+    files: {
+      acceptInbound:
+        typeof filesRaw["acceptInbound"] === "boolean"
+          ? filesRaw["acceptInbound"]
+          : true,
+      maxBytes:
+        typeof filesRaw["maxBytes"] === "number"
+          ? filesRaw["maxBytes"]
+          : DEFAULT_MAX_FILE_BYTES,
+    },
+    security: {
+      enabled:
+        typeof securityRaw["enabled"] === "boolean"
+          ? securityRaw["enabled"]
+          : false,
+      timestampToleranceMs:
+        typeof securityRaw["timestampToleranceMs"] === "number"
+          ? securityRaw["timestampToleranceMs"]
+          : 300_000,
+      dhRatchetIntervalMessages:
+        typeof securityRaw["dhRatchetIntervalMessages"] === "number"
+          ? securityRaw["dhRatchetIntervalMessages"]
+          : 50,
+      dhRatchetIntervalMs:
+        typeof securityRaw["dhRatchetIntervalMs"] === "number"
+          ? securityRaw["dhRatchetIntervalMs"]
+          : 3_600_000,
+      sessionMaxAgeMs:
+        typeof securityRaw["sessionMaxAgeMs"] === "number"
+          ? securityRaw["sessionMaxAgeMs"]
+          : 86_400_000,
+      rateLimit: {
+        maxRequests:
+          typeof rateLimitRaw["maxRequests"] === "number"
+            ? rateLimitRaw["maxRequests"]
+            : 60,
+        windowMs:
+          typeof rateLimitRaw["windowMs"] === "number"
+            ? rateLimitRaw["windowMs"]
+            : 60_000,
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// listSoyehtAccountIds
+// ---------------------------------------------------------------------------
+
+export function listSoyehtAccountIds(cfg: OpenClawConfig): string[] {
+  const accounts = readAccountsSection(cfg);
+  return listConfiguredAccountIds({
+    accounts: accounts as Record<string, unknown> | undefined,
+    normalizeAccountId,
+  });
+}

package/src/crypto.ts

@@ -0,0 +1,227 @@
+import {
+  generateKeyPairSync,
+  createPublicKey,
+  createPrivateKey,
+  diffieHellman,
+  hkdf,
+  hkdfSync,
+  createHash,
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+  sign,
+  verify,
+  type KeyObject,
+} from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Base64url encoding
+// ---------------------------------------------------------------------------
+
+export function base64UrlEncode(buf: Buffer): string {
+  return buf.toString("base64url");
+}
+
+export function base64UrlDecode(str: string): Buffer {
+  return Buffer.from(str, "base64url");
+}
+
+// ---------------------------------------------------------------------------
+// X25519 key pairs
+// ---------------------------------------------------------------------------
+
+export type X25519KeyPair = {
+  publicKey: KeyObject;
+  privateKey: KeyObject;
+  publicKeyRaw: Buffer;
+  publicKeyB64: string;
+};
+
+export function generateX25519KeyPair(): X25519KeyPair {
+  const { publicKey, privateKey } = generateKeyPairSync("x25519");
+  const publicKeyRaw = publicKey.export({ type: "spki", format: "der" }).subarray(-32);
+  return {
+    publicKey,
+    privateKey,
+    publicKeyRaw,
+    publicKeyB64: base64UrlEncode(publicKeyRaw),
+  };
+}
+
+export function importX25519PublicKey(rawB64: string): KeyObject {
+  const raw = base64UrlDecode(rawB64);
+  if (raw.length !== 32) {
+    throw new Error(`Invalid X25519 public key length: ${raw.length}`);
+  }
+  // X25519 SPKI DER prefix (12 bytes) + 32 bytes raw key
+  const spkiPrefix = Buffer.from("302a300506032b656e032100", "hex");
+  const spki = Buffer.concat([spkiPrefix, raw]);
+  return createPublicKey({ key: spki, format: "der", type: "spki" });
+}
+
+// ---------------------------------------------------------------------------
+// ECDH shared secret
+// ---------------------------------------------------------------------------
+
+export function computeSharedSecret(privateKey: KeyObject, peerPublicKey: KeyObject): Buffer {
+  return diffieHellman({ privateKey, publicKey: peerPublicKey });
+}
+
+// ---------------------------------------------------------------------------
+// Nonce generation
+// ---------------------------------------------------------------------------
+
+export function generateNonce(): Buffer {
+  return randomBytes(16);
+}
+
+export function generateNonceB64(): string {
+  return base64UrlEncode(generateNonce());
+}
+
+// ---------------------------------------------------------------------------
+// AES-256-GCM encrypt / decrypt
+// ---------------------------------------------------------------------------
+
+export type AesGcmEncryptParams = {
+  key: Buffer;
+  plaintext: string;
+};
+
+export type AesGcmEncryptResult = {
+  ciphertext: string; // base64url
+  iv: string;         // base64url (12 bytes)
+  tag: string;        // base64url (16 bytes auth tag)
+};
+
+export function aesGcmEncrypt(params: AesGcmEncryptParams): AesGcmEncryptResult {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", params.key, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(params.plaintext, "utf8"),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+
+  return {
+    ciphertext: base64UrlEncode(encrypted),
+    iv: base64UrlEncode(iv),
+    tag: base64UrlEncode(tag),
+  };
+}
+
+export type AesGcmDecryptParams = {
+  key: Buffer;
+  ciphertext: string; // base64url
+  iv: string;         // base64url
+  tag: string;        // base64url
+};
+
+export function aesGcmDecrypt(params: AesGcmDecryptParams): string {
+  const decipher = createDecipheriv(
+    "aes-256-gcm",
+    params.key,
+    base64UrlDecode(params.iv),
+  );
+  decipher.setAuthTag(base64UrlDecode(params.tag));
+  const decrypted = Buffer.concat([
+    decipher.update(base64UrlDecode(params.ciphertext)),
+    decipher.final(),
+  ]);
+  return decrypted.toString("utf8");
+}
+
+// ---------------------------------------------------------------------------
+// Ed25519 key pairs
+// ---------------------------------------------------------------------------
+
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+export type Ed25519KeyPair = {
+  publicKey: KeyObject;
+  privateKey: KeyObject;
+  publicKeyB64: string; // raw 32-byte pub, base64url
+};
+
+export function ed25519GenerateKeyPair(): Ed25519KeyPair {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const pubRaw = Buffer.from(publicKey.export({ type: "spki", format: "der" })).subarray(-32);
+  return { publicKey, privateKey, publicKeyB64: base64UrlEncode(pubRaw) };
+}
+
+export function ed25519Sign(privateKey: KeyObject, data: Buffer): Buffer {
+  return Buffer.from(sign(null, data, privateKey));
+}
+
+export function ed25519Verify(publicKey: KeyObject, data: Buffer, sig: Buffer): boolean {
+  try {
+    return verify(null, data, publicKey, sig);
+  } catch {
+    return false;
+  }
+}
+
+export function importEd25519PublicKey(b64: string): KeyObject {
+  const raw = base64UrlDecode(b64);
+  if (raw.length !== 32) throw new Error(`Invalid Ed25519 public key length: ${raw.length}`);
+  const spki = Buffer.concat([ED25519_SPKI_PREFIX, raw]);
+  return createPublicKey({ key: spki, format: "der", type: "spki" });
+}
+
+export function exportPublicKeyRaw(key: KeyObject): Buffer {
+  return Buffer.from(key.export({ type: "spki", format: "der" })).subarray(-32);
+}
+
+export function exportPrivateKeyPkcs8(key: KeyObject): Buffer {
+  return Buffer.from(key.export({ type: "pkcs8", format: "der" }));
+}
+
+export function importPrivateKeyPkcs8(der: Buffer): KeyObject {
+  return createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+}
+
+// Async HKDF-SHA256 (used for X3DH root derivation with nonce as salt)
+export function hkdfDerive(
+  ikm: Buffer,
+  salt: Buffer,
+  info: string,
+  length: number,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    hkdf("sha256", ikm, salt, Buffer.from(info, "utf8"), length, (err, derived) => {
+      if (err) reject(err);
+      else resolve(Buffer.from(derived));
+    });
+  });
+}
+
+// Sync HKDF-SHA256 (used for KDF chain advancement — called per-message)
+export function hkdfDeriveSync(ikm: Buffer, salt: Buffer, info: string, length: number): Buffer {
+  return Buffer.from(hkdfSync("sha256", ikm, salt, Buffer.from(info, "utf8"), length));
+}
+
+// ---------------------------------------------------------------------------
+// Timestamp validation
+// ---------------------------------------------------------------------------
+
+export function isTimestampValid(timestamp: number, toleranceMs = 300_000): boolean {
+  const diff = Math.abs(Date.now() - timestamp);
+  return diff <= toleranceMs;
+}
+
+// ---------------------------------------------------------------------------
+// Fingerprint — SHA-256 of identity keys, truncated to 16 bytes hex (32 chars)
+// ---------------------------------------------------------------------------
+
+export function computeFingerprint(identity: {
+  signKey: { publicKeyB64: string };
+  dhKey: { publicKeyB64: string };
+}): string {
+  const signRaw = base64UrlDecode(identity.signKey.publicKeyB64);
+  const dhRaw = base64UrlDecode(identity.dhKey.publicKeyB64);
+  const hash = createHash("sha256")
+    .update(signRaw)
+    .update(dhRaw)
+    .digest();
+  return hash.subarray(0, 16).toString("hex");
+}

package/src/envelope-v2.ts

@@ -0,0 +1,201 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import {
+  base64UrlEncode,
+  base64UrlDecode,
+  importX25519PublicKey,
+} from "./crypto.js";
+import {
+  advanceChain,
+  needsDhRatchet,
+  applySendDhRatchet,
+  executeDhRatchet,
+  type RatchetState,
+  type DhRatchetConfig,
+} from "./ratchet.js";
+
+// ---------------------------------------------------------------------------
+// Wire format
+// ---------------------------------------------------------------------------
+
+export type EnvelopeV2 = {
+  v: 2;
+  accountId: string;
+  direction: "plugin_to_app" | "app_to_plugin";
+  counter: number;
+  timestamp: number;
+  dhRatchetKey?: string; // X25519 pub raw b64url, only when DH ratchet emitted
+  ciphertext: string;    // base64url AES-256-GCM ciphertext
+  iv: string;            // base64url 12 bytes
+  tag: string;           // base64url 16 bytes auth tag
+};
+
+// ---------------------------------------------------------------------------
+// AAD construction
+// ---------------------------------------------------------------------------
+
+function buildAad(env: Pick<EnvelopeV2, "v" | "accountId" | "direction" | "counter" | "timestamp">): Buffer {
+  return Buffer.from(
+    `${env.v}|${env.accountId}|${env.direction}|${env.counter}|${env.timestamp}`,
+    "utf8",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Encrypt
+// ---------------------------------------------------------------------------
+
+export type EncryptParams = {
+  session: RatchetState;
+  accountId: string;
+  plaintext: string;
+  dhRatchetCfg: DhRatchetConfig;
+};
+
+export type EncryptResult = {
+  envelope: EnvelopeV2;
+  updatedSession: RatchetState;
+};
+
+export function encryptEnvelopeV2(params: EncryptParams): EncryptResult {
+  let session = params.session;
+  let dhRatchetKey: string | undefined;
+
+  // DH ratchet step (if needed)
+  if (needsDhRatchet(session, params.dhRatchetCfg)) {
+    const { updatedSession, newEphPubB64 } = applySendDhRatchet(session);
+    session = updatedSession;
+    dhRatchetKey = newEphPubB64;
+  }
+
+  // Advance KDF chain to get message key
+  const { messageKey, next: nextSending } = advanceChain(session.sending);
+  const counter = nextSending.counter - 1; // counter of THIS message
+  const timestamp = Date.now();
+
+  // Build partial envelope (without ciphertext) for AAD
+  const partial = {
+    v: 2 as const,
+    accountId: params.accountId,
+    direction: "plugin_to_app" as const,
+    counter,
+    timestamp,
+  };
+  const aad = buildAad(partial);
+
+  // AES-256-GCM encrypt
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", messageKey, iv);
+  cipher.setAAD(aad);
+  const cipherBuf = Buffer.concat([
+    cipher.update(params.plaintext, "utf8"),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+
+  // Zero message key
+  messageKey.fill(0);
+
+  const updatedSession: RatchetState = {
+    ...session,
+    sending: nextSending,
+    dhRatchetSendCount: session.dhRatchetSendCount + 1,
+  };
+
+  const envelope: EnvelopeV2 = {
+    v: 2,
+    accountId: params.accountId,
+    direction: "plugin_to_app",
+    counter,
+    timestamp,
+    ...(dhRatchetKey ? { dhRatchetKey } : {}),
+    ciphertext: base64UrlEncode(cipherBuf),
+    iv: base64UrlEncode(iv),
+    tag: base64UrlEncode(tag),
+  };
+
+  return { envelope, updatedSession };
+}
+
+// ---------------------------------------------------------------------------
+// Validate inbound envelope (before decryption)
+// ---------------------------------------------------------------------------
+
+export type ValidationResult = { valid: true } | { valid: false; error: string };
+
+// Counter validation uses strict monotonic ordering (no window).
+// This is intentional: allowing out-of-order counters would require
+// tracking a window of seen counters and complicates replay protection.
+export function validateEnvelopeV2(
+  envelope: EnvelopeV2,
+  session: RatchetState,
+): ValidationResult {
+  if (envelope.v !== 2) return { valid: false, error: "version_mismatch" };
+  if (envelope.direction !== "app_to_plugin") return { valid: false, error: "direction_mismatch" };
+  if (envelope.counter < session.receiving.counter) {
+    return { valid: false, error: "counter_mismatch" };
+  }
+  return { valid: true };
+}
+
+// ---------------------------------------------------------------------------
+// Decrypt
+// ---------------------------------------------------------------------------
+
+export type DecryptParams = {
+  session: RatchetState;
+  envelope: EnvelopeV2;
+};
+
+export type DecryptResult = {
+  plaintext: string;
+  updatedSession: RatchetState;
+};
+
+export function decryptEnvelopeV2(params: DecryptParams): DecryptResult {
+  let { session } = params;
+  const { envelope } = params;
+
+  // DH ratchet step (if sender included new ephemeral)
+  if (envelope.dhRatchetKey) {
+    const peerNewEphPub = importX25519PublicKey(envelope.dhRatchetKey);
+    const { newSession } = executeDhRatchet(session, peerNewEphPub);
+    session = newSession;
+  }
+
+  // Validate counter (strict monotonic after potential ratchet)
+  if (envelope.counter < session.receiving.counter) {
+    throw new Error("counter_mismatch");
+  }
+
+  // Advance receiving chain
+  const { messageKey, next: nextReceiving } = advanceChain(session.receiving);
+
+  const aad = buildAad(envelope);
+
+  try {
+    const decipher = createDecipheriv(
+      "aes-256-gcm",
+      messageKey,
+      base64UrlDecode(envelope.iv),
+    );
+    decipher.setAuthTag(base64UrlDecode(envelope.tag));
+    decipher.setAAD(aad);
+    const plainBuf = Buffer.concat([
+      decipher.update(base64UrlDecode(envelope.ciphertext)),
+      decipher.final(),
+    ]);
+    const plaintext = plainBuf.toString("utf8");
+    messageKey.fill(0);
+
+    const updatedSession: RatchetState = {
+      ...session,
+      receiving: nextReceiving,
+      dhRatchetRecvCount: session.dhRatchetRecvCount + 1,
+    };
+
+    return { plaintext, updatedSession };
+  } catch (err) {
+    messageKey.fill(0);
+    throw err;
+  }
+}