@openclaw/nostr 2026.1.29

package/src/nostr-state-store.test.ts

@@ -0,0 +1,129 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+import {
+  readNostrBusState,
+  writeNostrBusState,
+  computeSinceTimestamp,
+} from "./nostr-state-store.js";
+import { setNostrRuntime } from "./runtime.js";
+
+async function withTempStateDir<T>(fn: (dir: string) => Promise<T>) {
+  const previous = process.env.OPENCLAW_STATE_DIR;
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-nostr-"));
+  process.env.OPENCLAW_STATE_DIR = dir;
+  setNostrRuntime({
+    state: {
+      resolveStateDir: (env, homedir) => {
+        const override =
+          env.OPENCLAW_STATE_DIR?.trim() || env.OPENCLAW_STATE_DIR?.trim();
+        if (override) return override;
+        return path.join(homedir(), ".openclaw");
+      },
+    },
+  } as PluginRuntime);
+  try {
+    return await fn(dir);
+  } finally {
+    if (previous === undefined) delete process.env.OPENCLAW_STATE_DIR;
+    else process.env.OPENCLAW_STATE_DIR = previous;
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+describe("nostr bus state store", () => {
+  it("persists and reloads state across restarts", async () => {
+    await withTempStateDir(async () => {
+      // Fresh start - no state
+      expect(await readNostrBusState({ accountId: "test-bot" })).toBeNull();
+
+      // Write state
+      await writeNostrBusState({
+        accountId: "test-bot",
+        lastProcessedAt: 1700000000,
+        gatewayStartedAt: 1700000100,
+      });
+
+      // Read it back
+      const state = await readNostrBusState({ accountId: "test-bot" });
+      expect(state).toEqual({
+        version: 2,
+        lastProcessedAt: 1700000000,
+        gatewayStartedAt: 1700000100,
+        recentEventIds: [],
+      });
+    });
+  });
+
+  it("isolates state by accountId", async () => {
+    await withTempStateDir(async () => {
+      await writeNostrBusState({
+        accountId: "bot-a",
+        lastProcessedAt: 1000,
+        gatewayStartedAt: 1000,
+      });
+      await writeNostrBusState({
+        accountId: "bot-b",
+        lastProcessedAt: 2000,
+        gatewayStartedAt: 2000,
+      });
+
+      const stateA = await readNostrBusState({ accountId: "bot-a" });
+      const stateB = await readNostrBusState({ accountId: "bot-b" });
+
+      expect(stateA?.lastProcessedAt).toBe(1000);
+      expect(stateB?.lastProcessedAt).toBe(2000);
+    });
+  });
+});
+
+describe("computeSinceTimestamp", () => {
+  it("returns now for null state (fresh start)", () => {
+    const now = 1700000000;
+    expect(computeSinceTimestamp(null, now)).toBe(now);
+  });
+
+  it("uses lastProcessedAt when available", () => {
+    const state = {
+      version: 2,
+      lastProcessedAt: 1699999000,
+      gatewayStartedAt: null,
+      recentEventIds: [],
+    };
+    expect(computeSinceTimestamp(state, 1700000000)).toBe(1699999000);
+  });
+
+  it("uses gatewayStartedAt when lastProcessedAt is null", () => {
+    const state = {
+      version: 2,
+      lastProcessedAt: null,
+      gatewayStartedAt: 1699998000,
+      recentEventIds: [],
+    };
+    expect(computeSinceTimestamp(state, 1700000000)).toBe(1699998000);
+  });
+
+  it("uses the max of both timestamps", () => {
+    const state = {
+      version: 2,
+      lastProcessedAt: 1699999000,
+      gatewayStartedAt: 1699998000,
+      recentEventIds: [],
+    };
+    expect(computeSinceTimestamp(state, 1700000000)).toBe(1699999000);
+  });
+
+  it("falls back to now if both are null", () => {
+    const state = {
+      version: 2,
+      lastProcessedAt: null,
+      gatewayStartedAt: null,
+      recentEventIds: [],
+    };
+    expect(computeSinceTimestamp(state, 1700000000)).toBe(1700000000);
+  });
+});

package/src/nostr-state-store.ts

@@ -0,0 +1,226 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { getNostrRuntime } from "./runtime.js";
+
+const STORE_VERSION = 2;
+const PROFILE_STATE_VERSION = 1;
+
+type NostrBusStateV1 = {
+  version: 1;
+  /** Unix timestamp (seconds) of the last processed event */
+  lastProcessedAt: number | null;
+  /** Gateway startup timestamp (seconds) - events before this are old */
+  gatewayStartedAt: number | null;
+};
+
+type NostrBusState = {
+  version: 2;
+  /** Unix timestamp (seconds) of the last processed event */
+  lastProcessedAt: number | null;
+  /** Gateway startup timestamp (seconds) - events before this are old */
+  gatewayStartedAt: number | null;
+  /** Recent processed event IDs for overlap dedupe across restarts */
+  recentEventIds: string[];
+};
+
+/** Profile publish state (separate from bus state) */
+export type NostrProfileState = {
+  version: 1;
+  /** Unix timestamp (seconds) of last successful profile publish */
+  lastPublishedAt: number | null;
+  /** Event ID of the last published profile */
+  lastPublishedEventId: string | null;
+  /** Per-relay publish results from last attempt */
+  lastPublishResults: Record<string, "ok" | "failed" | "timeout"> | null;
+};
+
+function normalizeAccountId(accountId?: string): string {
+  const trimmed = accountId?.trim();
+  if (!trimmed) return "default";
+  return trimmed.replace(/[^a-z0-9._-]+/gi, "_");
+}
+
+function resolveNostrStatePath(
+  accountId?: string,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const stateDir = getNostrRuntime().state.resolveStateDir(env, os.homedir);
+  const normalized = normalizeAccountId(accountId);
+  return path.join(stateDir, "nostr", `bus-state-${normalized}.json`);
+}
+
+function resolveNostrProfileStatePath(
+  accountId?: string,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const stateDir = getNostrRuntime().state.resolveStateDir(env, os.homedir);
+  const normalized = normalizeAccountId(accountId);
+  return path.join(stateDir, "nostr", `profile-state-${normalized}.json`);
+}
+
+function safeParseState(raw: string): NostrBusState | null {
+  try {
+    const parsed = JSON.parse(raw) as Partial<NostrBusState> & Partial<NostrBusStateV1>;
+
+    if (parsed?.version === 2) {
+      return {
+        version: 2,
+        lastProcessedAt: typeof parsed.lastProcessedAt === "number" ? parsed.lastProcessedAt : null,
+        gatewayStartedAt: typeof parsed.gatewayStartedAt === "number" ? parsed.gatewayStartedAt : null,
+        recentEventIds: Array.isArray(parsed.recentEventIds)
+          ? parsed.recentEventIds.filter((x): x is string => typeof x === "string")
+          : [],
+      };
+    }
+
+    // Back-compat: v1 state files
+    if (parsed?.version === 1) {
+      return {
+        version: 2,
+        lastProcessedAt: typeof parsed.lastProcessedAt === "number" ? parsed.lastProcessedAt : null,
+        gatewayStartedAt: typeof parsed.gatewayStartedAt === "number" ? parsed.gatewayStartedAt : null,
+        recentEventIds: [],
+      };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function readNostrBusState(params: {
+  accountId?: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<NostrBusState | null> {
+  const filePath = resolveNostrStatePath(params.accountId, params.env);
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    return safeParseState(raw);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") return null;
+    return null;
+  }
+}
+
+export async function writeNostrBusState(params: {
+  accountId?: string;
+  lastProcessedAt: number;
+  gatewayStartedAt: number;
+  recentEventIds?: string[];
+  env?: NodeJS.ProcessEnv;
+}): Promise<void> {
+  const filePath = resolveNostrStatePath(params.accountId, params.env);
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(
+    dir,
+    `${path.basename(filePath)}.${crypto.randomUUID()}.tmp`
+  );
+  const payload: NostrBusState = {
+    version: STORE_VERSION,
+    lastProcessedAt: params.lastProcessedAt,
+    gatewayStartedAt: params.gatewayStartedAt,
+    recentEventIds: (params.recentEventIds ?? []).filter((x): x is string => typeof x === "string"),
+  };
+  await fs.writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf-8",
+  });
+  await fs.chmod(tmp, 0o600);
+  await fs.rename(tmp, filePath);
+}
+
+/**
+ * Determine the `since` timestamp for subscription.
+ * Returns the later of: lastProcessedAt or gatewayStartedAt (both from disk),
+ * falling back to `now` for fresh starts.
+ */
+export function computeSinceTimestamp(
+  state: NostrBusState | null,
+  nowSec: number = Math.floor(Date.now() / 1000)
+): number {
+  if (!state) return nowSec;
+
+  // Use the most recent timestamp we have
+  const candidates = [
+    state.lastProcessedAt,
+    state.gatewayStartedAt,
+  ].filter((t): t is number => t !== null && t > 0);
+
+  if (candidates.length === 0) return nowSec;
+  return Math.max(...candidates);
+}
+
+// ============================================================================
+// Profile State Management
+// ============================================================================
+
+function safeParseProfileState(raw: string): NostrProfileState | null {
+  try {
+    const parsed = JSON.parse(raw) as Partial<NostrProfileState>;
+
+    if (parsed?.version === 1) {
+      return {
+        version: 1,
+        lastPublishedAt:
+          typeof parsed.lastPublishedAt === "number" ? parsed.lastPublishedAt : null,
+        lastPublishedEventId:
+          typeof parsed.lastPublishedEventId === "string" ? parsed.lastPublishedEventId : null,
+        lastPublishResults:
+          parsed.lastPublishResults && typeof parsed.lastPublishResults === "object"
+            ? (parsed.lastPublishResults as Record<string, "ok" | "failed" | "timeout">)
+            : null,
+      };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function readNostrProfileState(params: {
+  accountId?: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<NostrProfileState | null> {
+  const filePath = resolveNostrProfileStatePath(params.accountId, params.env);
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    return safeParseProfileState(raw);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") return null;
+    return null;
+  }
+}
+
+export async function writeNostrProfileState(params: {
+  accountId?: string;
+  lastPublishedAt: number;
+  lastPublishedEventId: string;
+  lastPublishResults: Record<string, "ok" | "failed" | "timeout">;
+  env?: NodeJS.ProcessEnv;
+}): Promise<void> {
+  const filePath = resolveNostrProfileStatePath(params.accountId, params.env);
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(
+    dir,
+    `${path.basename(filePath)}.${crypto.randomUUID()}.tmp`
+  );
+  const payload: NostrProfileState = {
+    version: PROFILE_STATE_VERSION,
+    lastPublishedAt: params.lastPublishedAt,
+    lastPublishedEventId: params.lastPublishedEventId,
+    lastPublishResults: params.lastPublishResults,
+  };
+  await fs.writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf-8",
+  });
+  await fs.chmod(tmp, 0o600);
+  await fs.rename(tmp, filePath);
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setNostrRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getNostrRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Nostr runtime not initialized");
+  }
+  return runtime;
+}

package/src/seen-tracker.ts

@@ -0,0 +1,271 @@
+/**
+ * LRU-based seen event tracker with TTL support.
+ * Prevents unbounded memory growth under high load or abuse.
+ */
+
+export interface SeenTrackerOptions {
+  /** Maximum number of entries to track (default: 100,000) */
+  maxEntries?: number;
+  /** TTL in milliseconds (default: 1 hour) */
+  ttlMs?: number;
+  /** Prune interval in milliseconds (default: 10 minutes) */
+  pruneIntervalMs?: number;
+}
+
+export interface SeenTracker {
+  /** Check if an ID has been seen (also marks it as seen if not) */
+  has: (id: string) => boolean;
+  /** Mark an ID as seen */
+  add: (id: string) => void;
+  /** Check if ID exists without marking */
+  peek: (id: string) => boolean;
+  /** Delete an ID */
+  delete: (id: string) => void;
+  /** Clear all entries */
+  clear: () => void;
+  /** Get current size */
+  size: () => number;
+  /** Stop the pruning timer */
+  stop: () => void;
+  /** Pre-seed with IDs (useful for restart recovery) */
+  seed: (ids: string[]) => void;
+}
+
+interface Entry {
+  seenAt: number;
+  // For LRU: track order via doubly-linked list
+  prev: string | null;
+  next: string | null;
+}
+
+/**
+ * Create a new seen tracker with LRU eviction and TTL expiration.
+ */
+export function createSeenTracker(options?: SeenTrackerOptions): SeenTracker {
+  const maxEntries = options?.maxEntries ?? 100_000;
+  const ttlMs = options?.ttlMs ?? 60 * 60 * 1000; // 1 hour
+  const pruneIntervalMs = options?.pruneIntervalMs ?? 10 * 60 * 1000; // 10 minutes
+
+  // Main storage
+  const entries = new Map<string, Entry>();
+
+  // LRU tracking: head = most recent, tail = least recent
+  let head: string | null = null;
+  let tail: string | null = null;
+
+  // Move an entry to the front (most recently used)
+  function moveToFront(id: string): void {
+    const entry = entries.get(id);
+    if (!entry) return;
+
+    // Already at front
+    if (head === id) return;
+
+    // Remove from current position
+    if (entry.prev) {
+      const prevEntry = entries.get(entry.prev);
+      if (prevEntry) prevEntry.next = entry.next;
+    }
+    if (entry.next) {
+      const nextEntry = entries.get(entry.next);
+      if (nextEntry) nextEntry.prev = entry.prev;
+    }
+
+    // Update tail if this was the tail
+    if (tail === id) {
+      tail = entry.prev;
+    }
+
+    // Move to front
+    entry.prev = null;
+    entry.next = head;
+    if (head) {
+      const headEntry = entries.get(head);
+      if (headEntry) headEntry.prev = id;
+    }
+    head = id;
+
+    // If no tail, this is also the tail
+    if (!tail) tail = id;
+  }
+
+  // Remove an entry from the linked list
+  function removeFromList(id: string): void {
+    const entry = entries.get(id);
+    if (!entry) return;
+
+    if (entry.prev) {
+      const prevEntry = entries.get(entry.prev);
+      if (prevEntry) prevEntry.next = entry.next;
+    } else {
+      head = entry.next;
+    }
+
+    if (entry.next) {
+      const nextEntry = entries.get(entry.next);
+      if (nextEntry) nextEntry.prev = entry.prev;
+    } else {
+      tail = entry.prev;
+    }
+  }
+
+  // Evict the least recently used entry
+  function evictLRU(): void {
+    if (!tail) return;
+    const idToEvict = tail;
+    removeFromList(idToEvict);
+    entries.delete(idToEvict);
+  }
+
+  // Prune expired entries
+  function pruneExpired(): void {
+    const now = Date.now();
+    const toDelete: string[] = [];
+
+    for (const [id, entry] of entries) {
+      if (now - entry.seenAt > ttlMs) {
+        toDelete.push(id);
+      }
+    }
+
+    for (const id of toDelete) {
+      removeFromList(id);
+      entries.delete(id);
+    }
+  }
+
+  // Start pruning timer
+  let pruneTimer: ReturnType<typeof setInterval> | undefined;
+  if (pruneIntervalMs > 0) {
+    pruneTimer = setInterval(pruneExpired, pruneIntervalMs);
+    // Don't keep process alive just for pruning
+    if (pruneTimer.unref) pruneTimer.unref();
+  }
+
+  function add(id: string): void {
+    const now = Date.now();
+
+    // If already exists, update and move to front
+    const existing = entries.get(id);
+    if (existing) {
+      existing.seenAt = now;
+      moveToFront(id);
+      return;
+    }
+
+    // Evict if at capacity
+    while (entries.size >= maxEntries) {
+      evictLRU();
+    }
+
+    // Add new entry at front
+    const newEntry: Entry = {
+      seenAt: now,
+      prev: null,
+      next: head,
+    };
+
+    if (head) {
+      const headEntry = entries.get(head);
+      if (headEntry) headEntry.prev = id;
+    }
+
+    entries.set(id, newEntry);
+    head = id;
+    if (!tail) tail = id;
+  }
+
+  function has(id: string): boolean {
+    const entry = entries.get(id);
+    if (!entry) {
+      add(id);
+      return false;
+    }
+
+    // Check if expired
+    if (Date.now() - entry.seenAt > ttlMs) {
+      removeFromList(id);
+      entries.delete(id);
+      add(id);
+      return false;
+    }
+
+    // Mark as recently used
+    entry.seenAt = Date.now();
+    moveToFront(id);
+    return true;
+  }
+
+  function peek(id: string): boolean {
+    const entry = entries.get(id);
+    if (!entry) return false;
+
+    // Check if expired
+    if (Date.now() - entry.seenAt > ttlMs) {
+      removeFromList(id);
+      entries.delete(id);
+      return false;
+    }
+
+    return true;
+  }
+
+  function deleteEntry(id: string): void {
+    if (entries.has(id)) {
+      removeFromList(id);
+      entries.delete(id);
+    }
+  }
+
+  function clear(): void {
+    entries.clear();
+    head = null;
+    tail = null;
+  }
+
+  function size(): number {
+    return entries.size;
+  }
+
+  function stop(): void {
+    if (pruneTimer) {
+      clearInterval(pruneTimer);
+      pruneTimer = undefined;
+    }
+  }
+
+  function seed(ids: string[]): void {
+    const now = Date.now();
+    // Seed in reverse order so first IDs end up at front
+    for (let i = ids.length - 1; i >= 0; i--) {
+      const id = ids[i];
+      if (!entries.has(id) && entries.size < maxEntries) {
+        const newEntry: Entry = {
+          seenAt: now,
+          prev: null,
+          next: head,
+        };
+
+        if (head) {
+          const headEntry = entries.get(head);
+          if (headEntry) headEntry.prev = id;
+        }
+
+        entries.set(id, newEntry);
+        head = id;
+        if (!tail) tail = id;
+      }
+    }
+  }
+
+  return {
+    has,
+    add,
+    peek,
+    delete: deleteEntry,
+    clear,
+    size,
+    stop,
+    seed,
+  };
+}