@actagent/nostr 2026.6.2

package/README.md

@@ -0,0 +1,142 @@
+# @actagent/nostr
+
+Nostr DM channel plugin for ACTAgent using NIP-04 encrypted direct messages.
+
+## Overview
+
+This extension adds Nostr as a messaging channel to ACTAgent. It enables your bot to:
+
+- Receive encrypted DMs from Nostr users
+- Send encrypted responses back
+- Work with any NIP-04 compatible Nostr client (Damus, Amethyst, etc.)
+
+## Installation
+
+```bash
+actagent plugins install @actagent/nostr
+```
+
+## Quick Setup
+
+1. Generate a Nostr keypair (if you don't have one):
+
+   ```bash
+   # Using nak CLI
+   nak key generate
+
+   # Or use any Nostr key generator
+   ```
+
+2. Add to your config:
+
+   ```json
+   {
+     "channels": {
+       "nostr": {
+         "privateKey": "${NOSTR_PRIVATE_KEY}",
+         "relays": ["wss://relay.damus.io", "wss://nos.lol"]
+       }
+     }
+   }
+   ```
+
+3. Set the environment variable:
+
+   ```bash
+   export NOSTR_PRIVATE_KEY="nsec1..."  # or hex format
+   ```
+
+4. Restart the gateway
+
+## Configuration
+
+| Key          | Type     | Default                                     | Description                                                |
+| ------------ | -------- | ------------------------------------------- | ---------------------------------------------------------- |
+| `privateKey` | string   | required                                    | Bot's private key (nsec or hex format)                     |
+| `relays`     | string[] | `["wss://relay.damus.io", "wss://nos.lol"]` | WebSocket relay URLs                                       |
+| `dmPolicy`   | string   | `"pairing"`                                 | Access control: `pairing`, `allowlist`, `open`, `disabled` |
+| `allowFrom`  | string[] | `[]`                                        | Allowed sender pubkeys (npub or hex)                       |
+| `enabled`    | boolean  | `true`                                      | Enable/disable the channel                                 |
+| `name`       | string   | -                                           | Display name for the account                               |
+
+## Access Control
+
+### DM Policies
+
+- **pairing** (default): Unknown senders receive a pairing code to request access
+- **allowlist**: Only pubkeys in `allowFrom` can message the bot
+- **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
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "dmPolicy": "allowlist",
+      "allowFrom": ["npub1abc...", "0123456789abcdef..."]
+    }
+  }
+}
+```
+
+## Testing
+
+### Local Relay (Recommended)
+
+```bash
+# Using strfry
+docker run -p 7777:7777 ghcr.io/hoytech/strfry
+
+# Configure actagent to use local relay
+"relays": ["ws://localhost:7777"]
+```
+
+### Manual Test
+
+1. Start the gateway with Nostr configured
+2. Open Damus, Amethyst, or another Nostr client
+3. Send a DM to your bot's npub
+4. Verify the bot responds
+
+## Protocol Support
+
+| NIP    | Status    | Notes                  |
+| ------ | --------- | ---------------------- |
+| NIP-01 | Supported | Basic event structure  |
+| NIP-04 | Supported | Encrypted DMs (kind:4) |
+| NIP-17 | Planned   | Gift-wrapped DMs (v2)  |
+
+## Security Notes
+
+- 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
+
+## Troubleshooting
+
+### Bot not receiving messages
+
+1. Verify private key is correctly configured
+2. Check relay connectivity
+3. Ensure `enabled` is not set to `false`
+4. Check the bot's public key matches what you're sending to
+
+### Messages not being delivered
+
+1. Check relay URLs are correct (must use `wss://`)
+2. Verify relays are online and accepting connections
+3. Check for rate limiting (reduce message frequency)
+
+## License
+
+MIT

package/actagent.plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "nostr",
+  "name": "Nostr",
+  "description": "ACTAgent Nostr channel plugin for NIP-04 encrypted direct messages.",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["nostr"],
+  "channelEnvVars": {
+    "nostr": ["NOSTR_PRIVATE_KEY"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/api.ts

@@ -0,0 +1,11 @@
+// Nostr API module exposes the plugin public contract.
+export {
+  getPluginRuntimeGatewayRequestScope,
+  type ACTAgentConfig,
+  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,2 @@
+// Nostr API module exposes the plugin public contract.
+export { nostrPlugin } from "./src/channel.js";

package/doctor-contract-api.test.ts

@@ -0,0 +1,105 @@
+// Nostr tests cover doctor contract api plugin behavior.
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {
+  createPluginStateKeyedStoreForTests,
+  resetPluginStateStoreForTests,
+} from "actagent/plugin-sdk/plugin-state-test-runtime";
+import type {
+  OpenKeyedStoreOptions,
+  PluginDoctorStateMigrationContext,
+} from "actagent/plugin-sdk/runtime-doctor";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { stateMigrations } from "./doctor-contract-api.js";
+
+function createDoctorContext(env: NodeJS.ProcessEnv): PluginDoctorStateMigrationContext {
+  return {
+    openPluginStateKeyedStore<T>(options: OpenKeyedStoreOptions) {
+      return createPluginStateKeyedStoreForTests<T>("nostr", {
+        ...options,
+        env: options.env ?? env,
+      });
+    },
+  };
+}
+
+describe("nostr doctor state migration", () => {
+  let stateDir = "";
+  let env: NodeJS.ProcessEnv;
+
+  beforeEach(async () => {
+    resetPluginStateStoreForTests();
+    stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "actagent-nostr-doctor-"));
+    env = { ...process.env, ACTAGENT_STATE_DIR: stateDir };
+  });
+
+  afterEach(async () => {
+    await fs.rm(stateDir, { recursive: true, force: true });
+  });
+
+  it("imports legacy bus and profile state into plugin state", async () => {
+    const nostrDir = path.join(stateDir, "nostr");
+    const busPath = path.join(nostrDir, "bus-state-main.json");
+    const profilePath = path.join(nostrDir, "profile-state-main.json");
+    await fs.mkdir(nostrDir, { recursive: true });
+    await fs.writeFile(
+      busPath,
+      JSON.stringify({
+        version: 1,
+        lastProcessedAt: 1700,
+        gatewayStartedAt: 1600,
+      }),
+    );
+    await fs.writeFile(
+      profilePath,
+      JSON.stringify({
+        version: 1,
+        lastPublishedAt: 1800,
+        lastPublishedEventId: "event-1",
+        lastPublishResults: { "wss://relay.example": "ok", bad: "nope" },
+      }),
+    );
+
+    const context = createDoctorContext(env);
+    const busResult = await stateMigrations[0].migrateLegacyState({
+      config: {},
+      env,
+      stateDir,
+      oauthDir: path.join(stateDir, "oauth"),
+      context,
+    });
+    const profileResult = await stateMigrations[1].migrateLegacyState({
+      config: {},
+      env,
+      stateDir,
+      oauthDir: path.join(stateDir, "oauth"),
+      context,
+    });
+
+    expect(busResult.warnings).toEqual([]);
+    expect(profileResult.warnings).toEqual([]);
+    await expect(fs.access(busPath)).rejects.toThrow();
+    await expect(fs.access(profilePath)).rejects.toThrow();
+    await expect(fs.access(`${busPath}.migrated`)).resolves.toBeUndefined();
+    await expect(fs.access(`${profilePath}.migrated`)).resolves.toBeUndefined();
+    await expect(
+      context.openPluginStateKeyedStore({ namespace: "bus-state", maxEntries: 256 }).lookup("main"),
+    ).resolves.toEqual({
+      version: 2,
+      lastProcessedAt: 1700,
+      gatewayStartedAt: 1600,
+      recentEventIds: [],
+    });
+    await expect(
+      context
+        .openPluginStateKeyedStore({ namespace: "profile-state", maxEntries: 256 })
+        .lookup("main"),
+    ).resolves.toEqual({
+      version: 1,
+      lastPublishedAt: 1800,
+      lastPublishedEventId: "event-1",
+      lastPublishResults: { "wss://relay.example": "ok" },
+    });
+  });
+});

package/doctor-contract-api.ts

@@ -0,0 +1,297 @@
+// Nostr API module exposes the plugin public contract.
+import type { Dirent } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { PluginDoctorStateMigration } from "actagent/plugin-sdk/runtime-doctor";
+
+type NostrBusState = {
+  version: 2;
+  lastProcessedAt: number | null;
+  gatewayStartedAt: number | null;
+  recentEventIds: string[];
+};
+
+type NostrProfileState = {
+  version: 1;
+  lastPublishedAt: number | null;
+  lastPublishedEventId: string | null;
+  lastPublishResults: Record<string, "ok" | "failed" | "timeout"> | null;
+};
+
+const BUS_STATE_NAMESPACE = "bus-state";
+const PROFILE_STATE_NAMESPACE = "profile-state";
+const MAX_NOSTR_STATE_ENTRIES = 256;
+
+function normalizeAccountId(accountId?: string): string {
+  const trimmed = accountId?.trim();
+  if (!trimmed) {
+    return "default";
+  }
+  return trimmed.replace(/[^a-z0-9._-]+/gi, "_");
+}
+
+function finiteNumberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function parseBusState(value: unknown): NostrBusState | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const parsed = value as Record<string, unknown>;
+  if (parsed.version !== 1 && parsed.version !== 2) {
+    return null;
+  }
+  return {
+    version: 2,
+    lastProcessedAt: finiteNumberOrNull(parsed.lastProcessedAt),
+    gatewayStartedAt: finiteNumberOrNull(parsed.gatewayStartedAt),
+    recentEventIds:
+      parsed.version === 2 && Array.isArray(parsed.recentEventIds)
+        ? parsed.recentEventIds.filter((entry): entry is string => typeof entry === "string")
+        : [],
+  };
+}
+
+function parseProfileState(value: unknown): NostrProfileState | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const parsed = value as Record<string, unknown>;
+  if (parsed.version !== 1) {
+    return null;
+  }
+  const rawResults = parsed.lastPublishResults;
+  const lastPublishResults: Record<string, "ok" | "failed" | "timeout"> = {};
+  if (rawResults && typeof rawResults === "object" && !Array.isArray(rawResults)) {
+    for (const [relay, result] of Object.entries(rawResults)) {
+      if (result === "ok" || result === "failed" || result === "timeout") {
+        lastPublishResults[relay] = result;
+      }
+    }
+  }
+  return {
+    version: 1,
+    lastPublishedAt: finiteNumberOrNull(parsed.lastPublishedAt),
+    lastPublishedEventId:
+      typeof parsed.lastPublishedEventId === "string" ? parsed.lastPublishedEventId : null,
+    lastPublishResults:
+      rawResults === null || Object.keys(lastPublishResults).length === 0
+        ? null
+        : lastPublishResults,
+  };
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonFile(filePath: string): Promise<unknown> {
+  return JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
+}
+
+async function listLegacyFiles(params: {
+  stateDir: string;
+  prefix: string;
+  parse: (value: unknown) => unknown;
+}): Promise<Array<{ accountId: string; filePath: string; value: unknown }>> {
+  const dir = path.join(params.stateDir, "nostr");
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const suffix = ".json";
+  const files: Array<{ accountId: string; filePath: string; value: unknown }> = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.startsWith(params.prefix) || !entry.name.endsWith(suffix)) {
+      continue;
+    }
+    const rawAccountId = entry.name.slice(params.prefix.length, -suffix.length);
+    const accountId = normalizeAccountId(rawAccountId);
+    const filePath = path.join(dir, entry.name);
+    try {
+      const value = params.parse(await readJsonFile(filePath));
+      if (value) {
+        files.push({ accountId, filePath, value });
+      }
+    } catch {
+      // Malformed legacy cache/cursor files are ignored by migration.
+    }
+  }
+  return files;
+}
+
+async function archiveLegacySource(params: {
+  filePath: string;
+  label: string;
+  changes: string[];
+  warnings: string[];
+}): Promise<void> {
+  const archivedPath = `${params.filePath}.migrated`;
+  if (await fileExists(archivedPath)) {
+    params.warnings.push(
+      `Left migrated ${params.label} source in place because ${archivedPath} already exists`,
+    );
+    return;
+  }
+  try {
+    await fs.rename(params.filePath, archivedPath);
+    params.changes.push(`Archived ${params.label} legacy source -> ${archivedPath}`);
+  } catch (err) {
+    params.warnings.push(`Failed archiving ${params.label} legacy source: ${String(err)}`);
+  }
+}
+
+async function ensureStoreCapacity(params: {
+  files: Array<{ accountId: string }>;
+  store: { entries: () => Promise<Array<{ key: string; value: unknown }>> };
+  maxEntries: number;
+  label: string;
+  warnings: string[];
+}): Promise<Set<string> | null> {
+  const existingKeys = new Set((await params.store.entries()).map((entry) => entry.key));
+  const missingKeys = new Set(
+    params.files.map((file) => file.accountId).filter((key) => !existingKeys.has(key)),
+  );
+  if (missingKeys.size > params.maxEntries - existingKeys.size) {
+    params.warnings.push(
+      `Skipped migrating ${params.label} because plugin state has room for ${params.maxEntries - existingKeys.size} of ${missingKeys.size} missing entries; left legacy sources in place`,
+    );
+    return null;
+  }
+  return existingKeys;
+}
+
+export const stateMigrations: PluginDoctorStateMigration[] = [
+  {
+    id: "nostr-bus-state-json-to-plugin-state",
+    label: "Nostr bus state",
+    async detectLegacyState(params) {
+      const files = await listLegacyFiles({
+        stateDir: params.stateDir,
+        prefix: "bus-state-",
+        parse: parseBusState,
+      });
+      if (files.length === 0) {
+        return null;
+      }
+      return {
+        preview: [
+          `- Nostr bus state: ${files.length} ${files.length === 1 ? "account" : "accounts"} -> plugin state (${BUS_STATE_NAMESPACE})`,
+        ],
+      };
+    },
+    async migrateLegacyState(params) {
+      const changes: string[] = [];
+      const warnings: string[] = [];
+      const files = await listLegacyFiles({
+        stateDir: params.stateDir,
+        prefix: "bus-state-",
+        parse: parseBusState,
+      });
+      const store = params.context.openPluginStateKeyedStore<NostrBusState>({
+        namespace: BUS_STATE_NAMESPACE,
+        maxEntries: MAX_NOSTR_STATE_ENTRIES,
+      });
+      const existingKeys = await ensureStoreCapacity({
+        files,
+        store,
+        maxEntries: MAX_NOSTR_STATE_ENTRIES,
+        label: "Nostr bus state",
+        warnings,
+      });
+      if (!existingKeys) {
+        return { changes, warnings };
+      }
+      let imported = 0;
+      for (const file of files) {
+        if (!existingKeys.has(file.accountId)) {
+          await store.register(file.accountId, file.value as NostrBusState);
+          existingKeys.add(file.accountId);
+          imported++;
+        }
+        await archiveLegacySource({
+          filePath: file.filePath,
+          label: "Nostr bus state",
+          changes,
+          warnings,
+        });
+      }
+      if (imported > 0) {
+        changes.unshift(
+          `Migrated ${imported} Nostr bus-state ${imported === 1 ? "entry" : "entries"} -> plugin state`,
+        );
+      }
+      return { changes, warnings };
+    },
+  },
+  {
+    id: "nostr-profile-state-json-to-plugin-state",
+    label: "Nostr profile state",
+    async detectLegacyState(params) {
+      const files = await listLegacyFiles({
+        stateDir: params.stateDir,
+        prefix: "profile-state-",
+        parse: parseProfileState,
+      });
+      if (files.length === 0) {
+        return null;
+      }
+      return {
+        preview: [
+          `- Nostr profile state: ${files.length} ${files.length === 1 ? "account" : "accounts"} -> plugin state (${PROFILE_STATE_NAMESPACE})`,
+        ],
+      };
+    },
+    async migrateLegacyState(params) {
+      const changes: string[] = [];
+      const warnings: string[] = [];
+      const files = await listLegacyFiles({
+        stateDir: params.stateDir,
+        prefix: "profile-state-",
+        parse: parseProfileState,
+      });
+      const store = params.context.openPluginStateKeyedStore<NostrProfileState>({
+        namespace: PROFILE_STATE_NAMESPACE,
+        maxEntries: MAX_NOSTR_STATE_ENTRIES,
+      });
+      const existingKeys = await ensureStoreCapacity({
+        files,
+        store,
+        maxEntries: MAX_NOSTR_STATE_ENTRIES,
+        label: "Nostr profile state",
+        warnings,
+      });
+      if (!existingKeys) {
+        return { changes, warnings };
+      }
+      let imported = 0;
+      for (const file of files) {
+        if (!existingKeys.has(file.accountId)) {
+          await store.register(file.accountId, file.value as NostrProfileState);
+          existingKeys.add(file.accountId);
+          imported++;
+        }
+        await archiveLegacySource({
+          filePath: file.filePath,
+          label: "Nostr profile state",
+          changes,
+          warnings,
+        });
+      }
+      if (imported > 0) {
+        changes.unshift(
+          `Migrated ${imported} Nostr profile-state ${imported === 1 ? "entry" : "entries"} -> plugin state`,
+        );
+      }
+      return { changes, warnings };
+    },
+  },
+];

package/index.ts

@@ -0,0 +1,96 @@
+// Nostr plugin entrypoint registers its ACTAgent integration.
+import {
+  defineBundledChannelEntry,
+  loadBundledEntryExportSync,
+} from "actagent/plugin-sdk/channel-entry-contract";
+import type { ACTAgentConfig, PluginRuntime, ResolvedNostrAccount } from "./api.js";
+
+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",
+  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.current() as ACTAgentConfig;
+        const account = resolveNostrAccount({ cfg, accountId });
+        return account.profile;
+      },
+      updateConfigProfile: async (_accountId: string, profile: unknown) => {
+        const runtime = getNostrRuntime();
+
+        await runtime.config.mutateConfigFile({
+          afterWrite: { mode: "auto" },
+          mutate: (draft) => {
+            const channels = (draft.channels ?? {}) as Record<string, unknown>;
+            const nostrConfig = (channels.nostr ?? {}) as Record<string, unknown>;
+
+            draft.channels = {
+              ...channels,
+              nostr: {
+                ...nostrConfig,
+                profile,
+              },
+            };
+          },
+        });
+      },
+      getAccountInfo: (accountId: string) => {
+        const runtime = getNostrRuntime();
+        const cfg = runtime.config.current() as ACTAgentConfig;
+        const account = resolveNostrAccount({ cfg, accountId });
+        if (!account.configured || !account.publicKey) {
+          return null;
+        }
+        return {
+          pubkey: account.publicKey,
+          relays: account.relays,
+        };
+      },
+      log: api.logger,
+    });
+
+    api.registerHttpRoute({
+      path: "/api/channels/nostr",
+      auth: "gateway",
+      match: "prefix",
+      gatewayRuntimeScopeSurface: "trusted-operator",
+      handler: httpHandler,
+    });
+  },
+});