@actagent/nostr 2026.6.2

package/src/setup-adapter.ts

@@ -0,0 +1,86 @@
+// Nostr plugin module implements setup adapter behavior.
+import type { ChannelSetupAdapter } from "actagent/plugin-sdk/channel-setup";
+import type { ACTAgentConfig } from "actagent/plugin-sdk/config-contracts";
+import { DEFAULT_ACCOUNT_ID } from "actagent/plugin-sdk/routing";
+import { patchTopLevelChannelConfigSection, splitSetupEntries } from "actagent/plugin-sdk/setup";
+import { uniqueStrings } from "actagent/plugin-sdk/string-coerce-runtime";
+
+const channel = "nostr" as const;
+
+export function buildNostrSetupPatch(accountId: string, patch: Record<string, unknown>) {
+  return {
+    ...(accountId !== DEFAULT_ACCOUNT_ID ? { defaultAccount: accountId } : {}),
+    ...patch,
+  };
+}
+
+export function parseRelayUrls(raw: string): { relays: string[]; error?: string } {
+  const relays: string[] = [];
+  for (const entry of splitSetupEntries(raw)) {
+    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: uniqueStrings(relays) };
+}
+
+export function createNostrSetupAdapter(params: {
+  resolveAccountId: (cfg: ACTAgentConfig, accountId?: string | null) => string;
+  validatePrivateKey: (privateKey: string) => boolean;
+}): ChannelSetupAdapter {
+  return {
+    resolveAccountId: ({ cfg, accountId }) => params.resolveAccountId(cfg, accountId),
+    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 (!params.validatePrivateKey(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 } : {}),
+        }),
+      });
+    },
+  };
+}

package/src/setup-surface.ts

@@ -0,0 +1,204 @@
+// Nostr plugin module implements setup surface behavior.
+import { DEFAULT_ACCOUNT_ID } from "actagent/plugin-sdk/routing";
+// Nostr plugin module implements setup surface behavior.
+import {
+  hasConfiguredSecretInput,
+  normalizeSecretInputString,
+} from "actagent/plugin-sdk/secret-input";
+import type { ChannelSetupDmPolicy, ChannelSetupWizard, DmPolicy } from "actagent/plugin-sdk/setup";
+import {
+  createSetupTranslator,
+  createStandardChannelSetupStatus,
+  createTopLevelChannelDmPolicy,
+  createTopLevelChannelParsedAllowFromPrompt,
+  formatDocsLink,
+  mergeAllowFromEntries,
+  parseSetupEntriesWithParser,
+  patchTopLevelChannelConfigSection,
+} from "actagent/plugin-sdk/setup";
+import { DEFAULT_RELAYS } from "./default-relays.js";
+import { getPublicKeyFromPrivate, normalizePubkey } from "./nostr-key-utils.js";
+import { buildNostrSetupPatch, createNostrSetupAdapter, parseRelayUrls } from "./setup-adapter.js";
+import { resolveDefaultNostrAccountId, resolveNostrAccount } from "./types.js";
+
+const t = createSetupTranslator();
+
+const channel = "nostr" as const;
+const NOSTR_SETUP_HELP_LINES = [
+  t("wizard.nostr.helpPrivateKeyFormat"),
+  t("wizard.nostr.helpRelaysOptional"),
+  t("wizard.nostr.helpEnvVars"),
+  `Docs: ${formatDocsLink("/channels/nostr", "channels/nostr")}`,
+];
+
+const NOSTR_ALLOW_FROM_HELP_LINES = [
+  t("wizard.nostr.allowlistIntro"),
+  t("wizard.nostr.examples"),
+  "- npub1...",
+  "- nostr:npub1...",
+  "- 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  t("wizard.nostr.multipleEntries"),
+  `Docs: ${formatDocsLink("/channels/nostr", "channels/nostr")}`,
+];
+
+function parseNostrAllowFrom(raw: string): { entries: string[]; error?: string } {
+  return parseSetupEntriesWithParser(raw, (entry) => {
+    const cleaned = entry.replace(/^nostr:/i, "").trim();
+    try {
+      return { value: normalizePubkey(cleaned) };
+    } catch {
+      return { error: `Invalid Nostr pubkey: ${entry}` };
+    }
+  });
+}
+
+const promptNostrAllowFrom = createTopLevelChannelParsedAllowFromPrompt({
+  channel,
+  defaultAccountId: resolveDefaultNostrAccountId,
+  noteTitle: t("wizard.nostr.allowlistTitle"),
+  noteLines: NOSTR_ALLOW_FROM_HELP_LINES,
+  message: t("wizard.nostr.allowFromPrompt"),
+  placeholder: "npub1..., 0123abcd...",
+  parseEntries: parseNostrAllowFrom,
+  mergeEntries: ({ existing, parsed }) => mergeAllowFromEntries(existing, parsed),
+});
+
+const nostrDmPolicy: ChannelSetupDmPolicy = createTopLevelChannelDmPolicy({
+  label: "Nostr",
+  channel,
+  policyKey: "channels.nostr.dmPolicy",
+  allowFromKey: "channels.nostr.allowFrom",
+  getCurrent: (cfg) => (cfg.channels?.nostr?.dmPolicy as DmPolicy | undefined) ?? "pairing",
+  promptAllowFrom: promptNostrAllowFrom,
+});
+
+export const nostrSetupAdapter = createNostrSetupAdapter({
+  resolveAccountId: (cfg, accountId) => accountId?.trim() || resolveDefaultNostrAccountId(cfg),
+  validatePrivateKey: (privateKey) => {
+    try {
+      getPublicKeyFromPrivate(privateKey);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+});
+
+export const nostrSetupWizard: ChannelSetupWizard = {
+  channel,
+  resolveAccountIdForConfigure: ({ accountOverride, defaultAccountId }) =>
+    accountOverride?.trim() || defaultAccountId,
+  resolveShouldPromptAccountIds: () => false,
+  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 }) => resolveNostrAccount({ cfg }).configured,
+    resolveExtraStatusLines: ({ cfg }) => {
+      const account = resolveNostrAccount({ cfg });
+      return [`Relays: ${account.relays.length || DEFAULT_RELAYS.length}`];
+    },
+  }),
+  introNote: {
+    title: t("wizard.nostr.setupTitle"),
+    lines: NOSTR_SETUP_HELP_LINES,
+  },
+  envShortcut: {
+    prompt: t("wizard.nostr.privateKeyEnvPrompt"),
+    preferredEnvVar: "NOSTR_PRIVATE_KEY",
+    isAvailable: ({ cfg, accountId }) =>
+      accountId === DEFAULT_ACCOUNT_ID &&
+      Boolean(process.env.NOSTR_PRIVATE_KEY?.trim()) &&
+      !hasConfiguredSecretInput(resolveNostrAccount({ cfg, accountId }).config.privateKey),
+    apply: async ({ cfg, accountId }) =>
+      patchTopLevelChannelConfigSection({
+        cfg,
+        channel,
+        enabled: true,
+        clearFields: ["privateKey"],
+        patch: buildNostrSetupPatch(accountId, {}),
+      }),
+  },
+  credentials: [
+    {
+      inputKey: "privateKey",
+      providerHint: channel,
+      credentialLabel: "private key",
+      preferredEnvVar: "NOSTR_PRIVATE_KEY",
+      helpTitle: t("wizard.nostr.privateKeyTitle"),
+      helpLines: NOSTR_SETUP_HELP_LINES,
+      envPrompt: t("wizard.nostr.privateKeyEnvPrompt"),
+      keepPrompt: t("wizard.nostr.privateKeyKeep"),
+      inputPrompt: t("wizard.nostr.privateKeyInput"),
+      allowEnv: ({ accountId }) => accountId === DEFAULT_ACCOUNT_ID,
+      inspect: ({ cfg, accountId }) => {
+        const account = resolveNostrAccount({ cfg, accountId });
+        return {
+          accountConfigured: account.configured,
+          hasConfiguredValue: hasConfiguredSecretInput(account.config.privateKey),
+          resolvedValue: normalizeSecretInputString(account.config.privateKey),
+          envValue: process.env.NOSTR_PRIVATE_KEY?.trim(),
+        };
+      },
+      applyUseEnv: async ({ cfg, accountId }) =>
+        patchTopLevelChannelConfigSection({
+          cfg,
+          channel,
+          enabled: true,
+          clearFields: ["privateKey"],
+          patch: buildNostrSetupPatch(accountId, {}),
+        }),
+      applySet: async ({ cfg, accountId, resolvedValue }) =>
+        patchTopLevelChannelConfigSection({
+          cfg,
+          channel,
+          enabled: true,
+          patch: buildNostrSetupPatch(accountId, { privateKey: resolvedValue }),
+        }),
+    },
+  ],
+  textInputs: [
+    {
+      inputKey: "relayUrls",
+      message: t("wizard.nostr.relayUrlsPrompt"),
+      placeholder: DEFAULT_RELAYS.join(", "),
+      required: false,
+      applyEmptyValue: true,
+      helpTitle: t("wizard.nostr.relaysTitle"),
+      helpLines: [t("wizard.nostr.relaysWsOnly"), t("wizard.nostr.helpRelaysOptional")],
+      currentValue: ({ cfg, accountId }) => {
+        const account = resolveNostrAccount({ cfg, accountId });
+        const configuredRelays = cfg.channels?.nostr?.relays as string[] | undefined;
+        const relays = configuredRelays && configuredRelays.length > 0 ? account.relays : [];
+        return relays.join(", ");
+      },
+      keepPrompt: (value) => t("wizard.nostr.relayUrlsKeep", { value }),
+      validate: ({ value }) => parseRelayUrls(value).error,
+      applySet: async ({ cfg, accountId, value }) => {
+        const relayResult = parseRelayUrls(value);
+        return patchTopLevelChannelConfigSection({
+          cfg,
+          channel,
+          enabled: true,
+          clearFields: relayResult.relays.length > 0 ? undefined : ["relays"],
+          patch: buildNostrSetupPatch(
+            accountId,
+            relayResult.relays.length > 0 ? { relays: relayResult.relays } : {},
+          ),
+        });
+      },
+    },
+  ],
+  dmPolicy: nostrDmPolicy,
+  disable: (cfg) =>
+    patchTopLevelChannelConfigSection({
+      cfg,
+      channel,
+      patch: { enabled: false },
+    }),
+};

package/src/test-fixtures.ts

@@ -0,0 +1,46 @@
+// Nostr plugin module implements test fixtures behavior.
+import type { ResolvedNostrAccount } from "./types.js";
+
+export const TEST_HEX_PRIVATE_KEY =
+  "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+
+export const TEST_HEX_PUBLIC_KEY =
+  "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789";
+
+export const TEST_NSEC = "nsec1qypqxpq9qtpqscx7peytzfwtdjmcv0mrz5rjpej8vjppfkqfqy8skqfv3l";
+
+export const TEST_RELAY_URL = "wss://relay.example.com";
+export const TEST_SETUP_RELAY_URLS = ["wss://relay.damus.io", "wss://relay.primal.net"];
+export const TEST_RESOLVED_PRIVATE_KEY = "resolved-nostr-private-key";
+
+export const TEST_HEX_PRIVATE_KEY_BYTES = new Uint8Array(
+  TEST_HEX_PRIVATE_KEY.match(/.{2}/g)!.map((byte) => Number.parseInt(byte, 16)),
+);
+
+export function createConfiguredNostrCfg(overrides: Record<string, unknown> = {}): {
+  channels: { nostr: Record<string, unknown> };
+} {
+  return {
+    channels: {
+      nostr: {
+        privateKey: TEST_HEX_PRIVATE_KEY,
+        ...overrides,
+      },
+    },
+  };
+}
+
+export function buildResolvedNostrAccount(
+  overrides: Partial<ResolvedNostrAccount> = {},
+): ResolvedNostrAccount {
+  return {
+    accountId: "default",
+    enabled: true,
+    configured: true,
+    privateKey: TEST_HEX_PRIVATE_KEY,
+    publicKey: TEST_HEX_PUBLIC_KEY,
+    relays: [TEST_RELAY_URL],
+    config: {},
+    ...overrides,
+  };
+}

package/src/types.ts

@@ -0,0 +1,118 @@
+// Nostr type declarations define plugin contracts.
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeOptionalAccountId,
+} from "actagent/plugin-sdk/account-id";
+import {
+  listCombinedAccountIds,
+  resolveListedDefaultAccountId,
+} from "actagent/plugin-sdk/account-resolution";
+import type { ACTAgentConfig } from "actagent/plugin-sdk/config-contracts";
+import { normalizeSecretInputString, type SecretInput } from "actagent/plugin-sdk/secret-input";
+import { normalizeOptionalString } from "actagent/plugin-sdk/string-coerce-runtime";
+import type { NostrProfile } from "./config-schema.js";
+import { DEFAULT_RELAYS } from "./default-relays.js";
+import { getPublicKeyFromPrivate } from "./nostr-key-utils.js";
+
+interface NostrAccountConfig {
+  enabled?: boolean;
+  name?: string;
+  defaultAccount?: string;
+  privateKey?: SecretInput;
+  relays?: string[];
+  dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
+  allowFrom?: Array<string | number>;
+  profile?: NostrProfile;
+}
+
+export interface ResolvedNostrAccount {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  privateKey: string;
+  publicKey: string;
+  relays: string[];
+  profile?: NostrProfile;
+  config: NostrAccountConfig;
+}
+
+function resolveConfiguredDefaultNostrAccountId(cfg: ACTAgentConfig): string | undefined {
+  const nostrCfg = (cfg.channels as Record<string, unknown> | undefined)?.nostr as
+    | NostrAccountConfig
+    | undefined;
+  return normalizeOptionalAccountId(nostrCfg?.defaultAccount);
+}
+
+/**
+ * List all configured Nostr account IDs
+ */
+export function listNostrAccountIds(cfg: ACTAgentConfig): string[] {
+  const nostrCfg = (cfg.channels as Record<string, unknown> | undefined)?.nostr as
+    | NostrAccountConfig
+    | undefined;
+  const privateKey = normalizeSecretInputString(nostrCfg?.privateKey);
+  return listCombinedAccountIds({
+    configuredAccountIds: [],
+    implicitAccountId: privateKey
+      ? (resolveConfiguredDefaultNostrAccountId(cfg) ?? DEFAULT_ACCOUNT_ID)
+      : undefined,
+  });
+}
+
+/**
+ * Get the default account ID
+ */
+export function resolveDefaultNostrAccountId(cfg: ACTAgentConfig): string {
+  return resolveListedDefaultAccountId({
+    accountIds: listNostrAccountIds(cfg),
+    configuredDefaultAccountId: resolveConfiguredDefaultNostrAccountId(cfg),
+  });
+}
+
+/**
+ * Resolve a Nostr account from config
+ */
+export function resolveNostrAccount(opts: {
+  cfg: ACTAgentConfig;
+  accountId?: string | null;
+}): ResolvedNostrAccount {
+  const accountId = normalizeAccountId(opts.accountId ?? resolveDefaultNostrAccountId(opts.cfg));
+  const nostrCfg = (opts.cfg.channels as Record<string, unknown> | undefined)?.nostr as
+    | NostrAccountConfig
+    | undefined;
+
+  const baseEnabled = nostrCfg?.enabled !== false;
+  const privateKey = normalizeSecretInputString(nostrCfg?.privateKey) ?? "";
+  const configured = Boolean(privateKey);
+
+  let publicKey = "";
+  if (privateKey) {
+    try {
+      publicKey = getPublicKeyFromPrivate(privateKey);
+    } catch {
+      // Invalid key - leave publicKey empty, configured will indicate issues
+    }
+  }
+
+  return {
+    accountId,
+    name: normalizeOptionalString(nostrCfg?.name),
+    enabled: baseEnabled,
+    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,
+    },
+  };
+}

package/test/setup.ts

@@ -0,0 +1,5 @@
+// Test setup file for nostr extension
+import { vi } from "vitest";
+
+// Mock console.error to suppress noise in tests
+vi.spyOn(console, "error").mockImplementation(() => {});

package/test-api.ts

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

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}