@openclaw/nostr 2026.3.13 → 2026.5.2-beta.1

package/src/nostr-bus.ts

@@ -1,13 +1,11 @@
-import {
-  SimplePool,
-  finalizeEvent,
-  getPublicKey,
-  verifyEvent,
-  nip19,
-  type Event,
-} from "nostr-tools";
+import { SimplePool, finalizeEvent, getPublicKey, verifyEvent, type Event } from "nostr-tools";
 import { decrypt, encrypt } from "nostr-tools/nip04";
+import {
+  createDirectDmPreCryptoGuardPolicy,
+  type DirectDmPreCryptoGuardPolicyOverrides,
+} from "openclaw/plugin-sdk/direct-dm-guard-policy";
 import type { NostrProfile } from "./config-schema.js";
+import { DEFAULT_RELAYS } from "./default-relays.js";
 import {
   createMetrics,
   createNoopMetrics,
@@ -15,6 +13,7 @@ import {
   type MetricsSnapshot,
   type MetricEvent,
 } from "./metrics.js";
+import { validatePrivateKey } from "./nostr-key-utils.js";
 import { publishProfile as publishProfileFn, type ProfilePublishResult } from "./nostr-profile.js";
 import {
   readNostrBusState,
@@ -25,8 +24,6 @@ import {
 } from "./nostr-state-store.js";
 import { createSeenTracker, type SeenTracker } from "./seen-tracker.js";
 
-export const DEFAULT_RELAYS = ["wss://relay.damus.io", "wss://nos.lol"];
-
 // ============================================================================
 // Constants
 // ============================================================================
@@ -34,6 +31,7 @@ export const DEFAULT_RELAYS = ["wss://relay.damus.io", "wss://nos.lol"];
 const STARTUP_LOOKBACK_SEC = 120; // tolerate relay lag / clock skew
 const MAX_PERSISTED_EVENT_IDS = 5000;
 const STATE_PERSIST_DEBOUNCE_MS = 5000; // Debounce state writes
+const DEFAULT_INBOUND_GUARD_POLICY = createDirectDmPreCryptoGuardPolicy();
 
 // Circuit breaker configuration
 const CIRCUIT_BREAKER_THRESHOLD = 5; // failures before opening
@@ -46,7 +44,7 @@ const HEALTH_WINDOW_MS = 60000; // 1 minute window for health stats
 // Types
 // ============================================================================
 
-export interface NostrBusOptions {
+interface NostrBusOptions {
   /** Private key in hex or nsec format */
   privateKey: string;
   /** WebSocket relay URLs (defaults to damus + nos.lol) */
@@ -58,7 +56,15 @@ export interface NostrBusOptions {
     pubkey: string,
     text: string,
     reply: (text: string) => Promise<void>,
+    meta: { eventId: string; createdAt: number },
   ) => Promise<void>;
+  /** Called after signature verification and before decrypt to allow sender policy checks (optional) */
+  authorizeSender?: (params: {
+    senderPubkey: string;
+    reply: (text: string) => Promise<void>;
+  }) => Promise<"allow" | "block" | "pairing">;
+  /** Override pre-crypto DM guardrails for tests or future channel tuning (optional) */
+  guardPolicy?: DirectDmPreCryptoGuardPolicyOverrides;
   /** Called on errors (optional) */
   onError?: (error: Error, context: string) => void;
   /** Called on connection status changes (optional) */
@@ -75,6 +81,62 @@ export interface NostrBusOptions {
   seenTtlMs?: number;
 }
 
+type FixedWindowRateLimiter = {
+  isRateLimited: (key: string, nowMs?: number) => boolean;
+  size: () => number;
+  clear: () => void;
+};
+
+function createFixedWindowRateLimiter(params: {
+  windowMs: number;
+  maxRequests: number;
+  maxTrackedKeys: number;
+}): FixedWindowRateLimiter {
+  const windowMs = Math.max(1, Math.floor(params.windowMs));
+  const maxRequests = Math.max(1, Math.floor(params.maxRequests));
+  const maxTrackedKeys = Math.max(1, Math.floor(params.maxTrackedKeys));
+  const state = new Map<string, { count: number; windowStartMs: number }>();
+
+  const touch = (key: string, value: { count: number; windowStartMs: number }) => {
+    state.delete(key);
+    state.set(key, value);
+  };
+
+  const prune = (nowMs: number) => {
+    for (const [key, entry] of state) {
+      if (nowMs - entry.windowStartMs >= windowMs) {
+        state.delete(key);
+      }
+    }
+    while (state.size > maxTrackedKeys) {
+      const oldest = state.keys().next().value;
+      if (!oldest) {
+        break;
+      }
+      state.delete(oldest);
+    }
+  };
+
+  return {
+    isRateLimited: (key: string, nowMs = Date.now()) => {
+      if (!key) {
+        return false;
+      }
+      prune(nowMs);
+      const existing = state.get(key);
+      if (!existing || nowMs - existing.windowStartMs >= windowMs) {
+        touch(key, { count: 1, windowStartMs: nowMs });
+        return false;
+      }
+      const nextCount = existing.count + 1;
+      touch(key, { count: nextCount, windowStartMs: existing.windowStartMs });
+      return nextCount > maxRequests;
+    },
+    size: () => state.size,
+    clear: () => state.clear(),
+  };
+}
+
 export interface NostrBusHandle {
   /** Stop the bus and close connections */
   close: () => void;
@@ -271,46 +333,6 @@ function createRelayHealthTracker(): RelayHealthTracker {
   };
 }
 
-// ============================================================================
-// Key Validation
-// ============================================================================
-
-/**
- * Validate and normalize a private key (accepts hex or nsec format)
- */
-export function validatePrivateKey(key: string): Uint8Array {
-  const trimmed = key.trim();
-
-  // Handle nsec (bech32) format
-  if (trimmed.startsWith("nsec1")) {
-    const decoded = nip19.decode(trimmed);
-    if (decoded.type !== "nsec") {
-      throw new Error("Invalid nsec key: wrong type");
-    }
-    return decoded.data;
-  }
-
-  // Handle hex format
-  if (!/^[0-9a-fA-F]{64}$/.test(trimmed)) {
-    throw new Error("Private key must be 64 hex characters or nsec bech32 format");
-  }
-
-  // Convert hex string to Uint8Array
-  const bytes = new Uint8Array(32);
-  for (let i = 0; i < 32; i++) {
-    bytes[i] = parseInt(trimmed.slice(i * 2, i * 2 + 2), 16);
-  }
-  return bytes;
-}
-
-/**
- * Get public key from private key (hex or nsec format)
- */
-export function getPublicKeyFromPrivate(privateKey: string): string {
-  const sk = validatePrivateKey(privateKey);
-  return getPublicKey(sk);
-}
-
 // ============================================================================
 // Main Bus
 // ============================================================================
@@ -323,6 +345,7 @@ export async function startNostrBus(options: NostrBusOptions): Promise<NostrBusH
     privateKey,
     relays = DEFAULT_RELAYS,
     onMessage,
+    authorizeSender,
     onError,
     onEose,
     onMetric,
@@ -335,6 +358,14 @@ export async function startNostrBus(options: NostrBusOptions): Promise<NostrBusH
   const pool = new SimplePool();
   const accountId = options.accountId ?? pk.slice(0, 16);
   const gatewayStartedAt = Math.floor(Date.now() / 1000);
+  const guardPolicy = createDirectDmPreCryptoGuardPolicy({
+    ...DEFAULT_INBOUND_GUARD_POLICY,
+    ...options.guardPolicy,
+    rateLimit: {
+      ...DEFAULT_INBOUND_GUARD_POLICY.rateLimit,
+      ...options.guardPolicy?.rateLimit,
+    },
+  });
 
   // Initialize metrics
   const metrics = onMetric ? createMetrics(onMetric) : createNoopMetrics();
@@ -397,6 +428,23 @@ export async function startNostrBus(options: NostrBusOptions): Promise<NostrBusH
   }
 
   const inflight = new Set<string>();
+  const perSenderRateLimiter = createFixedWindowRateLimiter({
+    windowMs: guardPolicy.rateLimit.windowMs,
+    maxRequests: guardPolicy.rateLimit.maxPerSenderPerWindow,
+    maxTrackedKeys: guardPolicy.rateLimit.maxTrackedSenderKeys,
+  });
+  const globalRateLimiter = createFixedWindowRateLimiter({
+    windowMs: guardPolicy.rateLimit.windowMs,
+    maxRequests: guardPolicy.rateLimit.maxGlobalPerWindow,
+    maxTrackedKeys: 1,
+  });
+
+  const updateRateLimiterSizeMetric = () => {
+    metrics.emit(
+      "memory.rate_limiter_entries",
+      perSenderRateLimiter.size() + globalRateLimiter.size(),
+    );
+  };
 
   // Event handler
   async function handleEvent(event: Event): Promise<void> {
@@ -410,15 +458,34 @@ export async function startNostrBus(options: NostrBusOptions): Promise<NostrBusH
       }
       inflight.add(event.id);
 
+      const markSeen = () => {
+        seen.add(event.id);
+        metrics.emit("memory.seen_tracker_size", seen.size());
+      };
+      const rejectAndMarkSeen = (metric: Parameters<typeof metrics.emit>[0]) => {
+        markSeen();
+        metrics.emit(metric);
+      };
+
       // Self-message loop prevention: skip our own messages
       if (event.pubkey === pk) {
-        metrics.emit("event.rejected.self_message");
+        rejectAndMarkSeen("event.rejected.self_message");
         return;
       }
 
       // Skip events older than our `since` (relay may ignore filter)
       if (event.created_at < since) {
-        metrics.emit("event.rejected.stale");
+        rejectAndMarkSeen("event.rejected.stale");
+        return;
+      }
+
+      if (event.created_at > Math.floor(Date.now() / 1000) + guardPolicy.maxFutureSkewSec) {
+        metrics.emit("event.rejected.future");
+        return;
+      }
+
+      if (!guardPolicy.allowedKinds.includes(event.kind)) {
+        rejectAndMarkSeen("event.rejected.wrong_kind");
         return;
       }
 
@@ -431,20 +498,81 @@ export async function startNostrBus(options: NostrBusOptions): Promise<NostrBusH
         }
       }
       if (!targetsUs) {
-        metrics.emit("event.rejected.wrong_kind");
+        rejectAndMarkSeen("event.rejected.wrong_kind");
+        return;
+      }
+
+      const replyTo = async (text: string): Promise<void> => {
+        await sendEncryptedDm(
+          pool,
+          sk,
+          event.pubkey,
+          text,
+          relays,
+          metrics,
+          circuitBreakers,
+          healthTracker,
+          onError,
+        );
+      };
+
+      const rejectIfGlobalRateLimited = (): boolean => {
+        updateRateLimiterSizeMetric();
+        if (globalRateLimiter.isRateLimited("global")) {
+          metrics.emit("rate_limit.global");
+          metrics.emit("event.rejected.rate_limited");
+          updateRateLimiterSizeMetric();
+          return true;
+        }
+        updateRateLimiterSizeMetric();
+        return false;
+      };
+
+      const rejectIfVerifiedSenderRateLimited = (): boolean => {
+        updateRateLimiterSizeMetric();
+        if (perSenderRateLimiter.isRateLimited(event.pubkey)) {
+          metrics.emit("rate_limit.per_sender");
+          metrics.emit("event.rejected.rate_limited");
+          updateRateLimiterSizeMetric();
+          return true;
+        }
+        updateRateLimiterSizeMetric();
+        return false;
+      };
+
+      if (Buffer.byteLength(event.content, "utf8") > guardPolicy.maxCiphertextBytes) {
+        if (rejectIfGlobalRateLimited()) {
+          return;
+        }
+        rejectAndMarkSeen("event.rejected.oversized_ciphertext");
+        return;
+      }
+
+      if (rejectIfGlobalRateLimited()) {
         return;
       }
 
       // Verify signature (must pass before we trust the event)
       if (!verifyEvent(event)) {
-        metrics.emit("event.rejected.invalid_signature");
+        rejectAndMarkSeen("event.rejected.invalid_signature");
         onError?.(new Error("Invalid signature"), `event ${event.id}`);
         return;
       }
 
-      // Mark seen AFTER verify (don't cache invalid IDs)
-      seen.add(event.id);
-      metrics.emit("memory.seen_tracker_size", seen.size());
+      if (rejectIfVerifiedSenderRateLimited()) {
+        return;
+      }
+
+      if (authorizeSender) {
+        const decision = await authorizeSender({
+          senderPubkey: event.pubkey,
+          reply: replyTo,
+        });
+        if (decision !== "allow") {
+          markSeen();
+          return;
+        }
+      }
 
       // Decrypt the message
       let plaintext: string;
@@ -452,29 +580,27 @@ export async function startNostrBus(options: NostrBusOptions): Promise<NostrBusH
         plaintext = decrypt(sk, event.pubkey, event.content);
         metrics.emit("decrypt.success");
       } catch (err) {
+        markSeen();
         metrics.emit("decrypt.failure");
         metrics.emit("event.rejected.decrypt_failed");
         onError?.(err as Error, `decrypt from ${event.pubkey}`);
         return;
       }
 
-      // Create reply function (try relays by health score)
-      const replyTo = async (text: string): Promise<void> => {
-        await sendEncryptedDm(
-          pool,
-          sk,
-          event.pubkey,
-          text,
-          relays,
-          metrics,
-          circuitBreakers,
-          healthTracker,
-          onError,
-        );
-      };
+      if (Buffer.byteLength(plaintext, "utf8") > guardPolicy.maxPlaintextBytes) {
+        markSeen();
+        metrics.emit("event.rejected.oversized_plaintext");
+        return;
+      }
 
       // Call the message handler
-      await onMessage(event.pubkey, plaintext, replyTo);
+      await onMessage(event.pubkey, plaintext, replyTo, {
+        eventId: event.id,
+        createdAt: event.created_at,
+      });
+
+      // Only cache successful deliveries so handler failures can retry.
+      markSeen();
 
       // Mark as processed
       metrics.emit("event.processed");
@@ -569,6 +695,8 @@ export async function startNostrBus(options: NostrBusOptions): Promise<NostrBusH
     close: () => {
       sub.close();
       seen.stop();
+      perSenderRateLimiter.clear();
+      globalRateLimiter.clear();
       // Flush pending state write synchronously on close
       if (pendingWrite) {
         clearTimeout(pendingWrite);
@@ -632,8 +760,11 @@ async function sendEncryptedDm(
 
     const startTime = Date.now();
     try {
-      // oxlint-disable-next-line typescript/await-thenable typesciript/no-floating-promises
-      await pool.publish([relay], reply);
+      const [publishPromise] = pool.publish([relay], reply);
+      if (!publishPromise) {
+        throw new Error(`Failed to create publish promise for relay ${relay}`);
+      }
+      await publishPromise;
       const latency = Date.now() - startTime;
 
       // Record success
@@ -656,64 +787,3 @@ async function sendEncryptedDm(
 
   throw new Error(`Failed to publish to any relay: ${lastError?.message}`);
 }
-
-// ============================================================================
-// Pubkey Utilities
-// ============================================================================
-
-/**
- * Check if a string looks like a valid Nostr pubkey (hex or npub)
- */
-export function isValidPubkey(input: string): boolean {
-  if (typeof input !== "string") {
-    return false;
-  }
-  const trimmed = input.trim();
-
-  // npub format
-  if (trimmed.startsWith("npub1")) {
-    try {
-      const decoded = nip19.decode(trimmed);
-      return decoded.type === "npub";
-    } catch {
-      return false;
-    }
-  }
-
-  // Hex format
-  return /^[0-9a-fA-F]{64}$/.test(trimmed);
-}
-
-/**
- * Normalize a pubkey to hex format (accepts npub or hex)
- */
-export function normalizePubkey(input: string): string {
-  const trimmed = input.trim();
-
-  // npub format - decode to hex
-  if (trimmed.startsWith("npub1")) {
-    const decoded = nip19.decode(trimmed);
-    if (decoded.type !== "npub") {
-      throw new Error("Invalid npub key");
-    }
-    // Convert Uint8Array to hex string
-    return Array.from(decoded.data as unknown as Uint8Array)
-      .map((b) => b.toString(16).padStart(2, "0"))
-      .join("");
-  }
-
-  // Already hex - validate and return lowercase
-  if (!/^[0-9a-fA-F]{64}$/.test(trimmed)) {
-    throw new Error("Pubkey must be 64 hex characters or npub format");
-  }
-  return trimmed.toLowerCase();
-}
-
-/**
- * Convert a hex pubkey to npub format
- */
-export function pubkeyToNpub(hexPubkey: string): string {
-  const normalized = normalizePubkey(hexPubkey);
-  // npubEncode expects a hex string, not Uint8Array
-  return nip19.npubEncode(normalized);
-}

package/src/nostr-key-utils.ts

@@ -0,0 +1,94 @@
+import { getPublicKey, nip19 } from "nostr-tools";
+
+/**
+ * Validate and normalize a private key (accepts hex or nsec format)
+ */
+export function validatePrivateKey(key: string): Uint8Array {
+  const trimmed = key.trim();
+
+  // Handle nsec (bech32) format
+  if (trimmed.startsWith("nsec1")) {
+    const decoded = nip19.decode(trimmed);
+    if (decoded.type !== "nsec") {
+      throw new Error("Invalid nsec key: wrong type");
+    }
+    return decoded.data;
+  }
+
+  // Handle hex format
+  if (!/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+    throw new Error("Private key must be 64 hex characters or nsec bech32 format");
+  }
+
+  // Convert hex string to Uint8Array
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = Number.parseInt(trimmed.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Get public key from private key (hex or nsec format)
+ */
+export function getPublicKeyFromPrivate(privateKey: string): string {
+  const sk = validatePrivateKey(privateKey);
+  return getPublicKey(sk);
+}
+
+/**
+ * Check if a string looks like a valid Nostr pubkey (hex or npub)
+ */
+export function isValidPubkey(input: string): boolean {
+  if (typeof input !== "string") {
+    return false;
+  }
+  const trimmed = input.trim();
+
+  // npub format
+  if (trimmed.startsWith("npub1")) {
+    try {
+      const decoded = nip19.decode(trimmed);
+      return decoded.type === "npub";
+    } catch {
+      return false;
+    }
+  }
+
+  // Hex format
+  return /^[0-9a-fA-F]{64}$/.test(trimmed);
+}
+
+/**
+ * Normalize a pubkey to hex format (accepts npub or hex)
+ */
+export function normalizePubkey(input: string): string {
+  const trimmed = input.trim();
+
+  // npub format - decode to hex
+  if (trimmed.startsWith("npub1")) {
+    const decoded = nip19.decode(trimmed);
+    if (decoded.type !== "npub") {
+      throw new Error("Invalid npub key");
+    }
+    // Convert Uint8Array to hex string
+    return Array.from(decoded.data as unknown as Uint8Array)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+  }
+
+  // Already hex - validate and return lowercase
+  if (!/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+    throw new Error("Pubkey must be 64 hex characters or npub format");
+  }
+  return trimmed.toLowerCase();
+}
+
+/**
+ * Convert a hex pubkey to npub format
+ */
+export function pubkeyToNpub(hexPubkey: string): string {
+  const normalized = normalizePubkey(hexPubkey);
+  // npubEncode expects a hex string, not Uint8Array
+  return nip19.npubEncode(normalized);
+}

package/src/nostr-profile-core.ts

@@ -0,0 +1,134 @@
+import { type NostrProfile, NostrProfileSchema } from "./config-schema.js";
+
+/** NIP-01 profile content (JSON inside kind:0 event). */
+export interface ProfileContent {
+  name?: string;
+  display_name?: string;
+  about?: string;
+  picture?: string;
+  banner?: string;
+  website?: string;
+  nip05?: string;
+  lud16?: string;
+}
+
+/**
+ * Convert our config profile schema to NIP-01 content format.
+ * Strips undefined fields and validates URLs.
+ */
+export function profileToContent(profile: NostrProfile): ProfileContent {
+  const validated = NostrProfileSchema.parse(profile);
+
+  const content: ProfileContent = {};
+
+  if (validated.name !== undefined) {
+    content.name = validated.name;
+  }
+  if (validated.displayName !== undefined) {
+    content.display_name = validated.displayName;
+  }
+  if (validated.about !== undefined) {
+    content.about = validated.about;
+  }
+  if (validated.picture !== undefined) {
+    content.picture = validated.picture;
+  }
+  if (validated.banner !== undefined) {
+    content.banner = validated.banner;
+  }
+  if (validated.website !== undefined) {
+    content.website = validated.website;
+  }
+  if (validated.nip05 !== undefined) {
+    content.nip05 = validated.nip05;
+  }
+  if (validated.lud16 !== undefined) {
+    content.lud16 = validated.lud16;
+  }
+
+  return content;
+}
+
+/**
+ * Convert NIP-01 content format back to our config profile schema.
+ * Useful for importing existing profiles from relays.
+ */
+export function contentToProfile(content: ProfileContent): NostrProfile {
+  const profile: NostrProfile = {};
+
+  if (content.name !== undefined) {
+    profile.name = content.name;
+  }
+  if (content.display_name !== undefined) {
+    profile.displayName = content.display_name;
+  }
+  if (content.about !== undefined) {
+    profile.about = content.about;
+  }
+  if (content.picture !== undefined) {
+    profile.picture = content.picture;
+  }
+  if (content.banner !== undefined) {
+    profile.banner = content.banner;
+  }
+  if (content.website !== undefined) {
+    profile.website = content.website;
+  }
+  if (content.nip05 !== undefined) {
+    profile.nip05 = content.nip05;
+  }
+  if (content.lud16 !== undefined) {
+    profile.lud16 = content.lud16;
+  }
+
+  return profile;
+}
+
+/**
+ * Validate a profile without throwing (returns result object).
+ */
+export function validateProfile(profile: unknown): {
+  valid: boolean;
+  profile?: NostrProfile;
+  errors?: string[];
+} {
+  const result = NostrProfileSchema.safeParse(profile);
+
+  if (result.success) {
+    return { valid: true, profile: result.data };
+  }
+
+  return {
+    valid: false,
+    errors: result.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`),
+  };
+}
+
+/**
+ * Sanitize profile text fields to prevent XSS when displaying in UI.
+ * Escapes HTML special characters.
+ */
+export function sanitizeProfileForDisplay(profile: NostrProfile): NostrProfile {
+  const escapeHtml = (str: string | undefined): string | undefined => {
+    if (str === undefined) {
+      return undefined;
+    }
+    return str
+      .replace(/&/g, "&")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#039;");
+  };
+
+  return {
+    name: escapeHtml(profile.name),
+    displayName: escapeHtml(profile.displayName),
+    about: escapeHtml(profile.about),
+    picture: profile.picture,
+    banner: profile.banner,
+    website: profile.website,
+    nip05: escapeHtml(profile.nip05),
+    lud16: escapeHtml(profile.lud16),
+  };
+}

package/src/nostr-profile-http-runtime.ts

@@ -0,0 +1,6 @@
+export {
+  readJsonBodyWithLimit,
+  requestBodyErrorToText,
+} from "openclaw/plugin-sdk/webhook-request-guards";
+export { createFixedWindowRateLimiter } from "openclaw/plugin-sdk/webhook-ingress";
+export { getPluginRuntimeGatewayRequestScope } from "../runtime-api.js";