openclaw-nostr 2026.7.30

package/src/nostr-profile.ts

@@ -0,0 +1,320 @@
+/**
+ * Nostr Profile Management (NIP-01 kind:0)
+ *
+ * Profile events are "replaceable" - the latest created_at wins.
+ * This module handles profile event creation and publishing.
+ */
+
+import { finalizeEvent, SimplePool, type Event, type EventTemplate, type VerifiedEvent } from "nostr-tools";
+
+export type EventSigner = (template: EventTemplate) => Promise<Event>;
+import { type NostrProfile, NostrProfileSchema } from "./config-schema.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Result of a profile publish attempt */
+export interface ProfilePublishResult {
+  /** Event ID of the published profile */
+  eventId: string;
+  /** Relays that successfully received the event */
+  successes: string[];
+  /** Relays that failed with their error messages */
+  failures: Array<{ relay: string; error: string }>;
+  /** Unix timestamp when the event was created */
+  createdAt: number;
+}
+
+/** NIP-01 profile content (JSON inside kind:0 event) */
+export interface ProfileContent {
+  name?: string;
+  display_name?: string;
+  about?: string;
+  picture?: string;
+  banner?: string;
+  website?: string;
+  nip05?: string;
+  lud16?: string;
+}
+
+// ============================================================================
+// Profile Content Conversion
+// ============================================================================
+
+/**
+ * Convert our config profile schema to NIP-01 content format.
+ * Strips undefined fields and validates URLs.
+ */
+export function profileToContent(profile: NostrProfile): ProfileContent {
+  const validated = NostrProfileSchema.parse(profile);
+
+  const content: ProfileContent = {};
+
+  if (validated.name !== undefined) {
+    content.name = validated.name;
+  }
+  if (validated.displayName !== undefined) {
+    content.display_name = validated.displayName;
+  }
+  if (validated.about !== undefined) {
+    content.about = validated.about;
+  }
+  if (validated.picture !== undefined) {
+    content.picture = validated.picture;
+  }
+  if (validated.banner !== undefined) {
+    content.banner = validated.banner;
+  }
+  if (validated.website !== undefined) {
+    content.website = validated.website;
+  }
+  if (validated.nip05 !== undefined) {
+    content.nip05 = validated.nip05;
+  }
+  if (validated.lud16 !== undefined) {
+    content.lud16 = validated.lud16;
+  }
+
+  return content;
+}
+
+/**
+ * Convert NIP-01 content format back to our config profile schema.
+ * Useful for importing existing profiles from relays.
+ */
+export function contentToProfile(content: ProfileContent): NostrProfile {
+  const profile: NostrProfile = {};
+
+  if (content.name !== undefined) {
+    profile.name = content.name;
+  }
+  if (content.display_name !== undefined) {
+    profile.displayName = content.display_name;
+  }
+  if (content.about !== undefined) {
+    profile.about = content.about;
+  }
+  if (content.picture !== undefined) {
+    profile.picture = content.picture;
+  }
+  if (content.banner !== undefined) {
+    profile.banner = content.banner;
+  }
+  if (content.website !== undefined) {
+    profile.website = content.website;
+  }
+  if (content.nip05 !== undefined) {
+    profile.nip05 = content.nip05;
+  }
+  if (content.lud16 !== undefined) {
+    profile.lud16 = content.lud16;
+  }
+
+  return profile;
+}
+
+// ============================================================================
+// Event Creation
+// ============================================================================
+
+/**
+ * Create a signed kind:0 profile event.
+ *
+ * @param sk - Private key as Uint8Array (32 bytes)
+ * @param profile - Profile data to include
+ * @param lastPublishedAt - Previous profile timestamp (for monotonic guarantee)
+ * @returns Signed Nostr event
+ */
+function createProfileEventTemplate(
+  profile: NostrProfile,
+  lastPublishedAt?: number,
+): EventTemplate {
+  const content = profileToContent(profile);
+  const contentJson = JSON.stringify(content);
+
+  // Ensure monotonic timestamp (new event > previous)
+  const now = Math.floor(Date.now() / 1000);
+  const createdAt = lastPublishedAt !== undefined ? Math.max(now, lastPublishedAt + 1) : now;
+
+  return {
+    kind: 0,
+    content: contentJson,
+    tags: [],
+    created_at: createdAt,
+  };
+}
+
+export function createProfileEvent(
+  sk: Uint8Array,
+  profile: NostrProfile,
+  lastPublishedAt?: number,
+): Event {
+  return finalizeEvent(createProfileEventTemplate(profile, lastPublishedAt), sk);
+}
+
+// ============================================================================
+// Profile Publishing
+// ============================================================================
+
+/**
+ * Publish a profile event to multiple relays.
+ *
+ * Best-effort: publishes to all relays in parallel, reports per-relay results.
+ * nostr-tools handles per-relay timeouts internally (~4.4s).
+ *
+ * @param pool - SimplePool instance for relay connections
+ * @param relays - Array of relay WebSocket URLs
+ * @param event - Signed profile event (kind:0)
+ * @returns Publish results with successes and failures
+ */
+export async function publishProfileEvent(
+  pool: SimplePool,
+  relays: string[],
+  event: Event,
+  onauth?: (evt: EventTemplate) => Promise<VerifiedEvent>,
+): Promise<ProfilePublishResult> {
+  const successes: string[] = [];
+  const failures: Array<{ relay: string; error: string }> = [];
+
+  // pool.publish returns an array of per-relay promises
+  const perRelayPromises = pool.publish(relays, event, {
+    ...(onauth ? { onauth } : {}),
+  }) as unknown as Promise<string>[];
+
+  const settled = await Promise.allSettled(perRelayPromises);
+  for (let i = 0; i < relays.length; i++) {
+    const result = settled[i];
+    if (result.status === "fulfilled") {
+      successes.push(relays[i]);
+    } else {
+      const errorMessage = result.reason instanceof Error ? result.reason.message : String(result.reason);
+      failures.push({ relay: relays[i], error: errorMessage });
+    }
+  }
+
+  return {
+    eventId: event.id,
+    successes,
+    failures,
+    createdAt: event.created_at,
+  };
+}
+
+/**
+ * Create and publish a profile event in one call.
+ *
+ * @param pool - SimplePool instance
+ * @param sk - Private key as Uint8Array
+ * @param relays - Array of relay URLs
+ * @param profile - Profile data
+ * @param lastPublishedAt - Previous timestamp for monotonic ordering
+ * @returns Publish results
+ */
+export async function publishProfile(
+  pool: SimplePool,
+  signEvent: EventSigner,
+  relays: string[],
+  profile: NostrProfile,
+  lastPublishedAt?: number,
+  onauth?: (evt: EventTemplate) => Promise<VerifiedEvent>,
+): Promise<ProfilePublishResult> {
+  const event = await signEvent(createProfileEventTemplate(profile, lastPublishedAt));
+  return publishProfileEvent(pool, relays, event, onauth);
+}
+
+// ============================================================================
+// NIP-65 Relay List Metadata (kind:10002)
+// ============================================================================
+
+/**
+ * Create a signed kind:10002 relay list metadata event (NIP-65).
+ * Tags each relay with "r" and an optional read/write marker.
+ *
+ * @param sk - Private key as Uint8Array (32 bytes)
+ * @param relays - Array of relay URLs (all marked as read+write)
+ * @returns Signed Nostr event
+ */
+function createRelayListEventTemplate(relays: string[]): EventTemplate {
+  return {
+    kind: 10002,
+    content: "",
+    tags: relays.map((url) => ["r", url]),
+    created_at: Math.floor(Date.now() / 1000),
+  };
+}
+
+export function createRelayListEvent(sk: Uint8Array, relays: string[]): Event {
+  return finalizeEvent(createRelayListEventTemplate(relays), sk);
+}
+
+/**
+ * Create and publish a NIP-65 relay list metadata event.
+ *
+ * @param pool - SimplePool instance
+ * @param sk - Private key as Uint8Array
+ * @param relays - Array of relay URLs to advertise and publish to
+ * @returns Publish results
+ */
+export async function publishRelayList(
+  pool: SimplePool,
+  signEvent: EventSigner,
+  relays: string[],
+  onauth?: (evt: EventTemplate) => Promise<VerifiedEvent>,
+): Promise<ProfilePublishResult> {
+  const event = await signEvent(createRelayListEventTemplate(relays));
+  return publishProfileEvent(pool, relays, event, onauth);
+}
+
+// ============================================================================
+// Profile Validation Helpers
+// ============================================================================
+
+/**
+ * Validate a profile without throwing (returns result object).
+ */
+export function validateProfile(profile: unknown): {
+  valid: boolean;
+  profile?: NostrProfile;
+  errors?: string[];
+} {
+  const result = NostrProfileSchema.safeParse(profile);
+
+  if (result.success) {
+    return { valid: true, profile: result.data };
+  }
+
+  return {
+    valid: false,
+    errors: result.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`),
+  };
+}
+
+/**
+ * Sanitize profile text fields to prevent XSS when displaying in UI.
+ * Escapes HTML special characters.
+ */
+export function sanitizeProfileForDisplay(profile: NostrProfile): NostrProfile {
+  const escapeHtml = (str: string | undefined): string | undefined => {
+    if (str === undefined) {
+      return undefined;
+    }
+    return str
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#039;");
+  };
+
+  return {
+    name: escapeHtml(profile.name),
+    displayName: escapeHtml(profile.displayName),
+    about: escapeHtml(profile.about),
+    picture: profile.picture, // URLs already validated by schema
+    banner: profile.banner,
+    website: profile.website,
+    nip05: escapeHtml(profile.nip05),
+    lud16: escapeHtml(profile.lud16),
+  };
+}

package/src/nostr-pubkey.ts

@@ -0,0 +1,56 @@
+import { nip19 } from "nostr-tools";
+
+const HEX_PUBKEY_REGEX = /^[0-9a-fA-F]{64}$/;
+
+function stripOptionalNostrPrefix(input: string): string {
+  const trimmed = input.trim();
+  return trimmed.replace(/^nostr:/i, "").trim();
+}
+
+/**
+ * Check if a string looks like a valid Nostr pubkey (hex or npub).
+ */
+export function isValidPubkey(input: string): boolean {
+  if (typeof input !== "string") return false;
+
+  try {
+    normalizePubkey(input);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalize a pubkey to canonical lowercase hex format.
+ *
+ * Accepts raw 64-character hex, lowercase npub, and either form with an
+ * optional leading nostr: prefix. Unsupported NIP-19 entities and mixed-case
+ * npub identifiers are rejected by nip19.decode.
+ */
+export function normalizePubkey(input: string): string {
+  if (typeof input !== "string") {
+    throw new Error("Pubkey must be 64 hex characters or npub format");
+  }
+
+  const normalizedInput = stripOptionalNostrPrefix(input);
+
+  if (normalizedInput.startsWith("npub1")) {
+    const decoded = nip19.decode(normalizedInput);
+    if (decoded.type !== "npub") throw new Error("Invalid npub key");
+    return decoded.data as string;
+  }
+
+  if (!HEX_PUBKEY_REGEX.test(normalizedInput)) {
+    throw new Error("Pubkey must be 64 hex characters or npub format");
+  }
+  return normalizedInput.toLowerCase();
+}
+
+/**
+ * Convert a pubkey identifier to npub format.
+ */
+export function pubkeyToNpub(pubkey: string): string {
+  const normalized = normalizePubkey(pubkey);
+  return nip19.npubEncode(normalized);
+}