@gakr-gakr/nostr 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# @gakr-gakr/nostr
+
+Nostr DM channel plugin for AutoBot using NIP-04 encrypted direct messages.
+
+## Overview
+
+This extension adds Nostr as a messaging channel to AutoBot. 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
+autobot plugins install @gakr-gakr/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 autobot 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/api.ts

@@ -0,0 +1,10 @@
+export {
+  getPluginRuntimeGatewayRequestScope,
+  type AutoBotConfig,
+  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/autobot.plugin.json

@@ -0,0 +1,15 @@
+{
+  "id": "nostr",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["nostr"],
+  "channelEnvVars": {
+    "nostr": ["NOSTR_PRIVATE_KEY"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/channel-plugin-api.ts

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

package/index.ts

@@ -0,0 +1,95 @@
+import {
+  defineBundledChannelEntry,
+  loadBundledEntryExportSync,
+} from "autobot/plugin-sdk/channel-entry-contract";
+import type { AutoBotConfig, 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 AutoBotConfig;
+        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 AutoBotConfig;
+        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,
+    });
+  },
+});

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@gakr-gakr/nostr",
+  "version": "0.1.0",
+  "description": "AutoBot Nostr channel plugin for NIP-04 encrypted DMs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "dependencies": {
+    "nostr-tools": "2.23.3",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@gakr-gakr/plugin-sdk": "workspace:*",
+    "@gakr-gakr/autobot": "workspace:*",
+    "autobot": "workspace:@gakr-gakr/autobot@*"
+  },
+  "peerDependencies": {
+    "@gakr-gakr/autobot": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@gakr-gakr/autobot": {
+      "optional": true
+    }
+  },
+  "autobot": {
+    "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": "@gakr-gakr/nostr",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.19"
+    },
+    "build": {
+      "autobotVersion": "2026.5.19"
+    },
+    "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 { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+export { getPluginRuntimeGatewayRequestScope } from "autobot/plugin-sdk/plugin-runtime";
+export type { PluginRuntime } from "autobot/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 "autobot/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,11 @@
+export {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  formatPairingApproveHint,
+  type ChannelPlugin,
+} from "autobot/plugin-sdk/channel-plugin-common";
+export type { ChannelOutboundAdapter } from "autobot/plugin-sdk/channel-contract";
+export {
+  collectStatusIssuesFromLastError,
+  createDefaultChannelRuntimeState,
+} from "autobot/plugin-sdk/status-helpers";

package/src/channel.setup.ts

@@ -0,0 +1,234 @@
+import { describeAccountSnapshot } from "autobot/plugin-sdk/account-helpers";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { patchTopLevelChannelConfigSection } from "autobot/plugin-sdk/setup";
+import {
+  createDelegatedSetupWizardProxy,
+  createStandardChannelSetupStatus,
+  DEFAULT_ACCOUNT_ID,
+  createSetupTranslator,
+  type ChannelSetupAdapter,
+} from "autobot/plugin-sdk/setup-runtime";
+import { buildChannelConfigSchema, type ChannelPlugin } from "./channel-api.js";
+import { NostrConfigSchema } from "./config-schema.js";
+import { DEFAULT_RELAYS } from "./default-relays.js";
+
+const t = createSetupTranslator();
+
+const channel = "nostr" as const;
+
+type NostrAccountConfig = {
+  enabled?: boolean;
+  name?: string;
+  defaultAccount?: string;
+  privateKey?: unknown;
+  relays?: string[];
+  dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
+  allowFrom?: Array<string | number>;
+  profile?: unknown;
+};
+
+type ResolvedNostrSetupAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  privateKey: string;
+  publicKey: string;
+  relays: string[];
+  profile?: unknown;
+  config: NostrAccountConfig;
+};
+
+function getNostrConfig(cfg: AutoBotConfig): NostrAccountConfig | undefined {
+  return (cfg.channels as Record<string, unknown> | undefined)?.nostr as
+    | NostrAccountConfig
+    | undefined;
+}
+
+function listSetupNostrAccountIds(cfg: AutoBotConfig): string[] {
+  const nostrCfg = getNostrConfig(cfg);
+  const privateKey = typeof nostrCfg?.privateKey === "string" ? nostrCfg.privateKey.trim() : "";
+  if (!privateKey) {
+    return [];
+  }
+  return [resolveDefaultSetupNostrAccountId(cfg)];
+}
+
+function resolveDefaultSetupNostrAccountId(cfg: AutoBotConfig): string {
+  const configured = getNostrConfig(cfg)?.defaultAccount;
+  return typeof configured === "string" && configured.trim()
+    ? configured.trim()
+    : DEFAULT_ACCOUNT_ID;
+}
+
+function resolveSetupNostrAccount(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): ResolvedNostrSetupAccount {
+  const nostrCfg = getNostrConfig(params.cfg);
+  const accountId = params.accountId?.trim() || resolveDefaultSetupNostrAccountId(params.cfg);
+  const privateKey = typeof nostrCfg?.privateKey === "string" ? nostrCfg.privateKey.trim() : "";
+  const configured = Boolean(privateKey);
+  return {
+    accountId,
+    name: typeof nostrCfg?.name === "string" ? nostrCfg.name : undefined,
+    enabled: nostrCfg?.enabled !== false,
+    configured,
+    privateKey,
+    publicKey: "",
+    relays: nostrCfg?.relays ?? DEFAULT_RELAYS,
+    profile: nostrCfg?.profile,
+    config: {
+      enabled: nostrCfg?.enabled,
+      name: nostrCfg?.name,
+      privateKey: nostrCfg?.privateKey,
+      relays: nostrCfg?.relays,
+      dmPolicy: nostrCfg?.dmPolicy,
+      allowFrom: nostrCfg?.allowFrom,
+      profile: nostrCfg?.profile,
+    },
+  };
+}
+
+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 = raw
+    .split(/[,\n]/)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  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 looksLikeNostrPrivateKey(privateKey: string): boolean {
+  return privateKey.startsWith("nsec1") || /^[0-9a-fA-F]{64}$/.test(privateKey);
+}
+
+const nostrSetupAdapter: ChannelSetupAdapter = {
+  resolveAccountId: ({ cfg, accountId }) =>
+    accountId?.trim() || resolveDefaultSetupNostrAccountId(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.";
+      }
+      if (!looksLikeNostrPrivateKey(privateKey)) {
+        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 } : {}),
+      }),
+    });
+  },
+};
+
+const nostrSetupWizard = createDelegatedSetupWizardProxy({
+  channel,
+  loadWizard: async () => (await import("./setup-surface.js")).nostrSetupWizard,
+  status: {
+    ...createStandardChannelSetupStatus({
+      channelLabel: "Nostr",
+      configuredLabel: t("wizard.channels.statusConfigured"),
+      unconfiguredLabel: t("wizard.channels.statusNeedsPrivateKey"),
+      configuredHint: t("wizard.channels.statusConfigured"),
+      unconfiguredHint: t("wizard.channels.statusNeedsPrivateKey"),
+      configuredScore: 1,
+      unconfiguredScore: 0,
+      includeStatusLine: true,
+      resolveConfigured: ({ cfg, accountId }) =>
+        resolveSetupNostrAccount({ cfg, accountId }).configured,
+      resolveExtraStatusLines: ({ cfg }) => {
+        const account = resolveSetupNostrAccount({ cfg });
+        return [`Relays: ${account.relays.length || DEFAULT_RELAYS.length}`];
+      },
+    }),
+  },
+  resolveShouldPromptAccountIds: () => false,
+  delegatePrepare: true,
+  delegateFinalize: true,
+});
+
+export const nostrSetupPlugin: ChannelPlugin<ResolvedNostrSetupAccount> = {
+  id: channel,
+  meta: {
+    id: channel,
+    label: "Nostr",
+    selectionLabel: "Nostr",
+    docsPath: "/channels/nostr",
+    docsLabel: "nostr",
+    blurb: "Decentralized DMs via Nostr relays (NIP-04)",
+    order: 100,
+  },
+  capabilities: {
+    chatTypes: ["direct"],
+    media: false,
+  },
+  reload: { configPrefixes: ["channels.nostr"] },
+  configSchema: buildChannelConfigSchema(NostrConfigSchema),
+  setup: nostrSetupAdapter,
+  setupWizard: nostrSetupWizard,
+  config: {
+    listAccountIds: listSetupNostrAccountIds,
+    resolveAccount: (cfg, accountId) => resolveSetupNostrAccount({ cfg, accountId }),
+    defaultAccountId: resolveDefaultSetupNostrAccountId,
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) =>
+      describeAccountSnapshot({
+        account,
+        configured: account.configured,
+        extra: {
+          publicKey: account.publicKey,
+        },
+      }),
+  },
+};