@kodelyth/nostr 2026.5.39 → 2026.5.42

package/README.md

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

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

package/dist/api.js

@@ -0,0 +1,522 @@
+import { o as resolveNostrAccount } from "./setup-surface-DFlfVW6j.js";
+import { getPluginRuntimeGatewayRequestScope } from "./runtime-api.js";
+import { n as NostrProfileSchema } from "./config-schema-KoL8Et_9.js";
+import { a as setNostrRuntime, i as getNostrRuntime, n as nostrPlugin, o as contentToProfile, r as publishNostrProfile, t as getNostrProfileState } from "./channel-CnPQxTzj.js";
+import { z } from "zod";
+import { SimplePool, verifyEvent } from "nostr-tools";
+import { normalizeLowercaseStringOrEmpty, normalizeOptionalLowercaseString, readStringValue } from "klaw/plugin-sdk/string-coerce-runtime";
+import { readJsonBodyWithLimit, requestBodyErrorToText } from "klaw/plugin-sdk/webhook-request-guards";
+import { createFixedWindowRateLimiter } from "klaw/plugin-sdk/webhook-ingress";
+import { isBlockedHostnameOrIp } from "klaw/plugin-sdk/ssrf-runtime";
+//#region extensions/nostr/src/nostr-profile-url-safety.ts
+function validateUrlSafety(urlStr) {
+	try {
+		const url = new URL(urlStr);
+		if (url.protocol !== "https:") return {
+			ok: false,
+			error: "URL must use https:// protocol"
+		};
+		if (isBlockedHostnameOrIp(url.hostname.trim().toLowerCase())) return {
+			ok: false,
+			error: "URL must not point to private/internal addresses"
+		};
+		return { ok: true };
+	} catch {
+		return {
+			ok: false,
+			error: "Invalid URL format"
+		};
+	}
+}
+//#endregion
+//#region extensions/nostr/src/nostr-profile-import.ts
+/**
+* Nostr Profile Import
+*
+* Fetches and verifies kind:0 profile events from relays.
+* Used to import existing profiles before editing.
+*/
+const DEFAULT_TIMEOUT_MS = 5e3;
+/**
+* Sanitize URLs in an imported profile to prevent SSRF attacks.
+* Removes any URLs that don't pass SSRF validation.
+*/
+function sanitizeProfileUrls(profile) {
+	const result = { ...profile };
+	for (const field of [
+		"picture",
+		"banner",
+		"website"
+	]) {
+		const value = result[field];
+		if (value && typeof value === "string") {
+			if (!validateUrlSafety(value).ok) delete result[field];
+		}
+	}
+	return result;
+}
+/**
+* Fetch the latest kind:0 profile event for a pubkey from relays.
+*
+* - Queries all relays in parallel
+* - Takes the event with the highest created_at
+* - Verifies the event signature
+* - Parses and returns the profile
+*/
+async function importProfileFromRelays(opts) {
+	const { pubkey, relays, timeoutMs = DEFAULT_TIMEOUT_MS } = opts;
+	if (!pubkey || !/^[0-9a-fA-F]{64}$/.test(pubkey)) return {
+		ok: false,
+		error: "Invalid pubkey format (must be 64 hex characters)",
+		relaysQueried: []
+	};
+	if (relays.length === 0) return {
+		ok: false,
+		error: "No relays configured",
+		relaysQueried: []
+	};
+	const pool = new SimplePool();
+	const relaysQueried = [];
+	try {
+		const events = [];
+		const timeoutPromise = new Promise((resolve) => {
+			setTimeout(resolve, timeoutMs);
+		});
+		const subscriptionPromise = new Promise((resolve) => {
+			let completed = 0;
+			for (const relay of relays) {
+				relaysQueried.push(relay);
+				const sub = pool.subscribeMany([relay], [{
+					kinds: [0],
+					authors: [pubkey],
+					limit: 1
+				}], {
+					onevent(event) {
+						events.push({
+							event,
+							relay
+						});
+					},
+					oneose() {
+						completed++;
+						if (completed >= relays.length) resolve();
+					},
+					onclose() {
+						completed++;
+						if (completed >= relays.length) resolve();
+					}
+				});
+				setTimeout(() => {
+					sub.close();
+				}, timeoutMs);
+			}
+		});
+		await Promise.race([subscriptionPromise, timeoutPromise]);
+		if (events.length === 0) return {
+			ok: false,
+			error: "No profile found on any relay",
+			relaysQueried
+		};
+		let bestEvent = null;
+		for (const item of events) if (!bestEvent || item.event.created_at > bestEvent.event.created_at) bestEvent = item;
+		if (!bestEvent) return {
+			ok: false,
+			error: "No valid profile event found",
+			relaysQueried
+		};
+		if (!verifyEvent(bestEvent.event)) return {
+			ok: false,
+			error: "Profile event has invalid signature",
+			relaysQueried,
+			sourceRelay: bestEvent.relay
+		};
+		let content;
+		try {
+			content = JSON.parse(bestEvent.event.content);
+		} catch {
+			return {
+				ok: false,
+				error: "Profile event has invalid JSON content",
+				relaysQueried,
+				sourceRelay: bestEvent.relay
+			};
+		}
+		return {
+			ok: true,
+			profile: sanitizeProfileUrls(contentToProfile(content)),
+			event: {
+				id: bestEvent.event.id,
+				pubkey: bestEvent.event.pubkey,
+				created_at: bestEvent.event.created_at
+			},
+			relaysQueried,
+			sourceRelay: bestEvent.relay
+		};
+	} finally {
+		pool.close(relays);
+	}
+}
+/**
+* Merge imported profile with local profile.
+*
+* Strategy:
+* - For each field, prefer local if set, otherwise use imported
+* - This preserves user customizations while filling in missing data
+*/
+function mergeProfiles(local, imported) {
+	if (!imported) return local ?? {};
+	if (!local) return imported;
+	return {
+		name: local.name ?? imported.name,
+		displayName: local.displayName ?? imported.displayName,
+		about: local.about ?? imported.about,
+		picture: local.picture ?? imported.picture,
+		banner: local.banner ?? imported.banner,
+		website: local.website ?? imported.website,
+		nip05: local.nip05 ?? imported.nip05,
+		lud16: local.lud16 ?? imported.lud16
+	};
+}
+//#endregion
+//#region extensions/nostr/src/nostr-profile-http.ts
+const profileRateLimiter = createFixedWindowRateLimiter({
+	windowMs: 6e4,
+	maxRequests: 5,
+	maxTrackedKeys: 2048
+});
+function checkRateLimit(accountId) {
+	return !profileRateLimiter.isRateLimited(accountId);
+}
+const publishLocks = /* @__PURE__ */ new Map();
+async function withPublishLock(accountId, fn) {
+	const prev = publishLocks.get(accountId) ?? Promise.resolve();
+	let resolve;
+	const next = new Promise((r) => {
+		resolve = r;
+	});
+	publishLocks.set(accountId, next);
+	await prev.catch(() => {});
+	try {
+		return await fn();
+	} finally {
+		resolve();
+		if (publishLocks.get(accountId) === next) publishLocks.delete(accountId);
+	}
+}
+const nip05FormatSchema = z.string().regex(/^[a-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,}$/i, "Invalid NIP-05 format (user@domain.com)").optional();
+const lud16FormatSchema = z.string().regex(/^[a-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,}$/i, "Invalid Lightning address format").optional();
+const ProfileUpdateSchema = NostrProfileSchema.extend({
+	nip05: nip05FormatSchema,
+	lud16: lud16FormatSchema
+});
+const PROFILE_MUTATION_SCOPE = "operator.admin";
+function sendJson(res, status, body) {
+	res.statusCode = status;
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	res.end(JSON.stringify(body));
+}
+async function readJsonBody(req, maxBytes = 64 * 1024, timeoutMs = 3e4) {
+	const result = await readJsonBodyWithLimit(req, {
+		maxBytes,
+		timeoutMs,
+		emptyObjectOnEmpty: true
+	});
+	if (result.ok) return result.value;
+	if (result.code === "PAYLOAD_TOO_LARGE") throw new Error("Request body too large");
+	if (result.code === "REQUEST_BODY_TIMEOUT") throw new Error(requestBodyErrorToText("REQUEST_BODY_TIMEOUT"));
+	if (result.code === "CONNECTION_CLOSED") throw new Error(requestBodyErrorToText("CONNECTION_CLOSED"));
+	throw new Error(result.code === "INVALID_JSON" ? "Invalid JSON" : result.error);
+}
+function parseAccountIdFromPath(pathname) {
+	return pathname.match(/^\/api\/channels\/nostr\/([^/]+)\/profile/)?.[1] ?? null;
+}
+function isLoopbackRemoteAddress(remoteAddress) {
+	if (!remoteAddress) return false;
+	const ipLower = normalizeLowercaseStringOrEmpty(remoteAddress).replace(/^\[|\]$/g, "");
+	if (ipLower === "::1") return true;
+	if (ipLower === "127.0.0.1" || ipLower.startsWith("127.")) return true;
+	const v4Mapped = ipLower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+	if (v4Mapped) return isLoopbackRemoteAddress(v4Mapped[1]);
+	return false;
+}
+function isLoopbackOriginLike(value) {
+	try {
+		const hostname = normalizeLowercaseStringOrEmpty(new URL(value).hostname);
+		return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+	} catch {
+		return false;
+	}
+}
+function firstHeaderValue(value) {
+	if (Array.isArray(value)) return value[0];
+	return readStringValue(value);
+}
+function normalizeIpCandidate(raw) {
+	const unquoted = raw.trim().replace(/^"|"$/g, "");
+	const bracketedWithOptionalPort = unquoted.match(/^\[([^[\]]+)\](?::\d+)?$/);
+	if (bracketedWithOptionalPort) return bracketedWithOptionalPort[1] ?? "";
+	const ipv4WithPort = unquoted.match(/^(\d+\.\d+\.\d+\.\d+):\d+$/);
+	if (ipv4WithPort) return ipv4WithPort[1] ?? "";
+	return unquoted;
+}
+function hasNonLoopbackForwardedClient(req) {
+	const forwardedFor = firstHeaderValue(req.headers["x-forwarded-for"]);
+	if (forwardedFor) for (const hop of forwardedFor.split(",")) {
+		const candidate = normalizeIpCandidate(hop);
+		if (!candidate) continue;
+		if (!isLoopbackRemoteAddress(candidate)) return true;
+	}
+	const realIp = firstHeaderValue(req.headers["x-real-ip"]);
+	if (realIp) {
+		const candidate = normalizeIpCandidate(realIp);
+		if (candidate && !isLoopbackRemoteAddress(candidate)) return true;
+	}
+	return false;
+}
+function enforceLoopbackMutationGuards(ctx, req, res) {
+	const remoteAddress = req.socket.remoteAddress;
+	if (!isLoopbackRemoteAddress(remoteAddress)) {
+		ctx.log?.warn?.(`Rejected mutation from non-loopback remoteAddress=${String(remoteAddress)}`);
+		sendJson(res, 403, {
+			ok: false,
+			error: "Forbidden"
+		});
+		return false;
+	}
+	if (hasNonLoopbackForwardedClient(req)) {
+		ctx.log?.warn?.("Rejected mutation with non-loopback forwarded client headers");
+		sendJson(res, 403, {
+			ok: false,
+			error: "Forbidden"
+		});
+		return false;
+	}
+	if (normalizeOptionalLowercaseString(firstHeaderValue(req.headers["sec-fetch-site"])) === "cross-site") {
+		ctx.log?.warn?.("Rejected mutation with cross-site sec-fetch-site header");
+		sendJson(res, 403, {
+			ok: false,
+			error: "Forbidden"
+		});
+		return false;
+	}
+	const origin = firstHeaderValue(req.headers.origin);
+	if (typeof origin === "string" && !isLoopbackOriginLike(origin)) {
+		ctx.log?.warn?.(`Rejected mutation with non-loopback origin=${origin}`);
+		sendJson(res, 403, {
+			ok: false,
+			error: "Forbidden"
+		});
+		return false;
+	}
+	const referer = firstHeaderValue(req.headers.referer ?? req.headers.referrer);
+	if (typeof referer === "string" && !isLoopbackOriginLike(referer)) {
+		ctx.log?.warn?.(`Rejected mutation with non-loopback referer=${referer}`);
+		sendJson(res, 403, {
+			ok: false,
+			error: "Forbidden"
+		});
+		return false;
+	}
+	return true;
+}
+function enforceGatewayMutationScope(ctx, accountId, res) {
+	const runtimeScopes = getPluginRuntimeGatewayRequestScope()?.client?.connect?.scopes;
+	if ((Array.isArray(runtimeScopes) ? runtimeScopes : []).includes(PROFILE_MUTATION_SCOPE)) return true;
+	ctx.log?.warn?.(`[${accountId}] Rejected profile mutation missing ${PROFILE_MUTATION_SCOPE}`);
+	sendJson(res, 403, {
+		ok: false,
+		error: `missing scope: ${PROFILE_MUTATION_SCOPE}`
+	});
+	return false;
+}
+function createNostrProfileHttpHandler(ctx) {
+	return async (req, res) => {
+		const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+		if (!url.pathname.startsWith("/api/channels/nostr/")) return false;
+		const accountId = parseAccountIdFromPath(url.pathname);
+		if (!accountId) return false;
+		const isImport = url.pathname.endsWith("/profile/import");
+		if (!(url.pathname.endsWith("/profile") || isImport)) return false;
+		try {
+			if (req.method === "GET" && !isImport) return await handleGetProfile(accountId, ctx, res);
+			if (req.method === "PUT" && !isImport) return await handleUpdateProfile(accountId, ctx, req, res);
+			if (req.method === "POST" && isImport) return await handleImportProfile(accountId, ctx, req, res);
+			sendJson(res, 405, {
+				ok: false,
+				error: "Method not allowed"
+			});
+			return true;
+		} catch (err) {
+			ctx.log?.error(`Profile HTTP error: ${String(err)}`);
+			sendJson(res, 500, {
+				ok: false,
+				error: "Internal server error"
+			});
+			return true;
+		}
+	};
+}
+async function handleGetProfile(accountId, ctx, res) {
+	const configProfile = ctx.getConfigProfile(accountId);
+	const publishState = await getNostrProfileState(accountId);
+	sendJson(res, 200, {
+		ok: true,
+		profile: configProfile ?? null,
+		publishState: publishState ?? null
+	});
+	return true;
+}
+async function handleUpdateProfile(accountId, ctx, req, res) {
+	if (!enforceGatewayMutationScope(ctx, accountId, res)) return true;
+	if (!enforceLoopbackMutationGuards(ctx, req, res)) return true;
+	if (!checkRateLimit(accountId)) {
+		sendJson(res, 429, {
+			ok: false,
+			error: "Rate limit exceeded (5 requests/minute)"
+		});
+		return true;
+	}
+	let body;
+	try {
+		body = await readJsonBody(req);
+	} catch (err) {
+		sendJson(res, 400, {
+			ok: false,
+			error: String(err)
+		});
+		return true;
+	}
+	const parseResult = ProfileUpdateSchema.safeParse(body);
+	if (!parseResult.success) {
+		sendJson(res, 400, {
+			ok: false,
+			error: "Validation failed",
+			details: parseResult.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`)
+		});
+		return true;
+	}
+	const profile = parseResult.data;
+	if (profile.picture) {
+		const pictureCheck = validateUrlSafety(profile.picture);
+		if (!pictureCheck.ok) {
+			sendJson(res, 400, {
+				ok: false,
+				error: `picture: ${pictureCheck.error}`
+			});
+			return true;
+		}
+	}
+	if (profile.banner) {
+		const bannerCheck = validateUrlSafety(profile.banner);
+		if (!bannerCheck.ok) {
+			sendJson(res, 400, {
+				ok: false,
+				error: `banner: ${bannerCheck.error}`
+			});
+			return true;
+		}
+	}
+	if (profile.website) {
+		const websiteCheck = validateUrlSafety(profile.website);
+		if (!websiteCheck.ok) {
+			sendJson(res, 400, {
+				ok: false,
+				error: `website: ${websiteCheck.error}`
+			});
+			return true;
+		}
+	}
+	const mergedProfile = {
+		...ctx.getConfigProfile(accountId) ?? {},
+		...profile
+	};
+	try {
+		const result = await withPublishLock(accountId, async () => {
+			return await publishNostrProfile(accountId, mergedProfile);
+		});
+		if (result.successes.length > 0) {
+			await ctx.updateConfigProfile(accountId, mergedProfile);
+			ctx.log?.info(`[${accountId}] Profile published to ${result.successes.length} relay(s)`);
+		} else ctx.log?.warn(`[${accountId}] Profile publish failed on all relays`);
+		sendJson(res, 200, {
+			ok: true,
+			eventId: result.eventId,
+			createdAt: result.createdAt,
+			successes: result.successes,
+			failures: result.failures,
+			persisted: result.successes.length > 0
+		});
+	} catch (err) {
+		ctx.log?.error(`[${accountId}] Profile publish error: ${String(err)}`);
+		sendJson(res, 500, {
+			ok: false,
+			error: `Publish failed: ${String(err)}`
+		});
+	}
+	return true;
+}
+async function handleImportProfile(accountId, ctx, req, res) {
+	if (!enforceGatewayMutationScope(ctx, accountId, res)) return true;
+	if (!enforceLoopbackMutationGuards(ctx, req, res)) return true;
+	const accountInfo = ctx.getAccountInfo(accountId);
+	if (!accountInfo) {
+		sendJson(res, 404, {
+			ok: false,
+			error: `Account not found: ${accountId}`
+		});
+		return true;
+	}
+	const { pubkey, relays } = accountInfo;
+	if (!pubkey) {
+		sendJson(res, 400, {
+			ok: false,
+			error: "Account has no public key configured"
+		});
+		return true;
+	}
+	let autoMerge = false;
+	try {
+		const body = await readJsonBody(req);
+		if (typeof body === "object" && body !== null) autoMerge = body.autoMerge === true;
+	} catch {}
+	ctx.log?.info(`[${accountId}] Importing profile for ${pubkey.slice(0, 8)}...`);
+	const result = await importProfileFromRelays({
+		pubkey,
+		relays,
+		timeoutMs: 1e4
+	});
+	if (!result.ok) {
+		sendJson(res, 200, {
+			ok: false,
+			error: result.error,
+			relaysQueried: result.relaysQueried
+		});
+		return true;
+	}
+	if (autoMerge && result.profile) {
+		const merged = mergeProfiles(ctx.getConfigProfile(accountId), result.profile);
+		await ctx.updateConfigProfile(accountId, merged);
+		ctx.log?.info(`[${accountId}] Profile imported and merged`);
+		sendJson(res, 200, {
+			ok: true,
+			imported: result.profile,
+			merged,
+			saved: true,
+			event: result.event,
+			sourceRelay: result.sourceRelay,
+			relaysQueried: result.relaysQueried
+		});
+		return true;
+	}
+	sendJson(res, 200, {
+		ok: true,
+		imported: result.profile,
+		saved: false,
+		event: result.event,
+		sourceRelay: result.sourceRelay,
+		relaysQueried: result.relaysQueried
+	});
+	return true;
+}
+//#endregion
+export { createNostrProfileHttpHandler, getNostrRuntime, getPluginRuntimeGatewayRequestScope, nostrPlugin, resolveNostrAccount, setNostrRuntime };