@openclaw/nostr 2026.3.13 → 2026.5.1-beta.2

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

@@ -1,11 +1,13 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import type { PluginRuntime } from "openclaw/plugin-sdk/nostr";
 import { describe, expect, it } from "vitest";
+import type { PluginRuntime } from "../runtime-api.js";
 import {
   readNostrBusState,
+  readNostrProfileState,
   writeNostrBusState,
+  writeNostrProfileState,
   computeSinceTimestamp,
 } from "./nostr-state-store.js";
 import { setNostrRuntime } from "./runtime.js";
@@ -18,7 +20,7 @@ async function withTempStateDir<T>(fn: (dir: string) => Promise<T>) {
     state: {
       resolveStateDir: (env, homedir) => {
         const stateEnv = env ?? process.env;
-        const override = stateEnv.OPENCLAW_STATE_DIR?.trim() || stateEnv.CLAWDBOT_STATE_DIR?.trim();
+        const override = stateEnv.OPENCLAW_STATE_DIR?.trim();
         if (override) {
           return override;
         }
@@ -83,6 +85,108 @@ describe("nostr bus state store", () => {
       expect(stateB?.lastProcessedAt).toBe(2000);
     });
   });
+
+  it("upgrades v1 bus state files on read", async () => {
+    await withTempStateDir(async (dir) => {
+      const filePath = path.join(dir, "nostr", "bus-state-test-bot.json");
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(
+        filePath,
+        JSON.stringify({
+          version: 1,
+          lastProcessedAt: 1700000000,
+          gatewayStartedAt: 1700000100,
+        }),
+        "utf-8",
+      );
+
+      const state = await readNostrBusState({ accountId: "test-bot" });
+      expect(state).toEqual({
+        version: 2,
+        lastProcessedAt: 1700000000,
+        gatewayStartedAt: 1700000100,
+        recentEventIds: [],
+      });
+    });
+  });
+
+  it("drops malformed recent event ids while keeping the state", async () => {
+    await withTempStateDir(async (dir) => {
+      const filePath = path.join(dir, "nostr", "bus-state-test-bot.json");
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(
+        filePath,
+        JSON.stringify({
+          version: 2,
+          lastProcessedAt: 1700000000,
+          gatewayStartedAt: 1700000100,
+          recentEventIds: ["evt-1", 2, null],
+        }),
+        "utf-8",
+      );
+
+      const state = await readNostrBusState({ accountId: "test-bot" });
+      expect(state).toEqual({
+        version: 2,
+        lastProcessedAt: 1700000000,
+        gatewayStartedAt: 1700000100,
+        recentEventIds: ["evt-1"],
+      });
+    });
+  });
+});
+
+describe("nostr profile state store", () => {
+  it("persists and reloads profile publish state", async () => {
+    await withTempStateDir(async () => {
+      await writeNostrProfileState({
+        accountId: "test-bot",
+        lastPublishedAt: 1700000000,
+        lastPublishedEventId: "evt-1",
+        lastPublishResults: {
+          "wss://relay.example": "ok",
+        },
+      });
+
+      const state = await readNostrProfileState({ accountId: "test-bot" });
+      expect(state).toEqual({
+        version: 1,
+        lastPublishedAt: 1700000000,
+        lastPublishedEventId: "evt-1",
+        lastPublishResults: {
+          "wss://relay.example": "ok",
+        },
+      });
+    });
+  });
+
+  it("drops malformed relay results while keeping valid state fields", async () => {
+    await withTempStateDir(async (dir) => {
+      const filePath = path.join(dir, "nostr", "profile-state-test-bot.json");
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(
+        filePath,
+        JSON.stringify({
+          version: 1,
+          lastPublishedAt: 1700000000,
+          lastPublishedEventId: "evt-1",
+          lastPublishResults: {
+            "wss://relay.example": "ok",
+            "wss://relay.bad": "unknown",
+          },
+        }),
+        "utf-8",
+      );
+
+      const state = await readNostrProfileState({ accountId: "test-bot" });
+      expect(state).toEqual({
+        version: 1,
+        lastPublishedAt: 1700000000,
+        lastPublishedEventId: "evt-1",
+        lastPublishResults: null,
+      });
+    });
+  });
 });
 
 describe("computeSinceTimestamp", () => {

package/src/nostr-state-store.ts

@@ -2,12 +2,14 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { safeParseJsonWithSchema } from "openclaw/plugin-sdk/extension-shared";
+import { z } from "zod";
 import { getNostrRuntime } from "./runtime.js";
 
 const STORE_VERSION = 2;
 const PROFILE_STATE_VERSION = 1;
 
-type NostrBusStateV1 = {
+type _NostrBusStateV1 = {
   version: 1;
   /** Unix timestamp (seconds) of the last processed event */
   lastProcessedAt: number | null;
@@ -26,7 +28,7 @@ type NostrBusState = {
 };
 
 /** Profile publish state (separate from bus state) */
-export type NostrProfileState = {
+type NostrProfileState = {
   version: 1;
   /** Unix timestamp (seconds) of last successful profile publish */
   lastPublishedAt: number | null;
@@ -36,6 +38,33 @@ export type NostrProfileState = {
   lastPublishResults: Record<string, "ok" | "failed" | "timeout"> | null;
 };
 
+const NullableFiniteNumberSchema = z.number().finite().nullable().catch(null);
+const NostrBusStateV1Schema = z.object({
+  version: z.literal(1),
+  lastProcessedAt: NullableFiniteNumberSchema,
+  gatewayStartedAt: NullableFiniteNumberSchema,
+});
+
+const NostrBusStateSchema = z.object({
+  version: z.literal(2),
+  lastProcessedAt: NullableFiniteNumberSchema,
+  gatewayStartedAt: NullableFiniteNumberSchema,
+  recentEventIds: z
+    .array(z.unknown())
+    .catch([])
+    .transform((ids) => ids.filter((id): id is string => typeof id === "string")),
+});
+
+const NostrProfileStateSchema = z.object({
+  version: z.literal(1),
+  lastPublishedAt: NullableFiniteNumberSchema,
+  lastPublishedEventId: z.string().nullable().catch(null),
+  lastPublishResults: z
+    .record(z.string(), z.enum(["ok", "failed", "timeout"]))
+    .nullable()
+    .catch(null),
+});
+
 function normalizeAccountId(accountId?: string): string {
   const trimmed = accountId?.trim();
   if (!trimmed) {
@@ -60,36 +89,23 @@ function resolveNostrProfileStatePath(
 }
 
 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: [],
-      };
-    }
+  const parsedV2 = safeParseJsonWithSchema(NostrBusStateSchema, raw);
+  if (parsedV2) {
+    return parsedV2;
+  }
 
-    return null;
-  } catch {
+  const parsedV1 = safeParseJsonWithSchema(NostrBusStateV1Schema, raw);
+  if (!parsedV1) {
     return null;
   }
+
+  // Back-compat: v1 state files
+  return {
+    version: 2,
+    lastProcessedAt: parsedV1.lastProcessedAt,
+    gatewayStartedAt: parsedV1.gatewayStartedAt,
+    recentEventIds: [],
+  };
 }
 
 export async function readNostrBusState(params: {
@@ -162,26 +178,7 @@ export function computeSinceTimestamp(
 // ============================================================================
 
 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
-            : null,
-      };
-    }
-
-    return null;
-  } catch {
-    return null;
-  }
+  return safeParseJsonWithSchema(NostrProfileStateSchema, raw);
 }
 
 export async function readNostrProfileState(params: {

package/src/runtime.ts

@@ -1,6 +1,9 @@
-import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
-import type { PluginRuntime } from "openclaw/plugin-sdk/nostr";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 
 const { setRuntime: setNostrRuntime, getRuntime: getNostrRuntime } =
-  createPluginRuntimeStore<PluginRuntime>("Nostr runtime not initialized");
+  createPluginRuntimeStore<PluginRuntime>({
+    pluginId: "nostr",
+    errorMessage: "Nostr runtime not initialized",
+  });
 export { getNostrRuntime, setNostrRuntime };

package/src/seen-tracker.ts

@@ -3,7 +3,7 @@
  * Prevents unbounded memory growth under high load or abuse.
  */
 
-export interface SeenTrackerOptions {
+interface SeenTrackerOptions {
   /** Maximum number of entries to track (default: 100,000) */
   maxEntries?: number;
   /** TTL in milliseconds (default: 1 hour) */

package/src/session-route.ts

@@ -0,0 +1,25 @@
+import {
+  buildChannelOutboundSessionRoute,
+  stripChannelTargetPrefix,
+  type ChannelOutboundSessionRouteParams,
+} from "openclaw/plugin-sdk/core";
+
+export function resolveNostrOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
+  const target = stripChannelTargetPrefix(params.target, "nostr");
+  if (!target) {
+    return null;
+  }
+  return buildChannelOutboundSessionRoute({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "nostr",
+    accountId: params.accountId,
+    peer: {
+      kind: "direct",
+      id: target,
+    },
+    chatType: "direct",
+    from: `nostr:${target}`,
+    to: `nostr:${target}`,
+  });
+}

package/src/setup-surface.ts

@@ -0,0 +1,265 @@
+import type { ChannelSetupAdapter } from "openclaw/plugin-sdk/channel-setup";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/routing";
+import {
+  hasConfiguredSecretInput,
+  normalizeSecretInputString,
+} from "openclaw/plugin-sdk/secret-input";
+import type { ChannelSetupDmPolicy, ChannelSetupWizard, DmPolicy } from "openclaw/plugin-sdk/setup";
+import {
+  createStandardChannelSetupStatus,
+  createTopLevelChannelDmPolicy,
+  createTopLevelChannelParsedAllowFromPrompt,
+  formatDocsLink,
+  mergeAllowFromEntries,
+  parseSetupEntriesWithParser,
+  patchTopLevelChannelConfigSection,
+  splitSetupEntries,
+} from "openclaw/plugin-sdk/setup";
+import { DEFAULT_RELAYS } from "./default-relays.js";
+import { getPublicKeyFromPrivate, normalizePubkey } from "./nostr-key-utils.js";
+import { resolveDefaultNostrAccountId, resolveNostrAccount } from "./types.js";
+
+const channel = "nostr" as const;
+
+const NOSTR_SETUP_HELP_LINES = [
+  "Use a Nostr private key in nsec or 64-character hex format.",
+  "Relay URLs are optional. Leave blank to keep the default relay set.",
+  "Env vars supported: NOSTR_PRIVATE_KEY (default account only).",
+  `Docs: ${formatDocsLink("/channels/nostr", "channels/nostr")}`,
+];
+
+const NOSTR_ALLOW_FROM_HELP_LINES = [
+  "Allowlist Nostr DMs by npub or hex pubkey.",
+  "Examples:",
+  "- npub1...",
+  "- nostr:npub1...",
+  "- 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "Multiple entries: comma-separated.",
+  `Docs: ${formatDocsLink("/channels/nostr", "channels/nostr")}`,
+];
+
+function buildNostrSetupPatch(accountId: string, patch: Record<string, unknown>) {
+  return {
+    ...(accountId !== DEFAULT_ACCOUNT_ID ? { defaultAccount: accountId } : {}),
+    ...patch,
+  };
+}
+
+function parseRelayUrls(raw: string): { relays: string[]; error?: string } {
+  const entries = splitSetupEntries(raw);
+  const relays: string[] = [];
+  for (const entry of entries) {
+    try {
+      const parsed = new URL(entry);
+      if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+        return { relays: [], error: `Relay must use ws:// or wss:// (${entry})` };
+      }
+    } catch {
+      return { relays: [], error: `Invalid relay URL: ${entry}` };
+    }
+    relays.push(entry);
+  }
+  return { relays: [...new Set(relays)] };
+}
+
+function parseNostrAllowFrom(raw: string): { entries: string[]; error?: string } {
+  return parseSetupEntriesWithParser(raw, (entry) => {
+    const cleaned = entry.replace(/^nostr:/i, "").trim();
+    try {
+      return { value: normalizePubkey(cleaned) };
+    } catch {
+      return { error: `Invalid Nostr pubkey: ${entry}` };
+    }
+  });
+}
+
+const promptNostrAllowFrom = createTopLevelChannelParsedAllowFromPrompt({
+  channel,
+  defaultAccountId: resolveDefaultNostrAccountId,
+  noteTitle: "Nostr allowlist",
+  noteLines: NOSTR_ALLOW_FROM_HELP_LINES,
+  message: "Nostr allowFrom",
+  placeholder: "npub1..., 0123abcd...",
+  parseEntries: parseNostrAllowFrom,
+  mergeEntries: ({ existing, parsed }) => mergeAllowFromEntries(existing, parsed),
+});
+
+const nostrDmPolicy: ChannelSetupDmPolicy = createTopLevelChannelDmPolicy({
+  label: "Nostr",
+  channel,
+  policyKey: "channels.nostr.dmPolicy",
+  allowFromKey: "channels.nostr.allowFrom",
+  getCurrent: (cfg) => (cfg.channels?.nostr?.dmPolicy as DmPolicy | undefined) ?? "pairing",
+  promptAllowFrom: promptNostrAllowFrom,
+});
+
+export const nostrSetupAdapter: ChannelSetupAdapter = {
+  resolveAccountId: ({ cfg, accountId }) => accountId?.trim() || resolveDefaultNostrAccountId(cfg),
+  applyAccountName: ({ cfg, accountId, name }) =>
+    patchTopLevelChannelConfigSection({
+      cfg,
+      channel,
+      patch: buildNostrSetupPatch(accountId, name?.trim() ? { name: name.trim() } : {}),
+    }),
+  validateInput: ({ input }) => {
+    const typedInput = input as {
+      useEnv?: boolean;
+      privateKey?: string;
+      relayUrls?: string;
+    };
+    if (!typedInput.useEnv) {
+      const privateKey = typedInput.privateKey?.trim();
+      if (!privateKey) {
+        return "Nostr requires --private-key or --use-env.";
+      }
+      try {
+        getPublicKeyFromPrivate(privateKey);
+      } catch {
+        return "Nostr private key must be valid nsec or 64-character hex.";
+      }
+    }
+    if (typedInput.relayUrls?.trim()) {
+      return parseRelayUrls(typedInput.relayUrls).error ?? null;
+    }
+    return null;
+  },
+  applyAccountConfig: ({ cfg, accountId, input }) => {
+    const typedInput = input as {
+      useEnv?: boolean;
+      privateKey?: string;
+      relayUrls?: string;
+    };
+    const relayResult = typedInput.relayUrls?.trim()
+      ? parseRelayUrls(typedInput.relayUrls)
+      : { relays: [] };
+    return patchTopLevelChannelConfigSection({
+      cfg,
+      channel,
+      enabled: true,
+      clearFields: typedInput.useEnv ? ["privateKey"] : undefined,
+      patch: buildNostrSetupPatch(accountId, {
+        ...(typedInput.useEnv ? {} : { privateKey: typedInput.privateKey?.trim() }),
+        ...(relayResult.relays.length > 0 ? { relays: relayResult.relays } : {}),
+      }),
+    });
+  },
+};
+
+export const nostrSetupWizard: ChannelSetupWizard = {
+  channel,
+  resolveAccountIdForConfigure: ({ accountOverride, defaultAccountId }) =>
+    accountOverride?.trim() || defaultAccountId,
+  resolveShouldPromptAccountIds: () => false,
+  status: createStandardChannelSetupStatus({
+    channelLabel: "Nostr",
+    configuredLabel: "configured",
+    unconfiguredLabel: "needs private key",
+    configuredHint: "configured",
+    unconfiguredHint: "needs private key",
+    configuredScore: 1,
+    unconfiguredScore: 0,
+    includeStatusLine: true,
+    resolveConfigured: ({ cfg }) => resolveNostrAccount({ cfg }).configured,
+    resolveExtraStatusLines: ({ cfg }) => {
+      const account = resolveNostrAccount({ cfg });
+      return [`Relays: ${account.relays.length || DEFAULT_RELAYS.length}`];
+    },
+  }),
+  introNote: {
+    title: "Nostr setup",
+    lines: NOSTR_SETUP_HELP_LINES,
+  },
+  envShortcut: {
+    prompt: "NOSTR_PRIVATE_KEY detected. Use env var?",
+    preferredEnvVar: "NOSTR_PRIVATE_KEY",
+    isAvailable: ({ cfg, accountId }) =>
+      accountId === DEFAULT_ACCOUNT_ID &&
+      Boolean(process.env.NOSTR_PRIVATE_KEY?.trim()) &&
+      !hasConfiguredSecretInput(resolveNostrAccount({ cfg, accountId }).config.privateKey),
+    apply: async ({ cfg, accountId }) =>
+      patchTopLevelChannelConfigSection({
+        cfg,
+        channel,
+        enabled: true,
+        clearFields: ["privateKey"],
+        patch: buildNostrSetupPatch(accountId, {}),
+      }),
+  },
+  credentials: [
+    {
+      inputKey: "privateKey",
+      providerHint: channel,
+      credentialLabel: "private key",
+      preferredEnvVar: "NOSTR_PRIVATE_KEY",
+      helpTitle: "Nostr private key",
+      helpLines: NOSTR_SETUP_HELP_LINES,
+      envPrompt: "NOSTR_PRIVATE_KEY detected. Use env var?",
+      keepPrompt: "Nostr private key already configured. Keep it?",
+      inputPrompt: "Nostr private key (nsec... or hex)",
+      allowEnv: ({ accountId }) => accountId === DEFAULT_ACCOUNT_ID,
+      inspect: ({ cfg, accountId }) => {
+        const account = resolveNostrAccount({ cfg, accountId });
+        return {
+          accountConfigured: account.configured,
+          hasConfiguredValue: hasConfiguredSecretInput(account.config.privateKey),
+          resolvedValue: normalizeSecretInputString(account.config.privateKey),
+          envValue: process.env.NOSTR_PRIVATE_KEY?.trim(),
+        };
+      },
+      applyUseEnv: async ({ cfg, accountId }) =>
+        patchTopLevelChannelConfigSection({
+          cfg,
+          channel,
+          enabled: true,
+          clearFields: ["privateKey"],
+          patch: buildNostrSetupPatch(accountId, {}),
+        }),
+      applySet: async ({ cfg, accountId, resolvedValue }) =>
+        patchTopLevelChannelConfigSection({
+          cfg,
+          channel,
+          enabled: true,
+          patch: buildNostrSetupPatch(accountId, { privateKey: resolvedValue }),
+        }),
+    },
+  ],
+  textInputs: [
+    {
+      inputKey: "relayUrls",
+      message: "Relay URLs (comma-separated, optional)",
+      placeholder: DEFAULT_RELAYS.join(", "),
+      required: false,
+      applyEmptyValue: true,
+      helpTitle: "Nostr relays",
+      helpLines: ["Use ws:// or wss:// relay URLs.", "Leave blank to keep the default relay set."],
+      currentValue: ({ cfg, accountId }) => {
+        const account = resolveNostrAccount({ cfg, accountId });
+        const configuredRelays = cfg.channels?.nostr?.relays as string[] | undefined;
+        const relays = configuredRelays && configuredRelays.length > 0 ? account.relays : [];
+        return relays.join(", ");
+      },
+      keepPrompt: (value) => `Relay URLs set (${value}). Keep them?`,
+      validate: ({ value }) => parseRelayUrls(value).error,
+      applySet: async ({ cfg, accountId, value }) => {
+        const relayResult = parseRelayUrls(value);
+        return patchTopLevelChannelConfigSection({
+          cfg,
+          channel,
+          enabled: true,
+          clearFields: relayResult.relays.length > 0 ? undefined : ["relays"],
+          patch: buildNostrSetupPatch(
+            accountId,
+            relayResult.relays.length > 0 ? { relays: relayResult.relays } : {},
+          ),
+        });
+      },
+    },
+  ],
+  dmPolicy: nostrDmPolicy,
+  disable: (cfg) =>
+    patchTopLevelChannelConfigSection({
+      cfg,
+      channel,
+      patch: { enabled: false },
+    }),
+};

package/src/test-fixtures.ts

@@ -0,0 +1,45 @@
+import type { ResolvedNostrAccount } from "./types.js";
+
+export const TEST_HEX_PRIVATE_KEY =
+  "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+
+export const TEST_HEX_PUBLIC_KEY =
+  "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789";
+
+export const TEST_NSEC = "nsec1qypqxpq9qtpqscx7peytzfwtdjmcv0mrz5rjpej8vjppfkqfqy8skqfv3l";
+
+export const TEST_RELAY_URL = "wss://relay.example.com";
+export const TEST_SETUP_RELAY_URLS = ["wss://relay.damus.io", "wss://relay.primal.net"];
+export const TEST_RESOLVED_PRIVATE_KEY = "resolved-nostr-private-key";
+
+export const TEST_HEX_PRIVATE_KEY_BYTES = new Uint8Array(
+  TEST_HEX_PRIVATE_KEY.match(/.{2}/g)!.map((byte) => Number.parseInt(byte, 16)),
+);
+
+export function createConfiguredNostrCfg(overrides: Record<string, unknown> = {}): {
+  channels: { nostr: Record<string, unknown> };
+} {
+  return {
+    channels: {
+      nostr: {
+        privateKey: TEST_HEX_PRIVATE_KEY,
+        ...overrides,
+      },
+    },
+  };
+}
+
+export function buildResolvedNostrAccount(
+  overrides: Partial<ResolvedNostrAccount> = {},
+): ResolvedNostrAccount {
+  return {
+    accountId: "default",
+    enabled: true,
+    configured: true,
+    privateKey: TEST_HEX_PRIVATE_KEY,
+    publicKey: TEST_HEX_PUBLIC_KEY,
+    relays: [TEST_RELAY_URL],
+    config: {},
+    ...overrides,
+  };
+}