@nostr-wot/dm

@nostr-wot/dm

Direct messages for Nostr — encryption primitives, a streaming inbox cache, and React hooks. One package, three layers, pick what you need.

Entry	What's in it	Depends on
@nostr-wot/dm	Crypto primitives: NIP-04 encrypt/decrypt, NIP-17 seal + gift-wrap	nostr-tools, @nostr-wot/signers
@nostr-wot/dm/cache	Per-session inbox: live subscription, auto-decrypt, send, backfill, read cursors, encrypted-at-rest storage	+ @nostr-wot/data
@nostr-wot/dm/react	Hooks: useDMSession, useThread, useConversations, useUnreadCount, …	+ react (peer)

Install

npm i @nostr-wot/dm @nostr-wot/signers nostr-tools
# add @nostr-wot/data + react if using /cache or /react

Layer 1 — Crypto primitives

@nostr-wot/dm (the root entry) exposes pure, signer-driven encryption/decryption. No subscriptions, no cache.

NIP-17 sealed messages (recommended)

Built on NIP-44 v2 + gift wrapping. Hides sender; recipient is visible only via the wrap's p tag. Seal + wrap timestamps are randomized within ±2 days of now so traffic-analysis can't correlate.

import { buildChatMessage, sealAndGiftWrap, unwrapGiftWrap } from "@nostr-wot/dm";
import { Nip07Signer } from "@nostr-wot/signers";

const signer = new Nip07Signer();
const me = await signer.getPublicKey();

// Send
const inner = buildChatMessage(me, recipientPubkey, "hello");
const giftWrap = await sealAndGiftWrap(signer, recipientPubkey, inner);
// publish giftWrap (kind 1059) to recipient's read relays

// Receive
const { message, senderPubkey } = await unwrapGiftWrap(signer, giftWrap);
// message.content is the plaintext, senderPubkey recovered from the seal

NIP-04 (legacy)

Kind-4 AES-CBC. Sender + recipient visible on the wire. Still widely deployed; use as fallback only.

import { encryptNip04, decryptNip04 } from "@nostr-wot/dm";

const event = await encryptNip04(signer, recipientPubkey, "hello");
const plaintext = await decryptNip04(signer, event);

Layer 2 — Cache (/cache)

A complete inbox subsystem: subscribes to inbound events, auto-decrypts via your signer, dedupes, ingests into in-memory observables, and (optionally) persists to a DMStorage backend. Built on @nostr-wot/data's sharedCoalescer, so DM subscriptions piggyback on the same connection pool used by profile/note fetchers.

Bootstrap a session

import {
  initDMSession,
  subscribeInbox,
  sendDM,
  localStorageDMStorage,
} from "@nostr-wot/dm/cache";

const session = await initDMSession({
  myPubkey,
  signer,
  relays: ["wss://relay.damus.io", "wss://nos.lol"],
  storage: localStorageDMStorage(),  // optional persistence
  discoverInboxRelays: true,         // auto-resolve kind 10050
});

const stop = subscribeInbox(session); // live; returns teardown

await sendDM(session, partnerPubkey, "hi", { scheme: "nip17" }); // default

subscribeInbox opens three coalesced subscriptions: NIP-04 inbound (#p == me), NIP-04 outbound echo (authors == me), and NIP-17 gift wraps (#p == me). Every event is decrypted and ingested through the same ingestMessage pipeline — UI subscribers see one consistent stream.

Inbox-relay discovery + publishing (kind 10050)

import { fetchInboxRelays, publishInboxRelays } from "@nostr-wot/dm/cache";

// Where do my DMs go?
const inbox = await fetchInboxRelays(myPubkey, defaultRelays);

// Tell other clients where to send my DMs
await publishInboxRelays(signer, /* publish to */ relays, /* inbox = */ inbox);

Without a kind-10050, your NIP-17 DMs only arrive from senders who happen to share a relay with you.

Historical backfill

subscribeInbox only catches new events. To populate threads on first login (or after a long offline period), walk past kind-1059 wraps:

import { backfillInbox } from "@nostr-wot/dm/cache";

const { partners, ingested, windowsWalked } = await backfillInbox(session, {
  windows: 12,         // 12 × 30-day = ≈1 year
  limit: 200,          // events per window per filter
  minPartners: 50,     // stop once enough partners discovered
  timeoutMs: 30_000,   // hard wallclock budget
});

Read cursors (device-local)

Read state is intentionally never synced to relays — no server should know who you're DMing. Read cursors live in localStorage, keyed per account.

import {
  markRead,
  setReadCursor,
  getReadCursor,
  getUnreadCount,
  getUnreadCounts,
  detectScheme,
} from "@nostr-wot/dm/cache";

markRead(myPubkey, partnerPubkey);
const unread = getUnreadCount(myPubkey, partnerPubkey);
const allUnreads = getUnreadCounts(myPubkey);  // { partnerHex: n, ... }

// Predict whether to send NIP-04 or NIP-17 to a partner based on
// the most recent cached messages.
const scheme = detectScheme(messages); // "nip04" | "nip17" | null

Encrypted-at-rest storage

Wrap any DMStorage with AES-GCM encryption keyed by a NIP-44-self-encrypted KEK. The raw key is imported as a non-extractable WebCrypto key — XSS can call your encrypt/decrypt helpers but cannot exfiltrate the bytes.

import {
  initDMSession,
  localStorageDMStorage,
  getOrCreateCacheKey,
  wrapStorageWithEncryption,
} from "@nostr-wot/dm/cache";

const key = await getOrCreateCacheKey(myPubkey, signer);  // one-time signer prompt
const storage = wrapStorageWithEncryption(localStorageDMStorage()!, key);

await initDMSession({ myPubkey, signer, relays, storage });

Custom storage backends

import type { DMStorage } from "@nostr-wot/dm/cache";

const indexedDBStorage: DMStorage = {
  async load(myPubkey) { /* ... */ },
  async save(myPubkey, conversations) { /* ... */ },
};

Auto-persist + eviction

When you pass a storage to initDMSession, the session auto-persists on a debounce (default 500ms) after every cache mutation. Set autoPersist: false for manual control, or tune the debounce with autoPersistDebounceMs.

After each mutation the session also calls evictIfNeeded(myPubkey, evictionCap) (default cap 2000). Eviction is a no-op until you register a follow set — without one, every partner is treated as protected:

import { setFollowSet } from "@nostr-wot/dm/cache";
import { fetchFollows } from "@nostr-wot/data";

const follows = await fetchFollows(myPubkey);
setFollowSet(myPubkey, new Set(follows.pubkeys));   // enables eviction
// or pass null to explicitly mark "follows un-hydrated → protect everything"
setFollowSet(myPubkey, null);

Followed partners are never evicted; oldest non-followed messages drop first once the cap is exceeded.

Logout / account switch

import { closeDMSession, clearDMSession } from "@nostr-wot/dm/cache";

closeDMSession(session);                               // stop subscriptions
await clearDMSession(myPubkey, { storage, clearStorage: true }); // wipe state

Adapting an NDK signer

If you already have an NDK-based app, wrap your NDKSigner once and use the SDK end-to-end:

import { ndkSignerAsNostrSigner } from "@nostr-wot/signers";
import { NDKEvent } from "@nostr-dev-kit/ndk";

const signer = ndkSignerAsNostrSigner({
  ndk,
  NDKEvent,
});

await initDMSession({ myPubkey, signer, relays });

Layer 3 — React (/react)

Hooks built on useSyncExternalStore. Concurrent-mode safe; no double-renders.

import {
  useDMSession,
  useConversations,
  useThread,
  useUnreadCount,
  useUnreadCounts,
} from "@nostr-wot/dm/react";

function Inbox({ myPubkey, signer, relays }) {
  const { session, sendDM } = useDMSession({ signer, relays });
  const conversations = useConversations(myPubkey);
  const unreads = useUnreadCounts(myPubkey);

  return conversations.map((c) => (
    <Row
      key={c.partnerPubkey}
      preview={c.preview}
      lastAt={c.lastMessageAt}
      unread={unreads[c.partnerPubkey] ?? 0}
    />
  ));
}

function Thread({ myPubkey, partnerPubkey }) {
  const messages = useThread(myPubkey, partnerPubkey);
  const unread = useUnreadCount(myPubkey, partnerPubkey);
  return <ChatLog messages={messages} unread={unread} />;
}

useDMSession auto-subscribes to the inbox on mount and tears down on unmount. The returned sendDM is a stable callback bound to the session.

API surface

@nostr-wot/dm

Export	Purpose
KIND_NIP04_DM, KIND_NIP44_DM, KIND_SEALED, KIND_GIFT_WRAP	Event-kind constants
encryptNip04(signer, pk, plain)	→ kind-4 event
decryptNip04(signer, event)	→ plaintext
buildChatMessage(from, to, content, opts?)	→ kind-14 unsigned template
sealAndGiftWrap(signer, recipient, message)	→ kind-1059 event
unwrapGiftWrap(signer, giftWrap)	→ { message, senderPubkey }

@nostr-wot/dm/cache

Export	Purpose
initDMSession({ myPubkey, signer, relays, storage?, discoverInboxRelays?, autoPersist?, autoPersistDebounceMs?, evictionCap? })	Bootstrap + hydrate + auto-persist + eviction
closeDMSession(session)	Tear down subscriptions
clearDMSession(myPubkey, { storage?, clearStorage? })	Wipe per-account state
subscribeInbox(session)	Live decrypt loop; returns teardown
sendDM(session, partner, content, { scheme? })	Publish + local-echo
persistDMSession(session)	Manual snapshot to storage
backfillInbox(session, opts?)	Historical walker
fetchInboxRelays(pubkey, fallback)	Resolve kind 10050
publishInboxRelays(signer, publishRelays, inboxRelays)	Publish kind 10050
relaysForPartner(partner, defaults)	NIP-65 outbox merge
setReadCursor, markRead, getReadCursor, getReadCursors	Read-state
getUnreadCount, getUnreadCounts, subscribeReadCursors	Unread API
detectScheme(messages)	NIP-04 vs NIP-17 prediction
setFollowSet, getFollowSet, subscribeFollowSet	Follow set for eviction
evictIfNeeded(myPubkey, cap?)	Manual follow-aware LRU pass
getOrCreateCacheKey(myPubkey, signer)	KEK derivation
encryptToCache(key, str), decryptFromCache(key, blob)	At-rest crypto
wrapStorageWithEncryption(storage, key)	At-rest DMStorage adapter
localStorageDMStorage()	Built-in plaintext storage
KIND_NIP17_INBOX_RELAYS (10050)	Constant

@nostr-wot/dm/react

Export	Purpose
useDMSession({ signer, relays, storage?, discoverInboxRelays? })	Bootstrap + auto-subscribe
useThread(myPubkey, partner)	DMMessage[]
useConversations(myPubkey)	DMConversation[]
useUnreadCount(myPubkey, partner)	number
useUnreadCounts(myPubkey)	Record<partner, number>
useReadCursors(myPubkey)	Record<partner, msTs>

Types

type DMMessage = {
  id: string;
  fromPubkey: string;
  partnerPubkey: string;
  content: string;
  createdAt: number;       // unix seconds
  scheme: "nip04" | "nip17";
  raw?: NostrEvent;
};

type DMConversation = {
  partnerPubkey: string;
  lastMessageAt: number;
  preview: string;
  messageCount: number;
};

interface DMStorage {
  load(myPubkey: string): Promise<Record<string, DMMessage[]>>;
  save(myPubkey: string, conversations: Record<string, DMMessage[]>): Promise<void>;
}

License

MIT