@openclaw/nostr 2026.3.13 → 2026.5.2-beta.1

package/README.md

@@ -68,6 +68,10 @@ openclaw plugins install @openclaw/nostr
 - **open**: Anyone can message the bot (use with caution)
 - **disabled**: DMs are disabled
 
+Inbound event signatures are verified before policy enforcement and NIP-04 decryption.
+Unknown senders in `pairing` mode can receive a pairing reply, but their original DM body is not
+processed unless approved.
+
 ### Example: Allowlist Mode
 
 ```json
@@ -113,6 +117,8 @@ docker run -p 7777:7777 ghcr.io/hoytech/strfry
 
 - Private keys are never logged
 - Event signatures are verified before processing
+- Sender policy is checked before expensive crypto work
+- Inbound DMs are rate-limited and oversized payloads are dropped before decrypt
 - Use environment variables for keys, never commit to config files
 - Consider using `allowlist` mode in production
 

package/api.ts

@@ -0,0 +1,10 @@
+export {
+  getPluginRuntimeGatewayRequestScope,
+  type OpenClawConfig,
+  type PluginRuntime,
+} from "./runtime-api.js";
+export { nostrPlugin } from "./src/channel.js";
+export { createNostrProfileHttpHandler } from "./src/nostr-profile-http.js";
+export { getNostrRuntime, setNostrRuntime } from "./src/runtime.js";
+export { resolveNostrAccount } from "./src/types.js";
+export type { ResolvedNostrAccount } from "./src/types.js";

package/channel-plugin-api.ts

@@ -0,0 +1 @@
+export { nostrPlugin } from "./src/channel.js";

package/index.ts

@@ -1,54 +1,79 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/nostr";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/nostr";
-import { nostrPlugin } from "./src/channel.js";
-import type { NostrProfile } from "./src/config-schema.js";
-import { createNostrProfileHttpHandler } from "./src/nostr-profile-http.js";
-import { setNostrRuntime, getNostrRuntime } from "./src/runtime.js";
-import { resolveNostrAccount } from "./src/types.js";
+import {
+  defineBundledChannelEntry,
+  loadBundledEntryExportSync,
+} from "openclaw/plugin-sdk/channel-entry-contract";
+import type { OpenClawConfig, PluginRuntime, ResolvedNostrAccount } from "./api.js";
 
-const plugin = {
+function createNostrProfileHttpHandler() {
+  return loadBundledEntryExportSync<
+    (params: Record<string, unknown>) => (ctx: unknown) => Promise<void> | void
+  >(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "createNostrProfileHttpHandler",
+  });
+}
+
+function getNostrRuntime() {
+  return loadBundledEntryExportSync<() => PluginRuntime>(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "getNostrRuntime",
+  })();
+}
+
+function resolveNostrAccount(params: { cfg: unknown; accountId: string }) {
+  return loadBundledEntryExportSync<
+    (params: { cfg: unknown; accountId: string }) => ResolvedNostrAccount
+  >(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "resolveNostrAccount",
+  })(params);
+}
+
+export default defineBundledChannelEntry({
   id: "nostr",
   name: "Nostr",
   description: "Nostr DM channel plugin via NIP-04",
-  configSchema: emptyPluginConfigSchema(),
-  register(api: OpenClawPluginApi) {
-    setNostrRuntime(api.runtime);
-    api.registerChannel({ plugin: nostrPlugin });
-
-    // Register HTTP handler for profile management
-    const httpHandler = createNostrProfileHttpHandler({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "nostrPlugin",
+  },
+  runtime: {
+    specifier: "./api.js",
+    exportName: "setNostrRuntime",
+  },
+  registerFull(api) {
+    const httpHandler = createNostrProfileHttpHandler()({
       getConfigProfile: (accountId: string) => {
         const runtime = getNostrRuntime();
-        const cfg = runtime.config.loadConfig();
+        const cfg = runtime.config.current() as OpenClawConfig;
         const account = resolveNostrAccount({ cfg, accountId });
         return account.profile;
       },
-      updateConfigProfile: async (accountId: string, profile: NostrProfile) => {
+      updateConfigProfile: async (accountId: string, profile: unknown) => {
         const runtime = getNostrRuntime();
-        const cfg = runtime.config.loadConfig();
+        const cfg = runtime.config.current() as OpenClawConfig;
 
-        // Build the config patch for channels.nostr.profile
         const channels = (cfg.channels ?? {}) as Record<string, unknown>;
         const nostrConfig = (channels.nostr ?? {}) as Record<string, unknown>;
 
-        const updatedNostrConfig = {
-          ...nostrConfig,
-          profile,
-        };
-
-        const updatedChannels = {
-          ...channels,
-          nostr: updatedNostrConfig,
-        };
-
-        await runtime.config.writeConfigFile({
-          ...cfg,
-          channels: updatedChannels,
+        await runtime.config.replaceConfigFile({
+          nextConfig: {
+            ...cfg,
+            channels: {
+              ...channels,
+              nostr: {
+                ...nostrConfig,
+                profile,
+              },
+            },
+          },
+          afterWrite: { mode: "auto" },
         });
       },
       getAccountInfo: (accountId: string) => {
         const runtime = getNostrRuntime();
-        const cfg = runtime.config.loadConfig();
+        const cfg = runtime.config.current() as OpenClawConfig;
         const account = resolveNostrAccount({ cfg, accountId });
         if (!account.configured || !account.publicKey) {
           return null;
@@ -65,9 +90,8 @@ const plugin = {
       path: "/api/channels/nostr",
       auth: "gateway",
       match: "prefix",
+      gatewayRuntimeScopeSurface: "trusted-operator",
       handler: httpHandler,
     });
   },
-};
-
-export default plugin;
+});

package/openclaw.plugin.json

@@ -1,9 +1,198 @@
 {
   "id": "nostr",
-  "channels": ["nostr"],
+  "activation": {
+    "onStartup": false
+  },
+  "channels": [
+    "nostr"
+  ],
+  "channelEnvVars": {
+    "nostr": [
+      "NOSTR_PRIVATE_KEY"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {}
+  },
+  "channelConfigs": {
+    "nostr": {
+      "schema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "defaultAccount": {
+            "type": "string"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "markdown": {
+            "type": "object",
+            "properties": {
+              "tables": {
+                "type": "string",
+                "enum": [
+                  "off",
+                  "bullets",
+                  "code",
+                  "block"
+                ]
+              }
+            },
+            "additionalProperties": false
+          },
+          "privateKey": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "source": {
+                        "type": "string",
+                        "const": "env"
+                      },
+                      "provider": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+                      },
+                      "id": {
+                        "type": "string",
+                        "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
+                      }
+                    },
+                    "required": [
+                      "source",
+                      "provider",
+                      "id"
+                    ],
+                    "additionalProperties": false
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "source": {
+                        "type": "string",
+                        "const": "file"
+                      },
+                      "provider": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+                      },
+                      "id": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "source",
+                      "provider",
+                      "id"
+                    ],
+                    "additionalProperties": false
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "source": {
+                        "type": "string",
+                        "const": "exec"
+                      },
+                      "provider": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+                      },
+                      "id": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "source",
+                      "provider",
+                      "id"
+                    ],
+                    "additionalProperties": false
+                  }
+                ]
+              }
+            ]
+          },
+          "relays": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "dmPolicy": {
+            "type": "string",
+            "enum": [
+              "pairing",
+              "allowlist",
+              "open",
+              "disabled"
+            ]
+          },
+          "allowFrom": {
+            "type": "array",
+            "items": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            }
+          },
+          "profile": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "maxLength": 256
+              },
+              "displayName": {
+                "type": "string",
+                "maxLength": 256
+              },
+              "about": {
+                "type": "string",
+                "maxLength": 2000
+              },
+              "picture": {
+                "type": "string",
+                "format": "uri"
+              },
+              "banner": {
+                "type": "string",
+                "format": "uri"
+              },
+              "website": {
+                "type": "string",
+                "format": "uri"
+              },
+              "nip05": {
+                "type": "string"
+              },
+              "lud16": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      },
+      "label": "Nostr",
+      "description": "Decentralized protocol; encrypted DMs via NIP-04."
+    }
   }
 }

package/package.json

@@ -1,16 +1,33 @@
 {
   "name": "@openclaw/nostr",
-  "version": "2026.3.13",
+  "version": "2026.5.2-beta.1",
   "description": "OpenClaw Nostr channel plugin for NIP-04 encrypted DMs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
   "type": "module",
   "dependencies": {
     "nostr-tools": "^2.23.3",
-    "zod": "^4.3.6"
+    "zod": "^4.4.1"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*",
+    "openclaw": "workspace:*"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.5.2-beta.1"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
   },
   "openclaw": {
     "extensions": [
       "./index.ts"
     ],
+    "setupEntry": "./setup-entry.ts",
     "channel": {
       "id": "nostr",
       "label": "Nostr",
@@ -19,17 +36,32 @@
       "docsLabel": "nostr",
       "blurb": "Decentralized protocol; encrypted DMs via NIP-04.",
       "order": 55,
-      "quickstartAllowFrom": true
+      "quickstartAllowFrom": true,
+      "cliAddOptions": [
+        {
+          "flags": "--private-key <key>",
+          "description": "Nostr private key (nsec... or hex)"
+        },
+        {
+          "flags": "--relay-urls <list>",
+          "description": "Nostr relay URLs (comma-separated)"
+        }
+      ]
     },
     "install": {
       "npmSpec": "@openclaw/nostr",
-      "localPath": "extensions/nostr",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
     },
-    "releaseChecks": {
-      "rootDependencyMirrorAllowlist": [
-        "nostr-tools"
-      ]
+    "compat": {
+      "pluginApi": ">=2026.5.2-beta.1"
+    },
+    "build": {
+      "openclawVersion": "2026.5.2-beta.1"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
     }
   }
 }

package/runtime-api.ts

@@ -0,0 +1,6 @@
+// Private runtime barrel for the bundled Nostr extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+export { getPluginRuntimeGatewayRequestScope } from "openclaw/plugin-sdk/plugin-runtime";
+export type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

package/setup-api.ts

@@ -0,0 +1 @@
+export { nostrSetupAdapter, nostrSetupWizard } from "./src/setup-surface.js";

package/setup-entry.ts

@@ -0,0 +1,9 @@
+import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "nostrSetupPlugin",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled setup entry imports narrow so setup loads do not pull the
+// broader Nostr runtime plugin surface.
+export { nostrSetupPlugin } from "./src/channel.setup.js";

package/src/channel-api.ts

@@ -0,0 +1,15 @@
+export {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  formatPairingApproveHint,
+  type ChannelPlugin,
+} from "openclaw/plugin-sdk/channel-plugin-common";
+export type { ChannelOutboundAdapter } from "openclaw/plugin-sdk/channel-contract";
+export {
+  collectStatusIssuesFromLastError,
+  createDefaultChannelRuntimeState,
+} from "openclaw/plugin-sdk/status-helpers";
+export {
+  createPreCryptoDirectDmAuthorizer,
+  resolveInboundDirectDmAccessWithRuntime,
+} from "openclaw/plugin-sdk/direct-dm-access";

package/src/channel.inbound.test.ts

@@ -0,0 +1,176 @@
+import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-helpers";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { PluginRuntime } from "../runtime-api.js";
+import { startNostrGatewayAccount } from "./gateway.js";
+import { setNostrRuntime } from "./runtime.js";
+import { buildResolvedNostrAccount } from "./test-fixtures.js";
+
+const mocks = vi.hoisted(() => ({
+  normalizePubkey: vi.fn((value: string) =>
+    value
+      .trim()
+      .replace(/^nostr:/i, "")
+      .toLowerCase(),
+  ),
+  startNostrBus: vi.fn(),
+}));
+
+vi.mock("./nostr-bus.js", () => ({
+  DEFAULT_RELAYS: ["wss://relay.example.com"],
+  startNostrBus: mocks.startNostrBus,
+}));
+
+vi.mock("./nostr-key-utils.js", () => ({
+  getPublicKeyFromPrivate: vi.fn(() => "bot-pubkey"),
+  normalizePubkey: mocks.normalizePubkey,
+}));
+
+function createMockBus() {
+  return {
+    sendDm: vi.fn(async () => {}),
+    close: vi.fn(),
+    getMetrics: vi.fn(() => ({ counters: {} })),
+    publishProfile: vi.fn(),
+    getProfileState: vi.fn(async () => null),
+  };
+}
+
+function createRuntimeHarness() {
+  const recordInboundSession = vi.fn(async () => {});
+  const dispatchReplyWithBufferedBlockDispatcher = vi.fn(async ({ dispatcherOptions }) => {
+    await dispatcherOptions.deliver({ text: "|a|b|" });
+  });
+  const runtime = {
+    channel: {
+      text: {
+        resolveMarkdownTableMode: vi.fn(() => "off"),
+        convertMarkdownTables: vi.fn((text: string) => `converted:${text}`),
+      },
+      commands: {
+        shouldComputeCommandAuthorized: vi.fn(() => true),
+        resolveCommandAuthorizedFromAuthorizers: vi.fn(() => true),
+      },
+      routing: {
+        resolveAgentRoute: vi.fn(({ accountId, peer }) => ({
+          agentId: "agent-nostr",
+          accountId,
+          sessionKey: `nostr:${peer.id}`,
+        })),
+      },
+      session: {
+        resolveStorePath: vi.fn(() => "/tmp/nostr-session-store"),
+        readSessionUpdatedAt: vi.fn(() => undefined),
+        recordInboundSession,
+      },
+      reply: {
+        formatAgentEnvelope: vi.fn(({ body }) => `envelope:${body}`),
+        resolveEnvelopeFormatOptions: vi.fn(() => ({ mode: "agent" })),
+        finalizeInboundContext: vi.fn((ctx) => ctx),
+        dispatchReplyWithBufferedBlockDispatcher,
+      },
+      pairing: {
+        readAllowFromStore: vi.fn(async () => []),
+        upsertPairingRequest: vi.fn(async () => ({ code: "PAIR1234", created: true })),
+      },
+    },
+  } as unknown as PluginRuntime;
+
+  return {
+    runtime,
+    recordInboundSession,
+    dispatchReplyWithBufferedBlockDispatcher,
+  };
+}
+
+async function startGatewayHarness(params: {
+  account: ReturnType<typeof buildResolvedNostrAccount>;
+  cfg?: Parameters<typeof createStartAccountContext>[0]["cfg"];
+}) {
+  const harness = createRuntimeHarness();
+  const bus = createMockBus();
+  setNostrRuntime(harness.runtime);
+  mocks.startNostrBus.mockResolvedValueOnce(bus as never);
+
+  const cleanup = (await startNostrGatewayAccount(
+    createStartAccountContext({
+      account: params.account,
+      cfg: params.cfg,
+    }),
+  )) as { stop: () => void };
+
+  return { harness, bus, cleanup };
+}
+
+describe("nostr inbound gateway path", () => {
+  afterEach(() => {
+    mocks.normalizePubkey.mockClear();
+    mocks.startNostrBus.mockReset();
+  });
+
+  it("issues a pairing reply before decrypt for unknown senders", async () => {
+    const { cleanup } = await startGatewayHarness({
+      account: buildResolvedNostrAccount({
+        config: { dmPolicy: "pairing", allowFrom: [] },
+      }),
+    });
+
+    const options = mocks.startNostrBus.mock.calls[0]?.[0] as {
+      authorizeSender: (params: {
+        senderPubkey: string;
+        reply: (text: string) => Promise<void>;
+      }) => Promise<string>;
+    };
+    const sendPairingReply = vi.fn(async (_text: string) => {});
+
+    await expect(
+      options.authorizeSender({
+        senderPubkey: "nostr:UNKNOWN-SENDER",
+        reply: sendPairingReply,
+      }),
+    ).resolves.toBe("pairing");
+    expect(sendPairingReply).toHaveBeenCalledTimes(1);
+    expect(sendPairingReply.mock.calls[0]?.[0]).toContain("Pairing code:");
+
+    cleanup.stop();
+  });
+
+  it("routes allowed DMs through the standard reply pipeline", async () => {
+    const { harness, cleanup } = await startGatewayHarness({
+      account: buildResolvedNostrAccount({
+        publicKey: "bot-pubkey",
+        config: { dmPolicy: "allowlist", allowFrom: ["nostr:sender-pubkey"] },
+      }),
+      cfg: {
+        session: { store: { type: "jsonl" } },
+        commands: { useAccessGroups: true },
+      } as never,
+    });
+
+    const options = mocks.startNostrBus.mock.calls[0]?.[0] as {
+      onMessage: (
+        senderPubkey: string,
+        text: string,
+        reply: (text: string) => Promise<void>,
+        meta: { eventId: string; createdAt: number },
+      ) => Promise<void>;
+    };
+    const sendReply = vi.fn(async (_text: string) => {});
+
+    await options.onMessage("sender-pubkey", "hello from nostr", sendReply, {
+      eventId: "event-123",
+      createdAt: 1_710_000_000,
+    });
+
+    expect(harness.recordInboundSession).toHaveBeenCalledTimes(1);
+    expect(harness.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(1);
+    expect(harness.dispatchReplyWithBufferedBlockDispatcher.mock.calls[0]?.[0]?.ctx).toMatchObject({
+      BodyForAgent: "hello from nostr",
+      SenderId: "sender-pubkey",
+      MessageSid: "event-123",
+      CommandAuthorized: true,
+    });
+    expect(sendReply).toHaveBeenCalledWith("converted:|a|b|");
+
+    cleanup.stop();
+  });
+});