openclaw-nostr 2026.7.30

package/node_modules/cascadia-ts/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "cascadia-ts",
+  "version": "0.1.0",
+  "description": "Generated Cascadia event kind constants and ContextVM contracts",
+  "type": "module",
+  "main": "./dist/cascadia.js",
+  "types": "./dist/cascadia.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/cascadia.d.ts",
+      "import": "./dist/cascadia.js"
+    }
+  },
+  "files": ["dist", "cascadia.ts"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}

package/openclaw.plugin.json

@@ -0,0 +1,153 @@
+{
+  "id": "nostr",
+  "channels": ["nostr"],
+  "channelConfigs": {
+    "nostr": {
+      "schema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": { "type": "string", "description": "Account display name" },
+          "defaultAccount": { "type": "string", "description": "Default account id for routing" },
+          "enabled": { "type": "boolean", "description": "Whether the Nostr channel is enabled" },
+          "privateKey": { "type": "string", "description": "Private key in hex or nsec bech32 format" },
+          "relays": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "WebSocket relay URLs to connect to"
+          },
+          "dmRelays": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "DM relay URLs for NIP-17 (defaults to relays if unset)"
+          },
+          "nip17Enabled": { "type": "boolean", "description": "Enable NIP-17 gift-wrapped DMs (default: true)" },
+          "nip04Enabled": { "type": "boolean", "description": "Enable NIP-04 legacy DMs (default: true)" },
+          "inboundDispatchTimeoutSeconds": {
+            "type": "number",
+            "description": "Maximum seconds an inbound DM or NIP-29 message may occupy the delivery queue while waiting for agent dispatch (default: 300; <=0 disables)"
+          },
+          "dmPolicy": {
+            "type": "string",
+            "enum": ["pairing", "allowlist", "open", "disabled"],
+            "description": "DM access policy"
+          },
+          "allowFrom": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Allowed sender pubkeys (npub or hex format)"
+          },
+          "nostr_channels": {
+            "type": "object",
+            "description": "NIP-29 group and NIP-C7 chat channel subscriptions"
+          },
+          "nostrChannels": {
+            "type": "object",
+            "description": "Alias for nostr_channels"
+          },
+          "nip51": {
+            "type": "object",
+            "description": "Account-scoped NIP-51 fleet, mute-list, and relay-set synchronization",
+            "properties": {
+              "enabled": { "type": "boolean", "description": "Enable NIP-51 fleet synchronization (default: false)" },
+              "relays": { "type": "array", "items": { "type": "string" } },
+              "initialSyncTimeoutMs": { "type": "number", "minimum": 0 },
+              "capabilitySync": { "type": "boolean" },
+              "tiers": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "required": ["dTag"],
+                  "properties": {
+                    "dTag": { "type": "string", "minLength": 1 },
+                    "members": {
+                      "type": "array",
+                      "items": {
+                        "oneOf": [
+                          { "type": "string" },
+                          {
+                            "type": "object",
+                            "required": ["pubkey"],
+                            "properties": {
+                              "pubkey": { "type": "string" },
+                              "relay": { "type": "string" },
+                              "petname": { "type": "string" }
+                            }
+                          }
+                        ]
+                      }
+                    }
+                  }
+                }
+              },
+              "relaySets": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "properties": {
+                    "dTag": { "type": "string", "minLength": 1 },
+                    "relays": { "type": "array", "items": { "type": "string" } }
+                  }
+                }
+              }
+            }
+          },
+          "profile": {
+            "type": "object",
+            "description": "Profile metadata (NIP-01 kind:0 content)",
+            "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
+          }
+        }
+      },
+      "uiHints": {
+        "privateKey": {
+          "label": "Private Key",
+          "placeholder": "nsec1... or 64-char hex",
+          "sensitive": true
+        },
+        "relays": {
+          "label": "Relay URLs",
+          "placeholder": "wss://relay.example.com"
+        },
+        "dmRelays": {
+          "label": "DM Relay URLs",
+          "placeholder": "wss://relay.example.com (defaults to relays)"
+        },
+        "dmPolicy": {
+          "label": "DM Policy"
+        },
+        "allowFrom": {
+          "label": "Allowed Senders",
+          "placeholder": "npub1... or hex pubkey"
+        },
+        "nip51": {
+          "label": "NIP-51 Fleet Lists"
+        }
+      },
+      "label": "Nostr",
+      "description": "Decentralized DMs via Nostr relays (NIP-04 + NIP-17)"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "nostr_channels": {
+        "type": "object"
+      },
+      "nostrChannels": {
+        "type": "object"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "openclaw-nostr",
+  "version": "2026.7.30",
+  "description": "Nostr channel plugin for OpenClaw",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "api.ts",
+    "runtime-api.ts",
+    "setup-api.ts",
+    "setup-entry.ts",
+    "src",
+    "openclaw.plugin.json",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit --noCheck --module NodeNext --moduleResolution NodeNext --target ES2023 index.ts api.ts runtime-api.ts setup-api.ts setup-entry.ts src/*.ts test/setup.ts vitest.config.ts",
+    "test:bootstrap": "node --test test/nostr-claw-bootstrap.test.mjs",
+    "test:scanner": "vitest run test/runtime-security-scanner.test.ts"
+  },
+  "dependencies": {
+    "cascadia-ts": "file:../cascadia-nips/generated/typescript",
+    "nostr-tools": "2.23.3",
+    "ws": "^8.18.0"
+  },
+  "bundledDependencies": [
+    "cascadia-ts"
+  ],
+  "devDependencies": {
+    "openclaw": ">=2026.4.15",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.5"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.4.15"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "runtimeExtensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "runtimeSetupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "nostr",
+      "label": "Nostr",
+      "selectionLabel": "Nostr (NIP-04 + NIP-17 DMs)",
+      "docsPath": "/channels/nostr",
+      "docsLabel": "nostr",
+      "blurb": "Decentralized protocol; encrypted DMs via NIP-04 and NIP-17.",
+      "order": 55,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "openclaw-nostr",
+      "localPath": "extensions/nostr",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.15"
+    },
+    "compat": {
+      "pluginApi": ">=2026.4.15"
+    },
+    "build": {
+      "openclawVersion": "2026.4.15"
+    },
+    "bundle": {
+      "stageRuntimeDependencies": true
+    },
+    "release": {
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,12 @@
+// Private runtime barrel for the bundled Nostr extension.
+// Re-exports SDK symbols used by the extension's internal surface and tests.
+
+export type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
+export type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
+export type { OpenClawPluginApi } from "openclaw/plugin-sdk/channel-core";
+export type { ChannelPlugin } from "openclaw/plugin-sdk/channel-plugin-common";
+export type { ChannelSetupAdapter } from "openclaw/plugin-sdk/channel-setup";
+export { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+export { buildChannelConfigSchema, formatPairingApproveHint } from "openclaw/plugin-sdk/channel-plugin-common";
+export { collectStatusIssuesFromLastError, createDefaultChannelRuntimeState } from "openclaw/plugin-sdk/status-helpers";
+export { mapAllowFromEntries } from "openclaw/plugin-sdk/channel-config-helpers";

package/setup-api.ts

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

package/setup-entry.ts

@@ -0,0 +1,4 @@
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { nostrPlugin } from "./src/channel.js";
+
+export default defineSetupPluginEntry(nostrPlugin);

package/src/channel-actions.test.ts

@@ -0,0 +1,304 @@
+import { describe, expect, it, vi } from "vitest";
+import { createNostrMessageActions, type NostrSendActionDeps } from "./channel-actions.js";
+
+type ActionResult = { content: Array<{ type: string; text: string }>; details: Record<string, unknown> };
+
+function extractPayload(result: unknown): Record<string, unknown> {
+  return (result as ActionResult).details;
+}
+
+function createMockBus() {
+  return {
+    sendDm: vi.fn(async () => ({
+      protocol: "nip17" as const,
+      eventId: "rumor-id",
+      publishedEventIds: ["wrap-id-self", "wrap-id-recipient"],
+      relayResults: { successes: ["wss://relay.example.com"], failures: [] },
+    })),
+    sendGroupMessage: vi.fn(async () => ({
+      eventId: "group-event-id",
+      relay: "wss://groups.example.com",
+      groupId: "test-room",
+    })),
+    sendGroupReaction: vi.fn(),
+    deleteGroupEvent: vi.fn(),
+    close: vi.fn(),
+  };
+}
+
+function createSendDeps(
+  bus: ReturnType<typeof createMockBus>,
+  roomChannels?: Record<string, { kind?: string; enabled?: boolean }>,
+): NostrSendActionDeps {
+  return {
+    resolveBus: () => bus as never,
+    loadConfig: () => ({
+      channels: {
+        nostr: {
+          nostr_channels: roomChannels ?? {},
+        },
+      },
+    }),
+    resolveMarkdownTableMode: () => "off",
+    convertMarkdownTables: (text: string) => text,
+    normalizePubkey: (value: string) => {
+      const cleaned = value.replace(/^nostr:/i, "").trim();
+      return cleaned.toLowerCase();
+    },
+    extractMentionPubkeys: () => [],
+  };
+}
+
+describe("nostr send message action", () => {
+  it("sends a DM when target is a pubkey", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    const result = await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: {
+        target: "aaaa".repeat(16),
+        text: "hello from action",
+      },
+    } as never);
+
+    expect(bus.sendDm).toHaveBeenCalledWith("aaaa".repeat(16), "hello from action");
+    expect(bus.sendGroupMessage).not.toHaveBeenCalled();
+    const payload = extractPayload(result);
+    expect(payload.ok).toBe(true);
+    expect(payload.action).toBe("send");
+    expect(payload.to).toBe("aaaa".repeat(16));
+    expect(payload.messageId).toBe("wrap-id-self");
+  });
+
+  it("uses relay-visible wrap ID for NIP-17 DM sends", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    const result = await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: { target: "bbbb".repeat(16), text: "nip17 dm" },
+    } as never);
+
+    const payload = extractPayload(result);
+    // Must use relay-visible wrap ID, not the inner rumor ID
+    expect(payload.messageId).toBe("wrap-id-self");
+    expect(payload.messageId).not.toBe("rumor-id");
+  });
+
+  it("sends a group message when target is a configured NIP-29 room", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus, {
+      "fleet-ops": { kind: "nip29", enabled: true },
+    });
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    const result = await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: {
+        target: "fleet-ops",
+        text: "hello room",
+      },
+    } as never);
+
+    expect(bus.sendGroupMessage).toHaveBeenCalledWith("fleet-ops", "hello room", {
+      mentionPubkeys: [],
+    });
+    expect(bus.sendDm).not.toHaveBeenCalled();
+    const payload = extractPayload(result);
+    expect(payload.ok).toBe(true);
+    expect(payload.to).toBe("fleet-ops");
+    expect(payload.messageId).toBe("group-event-id");
+    expect(payload.groupId).toBe("test-room");
+  });
+
+  it("forwards replyToId to NIP-29 group sends", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus, {
+      "fleet-ops": { kind: "nip29", enabled: true },
+    });
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: {
+        target: "fleet-ops",
+        text: "reply in room",
+        replyToId: "parent-event-id",
+      },
+    } as never);
+
+    expect(bus.sendGroupMessage).toHaveBeenCalledWith("fleet-ops", "reply in room", {
+      mentionPubkeys: [],
+      replyToEventId: "parent-event-id",
+    });
+  });
+
+  it("forwards threadId to NIP-29 group sends", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus, {
+      "fleet-ops": { kind: "nip29", enabled: true },
+    });
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: {
+        target: "fleet-ops",
+        text: "threaded reply",
+        threadId: "thread-root-id",
+      },
+    } as never);
+
+    expect(bus.sendGroupMessage).toHaveBeenCalledWith("fleet-ops", "threaded reply", {
+      mentionPubkeys: [],
+      threadEventId: "thread-root-id",
+    });
+  });
+
+  it("strips nostr: prefix from target", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: { target: "nostr:" + "cccc".repeat(16), text: "prefixed" },
+    } as never);
+
+    expect(bus.sendDm).toHaveBeenCalledWith("cccc".repeat(16), "prefixed");
+  });
+
+  it("reads 'to' param as fallback for target", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: { to: "dddd".repeat(16), text: "via to param" },
+    } as never);
+
+    expect(bus.sendDm).toHaveBeenCalledWith("dddd".repeat(16), "via to param");
+  });
+
+  it("reads 'message' param as fallback for text", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: { target: "eeee".repeat(16), message: "via message param" },
+    } as never);
+
+    expect(bus.sendDm).toHaveBeenCalledWith("eeee".repeat(16), "via message param");
+  });
+
+  it("throws when no target is provided", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    await expect(
+      actions.handleAction!({
+        action: "send",
+        channel: "nostr",
+        params: { text: "no target" },
+      } as never),
+    ).rejects.toThrow("target or to parameter required");
+  });
+
+  it("throws when sendDeps are not provided", async () => {
+    const bus = createMockBus();
+    const actions = createNostrMessageActions(() => bus as never);
+
+    await expect(
+      actions.handleAction!({
+        action: "send",
+        channel: "nostr",
+        params: { target: "aaaa".repeat(16), text: "no deps" },
+      } as never),
+    ).rejects.toThrow("Nostr send action requires runtime dependencies");
+  });
+
+  it("applies markdown table conversion", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    deps.convertMarkdownTables = (text: string) => `converted:${text}`;
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: { target: "aaaa".repeat(16), text: "|a|b|" },
+    } as never);
+
+    expect(bus.sendDm).toHaveBeenCalledWith("aaaa".repeat(16), "converted:|a|b|");
+  });
+
+  it("extracts mention pubkeys for NIP-29 group sends", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus, {
+      "fleet-ops": { kind: "nip29", enabled: true },
+    });
+    deps.extractMentionPubkeys = () => ["mentioned-pubkey"];
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: { target: "fleet-ops", text: "hello @someone" },
+    } as never);
+
+    expect(bus.sendGroupMessage).toHaveBeenCalledWith("fleet-ops", "hello @someone", {
+      mentionPubkeys: ["mentioned-pubkey"],
+    });
+  });
+
+  it("sends empty text when no text param provided", async () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    await actions.handleAction!({
+      action: "send",
+      channel: "nostr",
+      params: { target: "aaaa".repeat(16) },
+    } as never);
+
+    expect(bus.sendDm).toHaveBeenCalledWith("aaaa".repeat(16), "");
+  });
+});
+
+describe("nostr message action discovery", () => {
+  it("advertises send, react, and delete actions", () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    const discovery = actions.describeMessageTool!({} as never);
+    expect(discovery?.actions).toEqual(["send", "react", "delete"]);
+  });
+
+  it("supportsAction returns true for send", () => {
+    const bus = createMockBus();
+    const deps = createSendDeps(bus);
+    const actions = createNostrMessageActions(() => bus as never, deps);
+
+    expect(actions.supportsAction!({ action: "send" })).toBe(true);
+    expect(actions.supportsAction!({ action: "react" })).toBe(true);
+    expect(actions.supportsAction!({ action: "delete" })).toBe(true);
+    expect(actions.supportsAction!({ action: "edit" as never })).toBe(false);
+  });
+});