@actagent/nostr 2026.6.2

package/npm-shrinkwrap.json

@@ -0,0 +1,137 @@
+{
+  "name": "@actagent/nostr",
+  "version": "2026.6.2",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@actagent/nostr",
+      "version": "2026.6.2",
+      "dependencies": {
+        "nostr-tools": "2.23.5",
+        "zod": "4.4.3"
+      },
+      "peerDependencies": {
+        "actagent": ">=2026.6.2"
+      },
+      "peerDependenciesMeta": {
+        "actagent": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@noble/ciphers": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@noble/ciphers/-/ciphers-2.1.1.tgz",
+      "integrity": "sha512-bysYuiVfhxNJuldNXlFEitTVdNnYUc+XNJZd7Qm2a5j1vZHgY+fazadNFWFaMK/2vye0JVlxV3gHmC0WDfAOQw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@noble/curves": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@noble/curves/-/curves-2.0.1.tgz",
+      "integrity": "sha512-vs1Az2OOTBiP4q0pwjW5aF0xp9n4MxVrmkFBxc6EKZc6ddYx5gaZiAsZoq0uRRXWbi3AT/sBqn05eRPtn1JCPw==",
+      "license": "MIT",
+      "dependencies": {
+        "@noble/hashes": "2.0.1"
+      },
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@noble/hashes": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-2.0.1.tgz",
+      "integrity": "sha512-XlOlEbQcE9fmuXxrVTXCTlG2nlRXa9Rj3rr5Ue/+tX+nmkgbX720YHh0VR3hBF9xDvwnb8D2shVGOwNx+ulArw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@scure/base": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@scure/base/-/base-2.0.0.tgz",
+      "integrity": "sha512-3E1kpuZginKkek01ovG8krQ0Z44E3DHPjc5S2rjJw9lZn3KSQOs8S7wqikF/AH7iRanHypj85uGyxk0XAyC37w==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@scure/bip32": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@scure/bip32/-/bip32-2.0.1.tgz",
+      "integrity": "sha512-4Md1NI5BzoVP+bhyJaY3K6yMesEFzNS1sE/cP+9nuvE7p/b0kx9XbpDHHFl8dHtufcbdHRUUQdRqLIPHN/s7yA==",
+      "license": "MIT",
+      "dependencies": {
+        "@noble/curves": "2.0.1",
+        "@noble/hashes": "2.0.1",
+        "@scure/base": "2.0.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@scure/bip39": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@scure/bip39/-/bip39-2.0.1.tgz",
+      "integrity": "sha512-PsxdFj/d2AcJcZDX1FXN3dDgitDDTmwf78rKZq1a6c1P1Nan1X/Sxc7667zU3U+AN60g7SxxP0YCVw2H/hBycg==",
+      "license": "MIT",
+      "dependencies": {
+        "@noble/hashes": "2.0.1",
+        "@scure/base": "2.0.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/nostr-tools": {
+      "version": "2.23.5",
+      "resolved": "https://registry.npmjs.org/nostr-tools/-/nostr-tools-2.23.5.tgz",
+      "integrity": "sha512-Fa7ZlUdjfUW1P4E7H3yBexhOHYi18XNyvd2n7eNHkYR085xADX6Y8V8Vm7nT/XQajaFOBrptXmVIGkJ2E4vfVw==",
+      "license": "Unlicense",
+      "dependencies": {
+        "@noble/ciphers": "2.1.1",
+        "@noble/curves": "2.0.1",
+        "@noble/hashes": "2.0.1",
+        "@scure/base": "2.0.0",
+        "@scure/bip32": "2.0.1",
+        "@scure/bip39": "2.0.1",
+        "nostr-wasm": "0.1.0"
+      },
+      "peerDependencies": {
+        "typescript": ">=5.0.0"
+      },
+      "peerDependenciesMeta": {
+        "typescript": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/nostr-wasm": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/nostr-wasm/-/nostr-wasm-0.1.0.tgz",
+      "integrity": "sha512-78BTryCLcLYv96ONU8Ws3Q1JzjlAt+43pWQhIl86xZmWeegYCNLPml7yQ+gG3vR6V5h4XGj+TxO+SS5dsThQIA==",
+      "license": "MIT"
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@actagent/nostr",
+  "version": "2026.6.2",
+  "description": "ACTAgent Nostr channel plugin for NIP-04 encrypted direct messages.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/actagent/actagent"
+  },
+  "type": "module",
+  "dependencies": {
+    "nostr-tools": "2.23.5",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@actagent/plugin-sdk": "workspace:*",
+    "actagent": "workspace:*"
+  },
+  "peerDependencies": {
+    "actagent": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "actagent": {
+      "optional": true
+    }
+  },
+  "actagent": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "nostr",
+      "label": "Nostr",
+      "selectionLabel": "Nostr (NIP-04 DMs)",
+      "docsPath": "/channels/nostr",
+      "docsLabel": "nostr",
+      "blurb": "Decentralized protocol; encrypted DMs via NIP-04.",
+      "order": 55,
+      "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": "@actagent/nostr",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.6.2"
+    },
+    "build": {
+      "actagentVersion": "2026.6.2"
+    },
+    "release": {
+      "publishToACTAgentHub": 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 { ACTAgentConfig } from "actagent/plugin-sdk/config-contracts";
+export { getPluginRuntimeGatewayRequestScope } from "actagent/plugin-sdk/plugin-runtime";
+export type { PluginRuntime } from "actagent/plugin-sdk/runtime-store";

package/setup-api.ts

@@ -0,0 +1,2 @@
+// Nostr API module exposes the plugin public contract.
+export { nostrSetupAdapter, nostrSetupWizard } from "./src/setup-surface.js";

package/setup-entry.ts

@@ -0,0 +1,10 @@
+// Nostr plugin module implements setup entry behavior.
+import { defineBundledChannelSetupEntry } from "actagent/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,12 @@
+// Nostr API module exposes the plugin public contract.
+export {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  formatPairingApproveHint,
+  type ChannelPlugin,
+} from "actagent/plugin-sdk/channel-plugin-common";
+export type { ChannelOutboundAdapter } from "actagent/plugin-sdk/channel-contract";
+export {
+  collectStatusIssuesFromLastError,
+  createDefaultChannelRuntimeState,
+} from "actagent/plugin-sdk/status-helpers";

package/src/channel.inbound.test.ts

@@ -0,0 +1,203 @@
+// Nostr tests cover channel.inbound plugin behavior.
+import { createStartAccountContext } from "actagent/plugin-sdk/channel-test-helpers";
+import { afterEach, beforeAll, 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,
+}));
+
+beforeAll(async () => {
+  await import("./inbound-direct-dm-runtime.js");
+});
+
+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 abort = new AbortController();
+
+  const task = startNostrGatewayAccount(
+    createStartAccountContext({
+      account: params.account,
+      cfg: params.cfg,
+      abortSignal: abort.signal,
+    }),
+  );
+  await vi.waitFor(() => {
+    expect(mocks.startNostrBus).toHaveBeenCalledTimes(1);
+  });
+  const cleanup = {
+    stop: async () => {
+      abort.abort();
+      await task;
+    },
+  };
+
+  return { harness, bus, cleanup };
+}
+
+function mockCallArg(mock: ReturnType<typeof vi.fn>, callIndex = 0, argIndex = 0): unknown {
+  const call = mock.mock.calls[callIndex];
+  if (!call) {
+    throw new Error(`Expected mock call ${callIndex}`);
+  }
+  return call[argIndex];
+}
+
+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 = mockCallArg(mocks.startNostrBus) 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(mockCallArg(sendPairingReply)).toContain("Pairing code:");
+
+    await 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 = mockCallArg(mocks.startNostrBus) 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);
+    const ctx = (
+      mockCallArg(harness.dispatchReplyWithBufferedBlockDispatcher) as {
+        ctx?: Record<string, unknown>;
+      }
+    ).ctx;
+    expect(ctx?.BodyForAgent).toBe("hello from nostr");
+    expect(ctx?.SenderId).toBe("sender-pubkey");
+    expect(ctx?.MessageSid).toBe("event-123");
+    expect(ctx?.CommandAuthorized).toBe(true);
+    expect(sendReply).toHaveBeenCalledWith("converted:|a|b|");
+
+    await cleanup.stop();
+  });
+});

package/src/channel.lifecycle.test.ts

@@ -0,0 +1,97 @@
+// Nostr tests cover channel.lifecycle plugin behavior.
+import {
+  createStartAccountContext,
+  createPluginRuntimeMock,
+  expectStopPendingUntilAbort,
+  startAccountAndTrackLifecycle,
+  waitForStartedMocks,
+} from "actagent/plugin-sdk/channel-test-helpers";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { getActiveNostrBuses, startNostrGatewayAccount } from "./gateway.js";
+import { setNostrRuntime } from "./runtime.js";
+import { buildResolvedNostrAccount } from "./test-fixtures.js";
+
+const mocks = vi.hoisted(() => ({
+  startNostrBus: vi.fn(),
+}));
+
+vi.mock("./nostr-bus.js", () => ({
+  DEFAULT_RELAYS: ["wss://relay.example.com"],
+  startNostrBus: mocks.startNostrBus,
+}));
+
+function createMockBus() {
+  return {
+    sendDm: vi.fn(async () => {}),
+    close: vi.fn(),
+    getMetrics: vi.fn(() => ({ counters: {} })),
+    publishProfile: vi.fn(),
+    getProfileState: vi.fn(async () => null),
+  };
+}
+
+describe("nostr gateway lifecycle", () => {
+  beforeEach(() => {
+    setNostrRuntime(createPluginRuntimeMock());
+  });
+
+  afterEach(() => {
+    mocks.startNostrBus.mockReset();
+  });
+
+  it("keeps startAccount pending until abort, then closes the bus", async () => {
+    const bus = createMockBus();
+    mocks.startNostrBus.mockResolvedValueOnce(bus as never);
+
+    const { abort, task, isSettled } = startAccountAndTrackLifecycle({
+      startAccount: startNostrGatewayAccount,
+      account: buildResolvedNostrAccount(),
+    });
+
+    await expectStopPendingUntilAbort({
+      waitForStarted: waitForStartedMocks(mocks.startNostrBus),
+      isSettled,
+      abort,
+      task,
+      stop: bus.close,
+    });
+  });
+
+  it("keeps the active bus registered while pending and removes it after abort", async () => {
+    const bus = createMockBus();
+    mocks.startNostrBus.mockResolvedValueOnce(bus as never);
+
+    const { abort, task, isSettled } = startAccountAndTrackLifecycle({
+      startAccount: startNostrGatewayAccount,
+      account: buildResolvedNostrAccount(),
+    });
+
+    await vi.waitFor(() => {
+      expect(getActiveNostrBuses().get("default")).toBe(bus);
+    });
+    expect(isSettled()).toBe(false);
+
+    abort.abort();
+    await task;
+
+    expect(bus.close).toHaveBeenCalledOnce();
+    expect(getActiveNostrBuses().has("default")).toBe(false);
+  });
+
+  it("stops immediately when startAccount receives an already-aborted signal", async () => {
+    const bus = createMockBus();
+    mocks.startNostrBus.mockResolvedValueOnce(bus as never);
+    const abort = new AbortController();
+    abort.abort();
+
+    await startNostrGatewayAccount(
+      createStartAccountContext({
+        account: buildResolvedNostrAccount(),
+        abortSignal: abort.signal,
+      }),
+    );
+
+    expect(mocks.startNostrBus).toHaveBeenCalledOnce();
+    expect(bus.close).toHaveBeenCalledOnce();
+  });
+});