@soyeht/soyeht 0.1.1

package/src/pairing.ts

@@ -0,0 +1,324 @@
+import { randomBytes } from "node:crypto";
+import type { GatewayRequestHandler } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  base64UrlDecode,
+  base64UrlEncode,
+  computeFingerprint,
+  ed25519Sign,
+  ed25519Verify,
+  importEd25519PublicKey,
+  importX25519PublicKey,
+} from "./crypto.js";
+import { normalizeAccountId } from "./config.js";
+import { deleteSession, savePeer, type PeerIdentity } from "./identity.js";
+import { zeroBuffer } from "./ratchet.js";
+import type { SecurityV2Deps } from "./service.js";
+
+const DEFAULT_PAIRING_TTL_MS = 90_000;
+const MIN_PAIRING_TTL_MS = 30_000;
+const MAX_PAIRING_TTL_MS = 300_000;
+
+function clampPairingTtlMs(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_PAIRING_TTL_MS;
+  }
+  return Math.min(Math.max(Math.trunc(value), MIN_PAIRING_TTL_MS), MAX_PAIRING_TTL_MS);
+}
+
+export function buildPairingQrTranscript(params: {
+  accountId: string;
+  pairingToken: string;
+  expiresAt: number;
+  allowOverwrite: boolean;
+  pluginIdentityKey: string;
+  pluginDhKey: string;
+  fingerprint: string;
+}): Buffer {
+  const {
+    accountId,
+    pairingToken,
+    expiresAt,
+    allowOverwrite,
+    pluginIdentityKey,
+    pluginDhKey,
+    fingerprint,
+  } = params;
+  return Buffer.from(
+    `pairing_qr_v1|${accountId}|${pairingToken}|${expiresAt}|${allowOverwrite ? 1 : 0}|${pluginIdentityKey}|${pluginDhKey}|${fingerprint}`,
+    "utf8",
+  );
+}
+
+export function buildPairingProofTranscript(params: {
+  accountId: string;
+  pairingToken: string;
+  expiresAt: number;
+  appIdentityKey: string;
+  appDhKey: string;
+}): Buffer {
+  const { accountId, pairingToken, expiresAt, appIdentityKey, appDhKey } = params;
+  return Buffer.from(
+    `pairing_proof_v1|${accountId}|${pairingToken}|${expiresAt}|${appIdentityKey}|${appDhKey}`,
+    "utf8",
+  );
+}
+
+function signPairingQrPayload(
+  privateKey: Parameters<typeof ed25519Sign>[0],
+  payload: Parameters<typeof buildPairingQrTranscript>[0],
+): string {
+  return base64UrlEncode(ed25519Sign(privateKey, buildPairingQrTranscript(payload)));
+}
+
+function clearAccountSessionState(v2deps: SecurityV2Deps, accountId: string): void {
+  const existingSession = v2deps.sessions.get(accountId);
+  if (existingSession) {
+    zeroBuffer(existingSession.rootKey);
+    zeroBuffer(existingSession.sending.chainKey);
+    zeroBuffer(existingSession.receiving.chainKey);
+    v2deps.sessions.delete(accountId);
+  }
+
+  for (const [key, pending] of v2deps.pendingHandshakes) {
+    if (pending.accountId === accountId) {
+      v2deps.pendingHandshakes.delete(key);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.security.identity — expose plugin public keys
+// ---------------------------------------------------------------------------
+
+export function handleSecurityIdentity(
+  _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 callerKey = normalizeAccountId(params["accountId"] as string | undefined);
+    const { allowed } = v2deps.rateLimiter.check(`identity:${callerKey}`);
+    if (!allowed) {
+      respond(false, undefined, { code: "RATE_LIMITED", message: "Too many requests" });
+      return;
+    }
+
+    respond(true, {
+      pluginIdentityKey: v2deps.identity.signKey.publicKeyB64,
+      pluginDhKey: v2deps.identity.dhKey.publicKeyB64,
+    });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.security.pairing.start — create a single-use QR payload
+// ---------------------------------------------------------------------------
+
+export function handleSecurityPairingStart(
+  _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 allowOverwrite = params["allowOverwrite"] === true;
+    const ttlMs = clampPairingTtlMs(params["ttlMs"]);
+    const { allowed } = v2deps.rateLimiter.check(`pairing:start:${accountId}`);
+    if (!allowed) {
+      respond(false, undefined, { code: "RATE_LIMITED", message: "Too many requests" });
+      return;
+    }
+
+    if (v2deps.peers.has(accountId) && !allowOverwrite) {
+      respond(false, undefined, {
+        code: "PEER_ALREADY_PAIRED",
+        message: "Account already paired. Start a new QR with allowOverwrite=true to replace it.",
+      });
+      return;
+    }
+
+    for (const [token, session] of v2deps.pairingSessions) {
+      if (session.accountId === accountId) {
+        v2deps.pairingSessions.delete(token);
+      }
+    }
+
+    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,
+      accountId,
+      pairingToken,
+      expiresAt,
+      allowOverwrite,
+      pluginIdentityKey: v2deps.identity.signKey.publicKeyB64,
+      pluginDhKey: v2deps.identity.dhKey.publicKeyB64,
+      fingerprint,
+    };
+    const signature = signPairingQrPayload(v2deps.identity.signKey.privateKey, payload);
+    const qrPayload = { ...payload, signature };
+
+    v2deps.pairingSessions.set(pairingToken, {
+      token: pairingToken,
+      accountId,
+      expiresAt,
+      allowOverwrite,
+    });
+
+    respond(true, {
+      qrPayload,
+      qrText: JSON.stringify(qrPayload),
+      expiresAt,
+    });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// soyeht.security.pair — consume a QR token and register the peer keys
+// ---------------------------------------------------------------------------
+
+export function handleSecurityPair(
+  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 { allowed } = v2deps.rateLimiter.check(`pair:${accountId}`);
+    if (!allowed) {
+      respond(false, undefined, { code: "RATE_LIMITED", message: "Too many requests" });
+      return;
+    }
+
+    const pairingToken = params["pairingToken"] as string | undefined;
+    const appIdentityKey = params["appIdentityKey"] as string | undefined;
+    const appDhKey = params["appDhKey"] as string | undefined;
+    const appSignature = params["appSignature"] as string | undefined;
+
+    if (!pairingToken || !appIdentityKey || !appDhKey || !appSignature) {
+      respond(false, undefined, {
+        code: "INVALID_PARAMS",
+        message: "Missing required params: pairingToken, appIdentityKey, appDhKey, appSignature",
+      });
+      return;
+    }
+
+    const pairingSession = v2deps.pairingSessions.get(pairingToken);
+    if (!pairingSession) {
+      respond(false, undefined, {
+        code: "PAIRING_REQUIRED",
+        message: "No active pairing session. Scan a fresh QR code first.",
+      });
+      return;
+    }
+
+    if (pairingSession.expiresAt <= Date.now()) {
+      v2deps.pairingSessions.delete(pairingToken);
+      respond(false, undefined, {
+        code: "PAIRING_EXPIRED",
+        message: "Pairing QR expired. Scan a fresh QR code first.",
+      });
+      return;
+    }
+
+    if (pairingSession.accountId !== accountId) {
+      respond(false, undefined, {
+        code: "PAIRING_ACCOUNT_MISMATCH",
+        message: "Pairing token is bound to a different accountId.",
+      });
+      return;
+    }
+
+    let appIdentityPub;
+    try {
+      appIdentityPub = importEd25519PublicKey(appIdentityKey);
+    } catch {
+      respond(false, undefined, { code: "INVALID_KEY", message: "Invalid appIdentityKey" });
+      return;
+    }
+
+    try {
+      importX25519PublicKey(appDhKey);
+    } catch {
+      respond(false, undefined, { code: "INVALID_KEY", message: "Invalid appDhKey" });
+      return;
+    }
+
+    const proofTranscript = buildPairingProofTranscript({
+      accountId,
+      pairingToken,
+      expiresAt: pairingSession.expiresAt,
+      appIdentityKey,
+      appDhKey,
+    });
+    if (!ed25519Verify(appIdentityPub, proofTranscript, base64UrlDecode(appSignature))) {
+      respond(false, undefined, {
+        code: "INVALID_SIGNATURE",
+        message: "App signature verification failed",
+      });
+      return;
+    }
+
+    const existingPeer = v2deps.peers.get(accountId);
+    if (existingPeer && !pairingSession.allowOverwrite) {
+      respond(false, undefined, {
+        code: "PEER_ALREADY_PAIRED",
+        message: "Account already paired. Scan a QR with allowOverwrite=true to replace it.",
+      });
+      return;
+    }
+
+    clearAccountSessionState(v2deps, accountId);
+    if (v2deps.stateDir) {
+      await deleteSession(v2deps.stateDir, accountId).catch(() => {});
+    }
+
+    const peer: PeerIdentity = { accountId, identityKeyB64: appIdentityKey, dhKeyB64: appDhKey };
+    v2deps.peers.set(accountId, peer);
+    v2deps.pairingSessions.delete(pairingToken);
+
+    if (v2deps.stateDir) {
+      await savePeer(v2deps.stateDir, peer);
+    }
+
+    api.logger.info("[soyeht] Security pairing completed", {
+      accountId,
+      allowOverwrite: pairingSession.allowOverwrite,
+    });
+
+    respond(true, {
+      accountId,
+      handshakeRequired: true,
+      pluginIdentityKey: v2deps.identity.signKey.publicKeyB64,
+      pluginDhKey: v2deps.identity.dhKey.publicKeyB64,
+      fingerprint: computeFingerprint(v2deps.identity),
+    });
+  };
+}

package/src/ratchet.ts

@@ -0,0 +1,262 @@
+import type { KeyObject } from "node:crypto";
+import {
+  generateX25519KeyPair,
+  computeSharedSecret,
+  hkdfDeriveSync,
+  exportPrivateKeyPkcs8,
+  exportPublicKeyRaw,
+  importX25519PublicKey,
+  importPrivateKeyPkcs8,
+  base64UrlEncode,
+  base64UrlDecode,
+  type X25519KeyPair,
+} from "./crypto.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ChainState = {
+  chainKey: Buffer;
+  counter: number; // monotonic, per direction
+};
+
+export type RatchetState = {
+  accountId: string;
+  rootKey: Buffer;
+  sending: ChainState;
+  receiving: ChainState;
+  myCurrentEphDhKey: X25519KeyPair;
+  peerLastEphDhKeyB64: string;    // peer's last ephemeral pub, raw b64url
+  dhRatchetSendCount: number;     // messages sent since last DH ratchet emitted
+  dhRatchetRecvCount: number;
+  createdAt: number;
+  expiresAt: number;
+};
+
+export type DhRatchetConfig = {
+  intervalMessages: number; // default 50
+  intervalMs: number;       // default 3_600_000
+};
+
+// ---------------------------------------------------------------------------
+// KDF chain advancement (sync, per-message)
+// ---------------------------------------------------------------------------
+
+const EMPTY = Buffer.alloc(0);
+
+export function advanceChain(state: ChainState): { messageKey: Buffer; next: ChainState } {
+  const messageKey = hkdfDeriveSync(state.chainKey, EMPTY, "soyeht-v2-msg-key", 32);
+  const nextChainKey = hkdfDeriveSync(state.chainKey, EMPTY, "soyeht-v2-chain-advance", 32);
+  // Zero the consumed chain key
+  state.chainKey.fill(0);
+  return {
+    messageKey,
+    next: { chainKey: nextChainKey, counter: state.counter + 1 },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// DH ratchet trigger
+// ---------------------------------------------------------------------------
+
+export function needsDhRatchet(
+  session: RatchetState,
+  cfg: DhRatchetConfig,
+): boolean {
+  if (session.dhRatchetSendCount >= cfg.intervalMessages) return true;
+  if (Date.now() - session.createdAt >= cfg.intervalMs) return true;
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// DH ratchet — SENDER side
+// Called inside encryptEnvelopeV2 when needsDhRatchet() is true.
+// Returns updated session + the new ephemeral pub to include in envelope.
+// ---------------------------------------------------------------------------
+
+export function applySendDhRatchet(session: RatchetState): {
+  updatedSession: RatchetState;
+  newEphPubB64: string;
+} {
+  const newEphKp = generateX25519KeyPair();
+  const peerPub = importX25519PublicKey(session.peerLastEphDhKeyB64);
+  const dhShared = computeSharedSecret(newEphKp.privateKey, peerPub);
+
+  const newRoot = hkdfDeriveSync(
+    Buffer.concat([session.rootKey, dhShared]),
+    EMPTY,
+    "soyeht-v2-dh-ratchet",
+    32,
+  );
+
+  // Sender: non-swapped (send = "chain-send", recv = "chain-recv")
+  const newSendChain = hkdfDeriveSync(newRoot, EMPTY, "soyeht-v2-chain-send", 32);
+  const newRecvChain = hkdfDeriveSync(newRoot, EMPTY, "soyeht-v2-chain-recv", 32);
+
+  // Zero old secrets
+  session.rootKey.fill(0);
+  dhShared.fill(0);
+
+  const updatedSession: RatchetState = {
+    ...session,
+    rootKey: newRoot,
+    sending: { chainKey: newSendChain, counter: session.sending.counter },
+    receiving: { chainKey: newRecvChain, counter: session.receiving.counter },
+    myCurrentEphDhKey: newEphKp,
+    dhRatchetSendCount: 0,
+  };
+
+  return { updatedSession, newEphPubB64: newEphKp.publicKeyB64 };
+}
+
+// ---------------------------------------------------------------------------
+// DH ratchet — RECEIVER side
+// Called when an incoming envelope has dhRatchetKey.
+// Uses SWAPPED labels (recv of envelope sender = sender's "send" chain).
+// ---------------------------------------------------------------------------
+
+export function executeDhRatchet(
+  session: RatchetState,
+  peerNewEphPub: KeyObject,
+): {
+  newSession: RatchetState;
+  myNewEphPubB64: string;
+} {
+  const dhShared = computeSharedSecret(session.myCurrentEphDhKey.privateKey, peerNewEphPub);
+
+  const newRoot = hkdfDeriveSync(
+    Buffer.concat([session.rootKey, dhShared]),
+    EMPTY,
+    "soyeht-v2-dh-ratchet",
+    32,
+  );
+
+  // Receiver: SWAPPED (my recv = sender's "chain-send", my send = "chain-recv")
+  const newRecvChain = hkdfDeriveSync(newRoot, EMPTY, "soyeht-v2-chain-send", 32);
+  const newSendChain = hkdfDeriveSync(newRoot, EMPTY, "soyeht-v2-chain-recv", 32);
+
+  // Zero old secrets
+  session.rootKey.fill(0);
+  dhShared.fill(0);
+
+  // Generate new ephemeral for our next DH ratchet
+  const myNewEphKp = generateX25519KeyPair();
+  const peerPubB64 = base64UrlEncode(exportPublicKeyRaw(peerNewEphPub));
+
+  const newSession: RatchetState = {
+    ...session,
+    rootKey: newRoot,
+    sending: { chainKey: newSendChain, counter: session.sending.counter },
+    receiving: { chainKey: newRecvChain, counter: session.receiving.counter },
+    myCurrentEphDhKey: myNewEphKp,
+    peerLastEphDhKeyB64: peerPubB64,
+    dhRatchetRecvCount: 0,
+  };
+
+  return { newSession, myNewEphPubB64: myNewEphKp.publicKeyB64 };
+}
+
+// ---------------------------------------------------------------------------
+// Zeroize a buffer
+// ---------------------------------------------------------------------------
+
+export function zeroBuffer(buf: Buffer): void {
+  buf.fill(0);
+}
+
+// ---------------------------------------------------------------------------
+// Deep clone — protects stored session from in-place Buffer mutations
+// ---------------------------------------------------------------------------
+
+export function cloneRatchetSession(session: RatchetState): RatchetState {
+  return {
+    ...session,
+    rootKey: Buffer.from(session.rootKey),
+    sending: {
+      chainKey: Buffer.from(session.sending.chainKey),
+      counter: session.sending.counter,
+    },
+    receiving: {
+      chainKey: Buffer.from(session.receiving.chainKey),
+      counter: session.receiving.counter,
+    },
+    // myCurrentEphDhKey contains KeyObjects (immutable) + publicKeyRaw Buffer
+    myCurrentEphDhKey: {
+      ...session.myCurrentEphDhKey,
+      publicKeyRaw: Buffer.from(session.myCurrentEphDhKey.publicKeyRaw),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Serialization (for disk persistence)
+// ---------------------------------------------------------------------------
+
+type SerializedX25519KeyPair = {
+  publicSpki: string;   // base64url SPKI DER
+  privatePkcs8: string; // base64url PKCS8 DER
+  publicKeyB64: string; // base64url raw 32 bytes
+};
+
+function serializeX25519KeyPair(kp: X25519KeyPair): SerializedX25519KeyPair {
+  return {
+    publicSpki: base64UrlEncode(Buffer.from(kp.publicKey.export({ type: "spki", format: "der" }))),
+    privatePkcs8: base64UrlEncode(exportPrivateKeyPkcs8(kp.privateKey)),
+    publicKeyB64: kp.publicKeyB64,
+  };
+}
+
+function deserializeX25519KeyPair(s: SerializedX25519KeyPair): X25519KeyPair {
+  const publicKey = importX25519PublicKey(s.publicKeyB64);
+  const privateKey = importPrivateKeyPkcs8(base64UrlDecode(s.privatePkcs8));
+  const publicKeyRaw = base64UrlDecode(s.publicKeyB64);
+  return { publicKey, privateKey, publicKeyRaw, publicKeyB64: s.publicKeyB64 };
+}
+
+export function serializeSession(session: RatchetState): Record<string, unknown> {
+  return {
+    accountId: session.accountId,
+    rootKey: base64UrlEncode(session.rootKey),
+    sending: {
+      chainKey: base64UrlEncode(session.sending.chainKey),
+      counter: session.sending.counter,
+    },
+    receiving: {
+      chainKey: base64UrlEncode(session.receiving.chainKey),
+      counter: session.receiving.counter,
+    },
+    myCurrentEphDhKey: serializeX25519KeyPair(session.myCurrentEphDhKey),
+    peerLastEphDhKeyB64: session.peerLastEphDhKeyB64,
+    dhRatchetSendCount: session.dhRatchetSendCount,
+    dhRatchetRecvCount: session.dhRatchetRecvCount,
+    createdAt: session.createdAt,
+    expiresAt: session.expiresAt,
+  };
+}
+
+export function deserializeSession(raw: unknown): RatchetState {
+  const r = raw as Record<string, unknown>;
+  const s = r["sending"] as Record<string, unknown>;
+  const rv = r["receiving"] as Record<string, unknown>;
+  const ephRaw = r["myCurrentEphDhKey"] as SerializedX25519KeyPair;
+
+  return {
+    accountId: r["accountId"] as string,
+    rootKey: base64UrlDecode(r["rootKey"] as string),
+    sending: {
+      chainKey: base64UrlDecode(s["chainKey"] as string),
+      counter: s["counter"] as number,
+    },
+    receiving: {
+      chainKey: base64UrlDecode(rv["chainKey"] as string),
+      counter: rv["counter"] as number,
+    },
+    myCurrentEphDhKey: deserializeX25519KeyPair(ephRaw),
+    peerLastEphDhKeyB64: r["peerLastEphDhKeyB64"] as string,
+    dhRatchetSendCount: r["dhRatchetSendCount"] as number,
+    dhRatchetRecvCount: r["dhRatchetRecvCount"] as number,
+    createdAt: r["createdAt"] as number,
+    expiresAt: r["expiresAt"] as number,
+  };
+}