@kodelyth/nostr 2026.5.39 → 2026.5.42

package/src/seen-tracker.ts

@@ -0,0 +1,289 @@
+/**
+ * LRU-based seen event tracker with TTL support.
+ * Prevents unbounded memory growth under high load or abuse.
+ */
+
+interface SeenTrackerOptions {
+  /** Maximum number of entries to track (default: 100,000) */
+  maxEntries?: number;
+  /** TTL in milliseconds (default: 1 hour) */
+  ttlMs?: number;
+  /** Prune interval in milliseconds (default: 10 minutes) */
+  pruneIntervalMs?: number;
+}
+
+export interface SeenTracker {
+  /** Check if an ID has been seen (also marks it as seen if not) */
+  has: (id: string) => boolean;
+  /** Mark an ID as seen */
+  add: (id: string) => void;
+  /** Check if ID exists without marking */
+  peek: (id: string) => boolean;
+  /** Delete an ID */
+  delete: (id: string) => void;
+  /** Clear all entries */
+  clear: () => void;
+  /** Get current size */
+  size: () => number;
+  /** Stop the pruning timer */
+  stop: () => void;
+  /** Pre-seed with IDs (useful for restart recovery) */
+  seed: (ids: string[]) => void;
+}
+
+interface Entry {
+  seenAt: number;
+  // For LRU: track order via doubly-linked list
+  prev: string | null;
+  next: string | null;
+}
+
+/**
+ * Create a new seen tracker with LRU eviction and TTL expiration.
+ */
+export function createSeenTracker(options?: SeenTrackerOptions): SeenTracker {
+  const maxEntries = options?.maxEntries ?? 100_000;
+  const ttlMs = options?.ttlMs ?? 60 * 60 * 1000; // 1 hour
+  const pruneIntervalMs = options?.pruneIntervalMs ?? 10 * 60 * 1000; // 10 minutes
+
+  // Main storage
+  const entries = new Map<string, Entry>();
+
+  // LRU tracking: head = most recent, tail = least recent
+  let head: string | null = null;
+  let tail: string | null = null;
+
+  // Move an entry to the front (most recently used)
+  function moveToFront(id: string): void {
+    const entry = entries.get(id);
+    if (!entry) {
+      return;
+    }
+
+    // Already at front
+    if (head === id) {
+      return;
+    }
+
+    // Remove from current position
+    if (entry.prev) {
+      const prevEntry = entries.get(entry.prev);
+      if (prevEntry) {
+        prevEntry.next = entry.next;
+      }
+    }
+    if (entry.next) {
+      const nextEntry = entries.get(entry.next);
+      if (nextEntry) {
+        nextEntry.prev = entry.prev;
+      }
+    }
+
+    // Update tail if this was the tail
+    if (tail === id) {
+      tail = entry.prev;
+    }
+
+    // Move to front
+    entry.prev = null;
+    entry.next = head;
+    if (head) {
+      const headEntry = entries.get(head);
+      if (headEntry) {
+        headEntry.prev = id;
+      }
+    }
+    head = id;
+
+    // If no tail, this is also the tail
+    if (!tail) {
+      tail = id;
+    }
+  }
+
+  // Remove an entry from the linked list
+  function removeFromList(id: string): void {
+    const entry = entries.get(id);
+    if (!entry) {
+      return;
+    }
+
+    if (entry.prev) {
+      const prevEntry = entries.get(entry.prev);
+      if (prevEntry) {
+        prevEntry.next = entry.next;
+      }
+    } else {
+      head = entry.next;
+    }
+
+    if (entry.next) {
+      const nextEntry = entries.get(entry.next);
+      if (nextEntry) {
+        nextEntry.prev = entry.prev;
+      }
+    } else {
+      tail = entry.prev;
+    }
+  }
+
+  // Evict the least recently used entry
+  function evictLRU(): void {
+    if (!tail) {
+      return;
+    }
+    const idToEvict = tail;
+    removeFromList(idToEvict);
+    entries.delete(idToEvict);
+  }
+
+  function insertAtFront(id: string, seenAt: number): void {
+    const newEntry: Entry = {
+      seenAt,
+      prev: null,
+      next: head,
+    };
+
+    if (head) {
+      const headEntry = entries.get(head);
+      if (headEntry) {
+        headEntry.prev = id;
+      }
+    }
+
+    entries.set(id, newEntry);
+    head = id;
+    if (!tail) {
+      tail = id;
+    }
+  }
+
+  // Prune expired entries
+  function pruneExpired(): void {
+    const now = Date.now();
+    const toDelete: string[] = [];
+
+    for (const [id, entry] of entries) {
+      if (now - entry.seenAt > ttlMs) {
+        toDelete.push(id);
+      }
+    }
+
+    for (const id of toDelete) {
+      removeFromList(id);
+      entries.delete(id);
+    }
+  }
+
+  // Start pruning timer
+  let pruneTimer: ReturnType<typeof setInterval> | undefined;
+  if (pruneIntervalMs > 0) {
+    pruneTimer = setInterval(pruneExpired, pruneIntervalMs);
+    // Don't keep process alive just for pruning
+    if (pruneTimer.unref) {
+      pruneTimer.unref();
+    }
+  }
+
+  function add(id: string): void {
+    const now = Date.now();
+
+    // If already exists, update and move to front
+    const existing = entries.get(id);
+    if (existing) {
+      existing.seenAt = now;
+      moveToFront(id);
+      return;
+    }
+
+    // Evict if at capacity
+    while (entries.size >= maxEntries) {
+      evictLRU();
+    }
+
+    insertAtFront(id, now);
+  }
+
+  function has(id: string): boolean {
+    const entry = entries.get(id);
+    if (!entry) {
+      add(id);
+      return false;
+    }
+
+    // Check if expired
+    if (Date.now() - entry.seenAt > ttlMs) {
+      removeFromList(id);
+      entries.delete(id);
+      add(id);
+      return false;
+    }
+
+    // Mark as recently used
+    entry.seenAt = Date.now();
+    moveToFront(id);
+    return true;
+  }
+
+  function peek(id: string): boolean {
+    const entry = entries.get(id);
+    if (!entry) {
+      return false;
+    }
+
+    // Check if expired
+    if (Date.now() - entry.seenAt > ttlMs) {
+      removeFromList(id);
+      entries.delete(id);
+      return false;
+    }
+
+    return true;
+  }
+
+  function deleteEntry(id: string): void {
+    if (entries.has(id)) {
+      removeFromList(id);
+      entries.delete(id);
+    }
+  }
+
+  function clear(): void {
+    entries.clear();
+    head = null;
+    tail = null;
+  }
+
+  function size(): number {
+    return entries.size;
+  }
+
+  function stop(): void {
+    if (pruneTimer) {
+      clearInterval(pruneTimer);
+      pruneTimer = undefined;
+    }
+  }
+
+  function seed(ids: string[]): void {
+    const now = Date.now();
+    // Seed in reverse order so first IDs end up at front
+    for (let i = ids.length - 1; i >= 0; i--) {
+      const id = ids[i];
+      if (!entries.has(id) && entries.size < maxEntries) {
+        insertAtFront(id, now);
+      }
+    }
+  }
+
+  return {
+    has,
+    add,
+    peek,
+    delete: deleteEntry,
+    clear,
+    size,
+    stop,
+    seed,
+  };
+}

package/src/session-route.ts

@@ -0,0 +1,25 @@
+import {
+  buildChannelOutboundSessionRoute,
+  stripChannelTargetPrefix,
+  type ChannelOutboundSessionRouteParams,
+} from "klaw/plugin-sdk/core";
+
+export function resolveNostrOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
+  const target = stripChannelTargetPrefix(params.target, "nostr");
+  if (!target) {
+    return null;
+  }
+  return buildChannelOutboundSessionRoute({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "nostr",
+    accountId: params.accountId,
+    peer: {
+      kind: "direct",
+      id: target,
+    },
+    chatType: "direct",
+    from: `nostr:${target}`,
+    to: `nostr:${target}`,
+  });
+}

package/src/setup-surface.ts

@@ -0,0 +1,264 @@
+import type { ChannelSetupAdapter } from "klaw/plugin-sdk/channel-setup";
+import { DEFAULT_ACCOUNT_ID } from "klaw/plugin-sdk/routing";
+import { hasConfiguredSecretInput, normalizeSecretInputString } from "klaw/plugin-sdk/secret-input";
+import type { ChannelSetupDmPolicy, ChannelSetupWizard, DmPolicy } from "klaw/plugin-sdk/setup";
+import {
+  createSetupTranslator,
+  createStandardChannelSetupStatus,
+  createTopLevelChannelDmPolicy,
+  createTopLevelChannelParsedAllowFromPrompt,
+  formatDocsLink,
+  mergeAllowFromEntries,
+  parseSetupEntriesWithParser,
+  patchTopLevelChannelConfigSection,
+  splitSetupEntries,
+} from "klaw/plugin-sdk/setup";
+import { DEFAULT_RELAYS } from "./default-relays.js";
+import { getPublicKeyFromPrivate, normalizePubkey } from "./nostr-key-utils.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 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 = splitSetupEntries(raw);
+  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 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: ChannelSetupAdapter = {
+  resolveAccountId: ({ cfg, accountId }) => accountId?.trim() || resolveDefaultNostrAccountId(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.";
+      }
+      try {
+        getPublicKeyFromPrivate(privateKey);
+      } catch {
+        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 } : {}),
+      }),
+    });
+  },
+};
+
+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,45 @@
+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,
+  };
+}