@abndnce/pulsar-client 0.0.9 → 0.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -23,12 +23,21 @@ declare function connectDirect(host: string, port: number): Promise<PulsarClient
 //#endregion
 //#region lib/connection/nostr.d.ts
 /**
- * Connect via a Nostr relay (placeholder).
+ * Establish a Pulsar tunnel via Nostr relay signaling.
  *
- * In the future, this will implement a Nostr-based signaling layer for
- * establishing peer connections through a Nostr relay.
+ * 1. Connects to a Nostr relay (tries nostr.data.haus first,
+ *    then kotukonostr.onrender.com)
+ * 2. Looks up the tunnel's discovery event (Kind 38000, d="pulsar-tunnel").
+ *    If `tunnelCode` is given (e.g. "a3f2"), filters to the tunnel
+ *    whose pubkey begins with those 4 hex characters.
+ * 3. Generates an ephemeral client keypair
+ * 4. Creates a WebRTC offer
+ * 5. Encrypts the offer and sends via a Kind 28000 ephemeral event
+ * 6. Waits for the encrypted answer
+ * 7. Sets the answer as remote description
+ * 8. Returns the connected PulsarClientConnection
  */
-declare function connectNostr(_relay: string, _pubkey: string): Promise<PulsarClientConnection>;
+declare function connectNostr(tunnelCode?: string): Promise<PulsarClientConnection>;
 //#endregion
 //#region lib/socket-channel.d.ts
 /**
@@ -105,14 +114,13 @@ declare class DataChannelSocket extends EventTarget {
  * import { connectDirect, libcurlTransport } from '@abndnce/pulsar-client';
  * import { libcurl } from 'libcurl.js';
  *
- * const tunnel = await connectDirect('216.250.119.217', 42069);
+ * const tunnel = await connectDirect('1.2.3.4', 1234);
  * libcurl.transport = libcurlTransport(tunnel.pc);
  * libcurl.set_websocket('wss://pulsar-tunnel.local/');
  * ```
  *
  * libcurl.js calls the factory with URLs like:
  *   `wss://pulsar-tunnel.local/example.com:80`
- *   `wss://pulsar-tunnel.local/216.250.119.217:443`
  *
  * The factory parses `<hostname>:<port>` from the URL path, opens a
  * Pulsar socket data channel, and returns a WebSocket-like adapter.

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { schnorr, secp256k1 } from "@noble/curves/secp256k1";
 //#region ../core/constants.ts
 const PULSAR_UFRAG = "pulsar";
 const PULSAR_PWD = "pulsarpulsarpulsarpuls";
@@ -71,15 +72,349 @@ async function connectDirect(host, port) {
 	};
 }
 //#endregion
+//#region ../core/nostr.ts
+const NOSTR_RELAYS = ["wss://nostr.data.haus", "wss://kotukonostr.onrender.com"];
+/** Ephemeral event kind used for encrypted WebRTC signaling. */
+const SIGNALING_KIND = 28e3;
+/** Parameterized replaceable event kind used for server discovery. */
+const DISCOVERY_KIND = 38e3;
+/** The `d` tag identifier for the Pulsar tunnel discovery event. */
+const D_TAG_ID = "pulsar-tunnel";
+//#endregion
 //#region lib/connection/nostr.ts
+function hexToBytes(hex) {
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < hex.length; i += 2) bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+	return bytes;
+}
+function bytesToHex(bytes) {
+	return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function generateKeypair() {
+	const seckey = secp256k1.utils.randomPrivateKey();
+	const pubkey = secp256k1.getPublicKey(seckey, true).slice(1);
+	return {
+		seckey: bytesToHex(seckey),
+		pubkey: bytesToHex(pubkey)
+	};
+}
 /**
-* Connect via a Nostr relay (placeholder).
+* Derive a shared ECDH secret between a private key and a peer's
+* 32-byte x-only public key (Nostr format).
 *
-* In the future, this will implement a Nostr-based signaling layer for
-* establishing peer connections through a Nostr relay.
+* Schnorr public keys always have even y, so we reconstruct the
+* full point via ProjectivePoint and do scalar multiplication.
 */
-async function connectNostr(_relay, _pubkey) {
-	throw new Error("Nostr mode not yet implemented");
+function getSharedXOnly(seckey, pubkeyXOnly) {
+	const compressed = new Uint8Array(33);
+	compressed[0] = 2;
+	compressed.set(pubkeyXOnly, 1);
+	const pubPoint = secp256k1.ProjectivePoint.fromHex(compressed);
+	const scalar = bytesToBigInt(seckey);
+	const shared = pubPoint.multiply(scalar);
+	return new Uint8Array(shared.toRawBytes(false).slice(1, 33));
+}
+function bytesToBigInt(bytes) {
+	let hex = "";
+	for (const b of bytes) hex += b.toString(16).padStart(2, "0");
+	return BigInt("0x" + hex);
+}
+async function getConversationKey(seckeyBytes, pubkeyBytes) {
+	const sharedSecret = getSharedXOnly(seckeyBytes, pubkeyBytes);
+	const hkdfKey = await crypto.subtle.importKey("raw", sharedSecret, "HKDF", false, ["deriveBits", "deriveKey"]);
+	return crypto.subtle.deriveKey({
+		name: "HKDF",
+		hash: "SHA-256",
+		salt: new Uint8Array(0),
+		info: new TextEncoder().encode("nip44-v2")
+	}, hkdfKey, {
+		name: "AES-GCM",
+		length: 256
+	}, false, ["encrypt", "decrypt"]);
+}
+async function nip44Encrypt(plaintext, seckeyHex, pubkeyHex) {
+	const convKey = await getConversationKey(hexToBytes(seckeyHex), hexToBytes(pubkeyHex));
+	const nonce = crypto.getRandomValues(new Uint8Array(12));
+	const encoded = new TextEncoder().encode(plaintext);
+	const encrypted = await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv: nonce,
+		tagLength: 128
+	}, convKey, encoded);
+	const result = new Uint8Array(13 + encrypted.byteLength);
+	result[0] = 2;
+	result.set(nonce, 1);
+	result.set(new Uint8Array(encrypted), 13);
+	return btoa(String.fromCharCode(...result));
+}
+async function nip44Decrypt(ciphertextB64, seckeyHex, pubkeyHex) {
+	const convKey = await getConversationKey(hexToBytes(seckeyHex), hexToBytes(pubkeyHex));
+	const raw = Uint8Array.from(atob(ciphertextB64), (c) => c.charCodeAt(0));
+	if (raw.length < 13) throw new Error("Ciphertext too short");
+	const nonce = raw.slice(1, 13);
+	const ciphertext = raw.slice(13);
+	const decrypted = await crypto.subtle.decrypt({
+		name: "AES-GCM",
+		iv: nonce,
+		tagLength: 128
+	}, convKey, ciphertext);
+	return new TextDecoder().decode(decrypted);
+}
+function serializeEvent(ev) {
+	return JSON.stringify([
+		0,
+		ev.pubkey,
+		ev.created_at,
+		ev.kind,
+		ev.tags,
+		ev.content
+	]);
+}
+async function computeEventId(ev) {
+	const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(serializeEvent(ev)));
+	return bytesToHex(new Uint8Array(hash));
+}
+async function signEvent(ev, seckey) {
+	const id = await computeEventId(ev);
+	const sig = schnorr.sign(hexToBytes(id), seckey);
+	return {
+		...ev,
+		id,
+		sig: bytesToHex(sig)
+	};
+}
+function connectRelay(url, timeoutMs = 1e4) {
+	return new Promise((resolve, reject) => {
+		const ws = new WebSocket(url);
+		const timeout = setTimeout(() => {
+			ws.close();
+			reject(/* @__PURE__ */ new Error(`Connection to ${url} timed out`));
+		}, timeoutMs);
+		ws.addEventListener("open", () => {
+			clearTimeout(timeout);
+			resolve(ws);
+		});
+		ws.addEventListener("error", () => {
+			clearTimeout(timeout);
+			reject(/* @__PURE__ */ new Error(`Failed to connect to ${url}`));
+		});
+	});
+}
+/**
+* Try each relay in order until one connects successfully.
+*/
+async function connectToAnyRelay() {
+	const errors = [];
+	for (const relayUrl of NOSTR_RELAYS) try {
+		const ws = await connectRelay(relayUrl);
+		console.log(`[nostr] Connected to ${relayUrl}`);
+		return ws;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		errors.push(msg);
+		console.warn(`[nostr] ${relayUrl}: ${msg}`);
+	}
+	throw new Error(`Failed to connect to any Nostr relay: ${errors.join("; ")}`);
+}
+/**
+* Wait for a single event matching a filter, with timeout.
+*/
+function waitForEvent(ws, subId, filter, timeoutMs = 15e3) {
+	return new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => {
+			ws.send(JSON.stringify(["CLOSE", subId]));
+			reject(/* @__PURE__ */ new Error("Timed out waiting for Nostr event"));
+		}, timeoutMs);
+		ws.send(JSON.stringify([
+			"REQ",
+			subId,
+			filter
+		]));
+		const onMessage = (event) => {
+			let msg;
+			try {
+				msg = JSON.parse(event.data);
+			} catch {
+				return;
+			}
+			if (msg[0] === "EVENT" && msg[1] === subId) {
+				clearTimeout(timeout);
+				ws.removeEventListener("message", onMessage);
+				ws.send(JSON.stringify(["CLOSE", subId]));
+				resolve(msg[2]);
+			}
+		};
+		ws.addEventListener("message", onMessage);
+	});
+}
+const defaultIceServers = [{ urls: "stun:stun.l.google.com:19302" }, { urls: "stun:global.stun.twilio.com:3478" }];
+/**
+* Represents a Pulsar tunnel connection established via Nostr signaling.
+*/
+var NostrClientConnection = class {
+	keepalive;
+	pc;
+	_ws;
+	_seckey;
+	_serverPubkey;
+	constructor(keepalive, pc, _ws, _seckey, _serverPubkey) {
+		this.keepalive = keepalive;
+		this.pc = pc;
+		this._ws = _ws;
+		this._seckey = _seckey;
+		this._serverPubkey = _serverPubkey;
+	}
+	async close() {
+		try {
+			this.keepalive.close();
+		} catch {}
+		try {
+			this.pc.close();
+		} catch {}
+		try {
+			this._ws.close();
+		} catch {}
+	}
+};
+/**
+* Find a Pulsar server via discovery events.
+*
+* If `pubkeyPrefix` is given (4 hex chars), returns the first server
+* whose pubkey starts with that prefix. Otherwise returns any server.
+*/
+async function findServer(ws, pubkeyPrefix, timeoutMs = 15e3) {
+	return new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => {
+			ws.send(JSON.stringify(["CLOSE", "pulsar-discover"]));
+			reject(/* @__PURE__ */ new Error(pubkeyPrefix ? `No Pulsar server with tunnel code "pulsar${pubkeyPrefix}" found` : "No Pulsar server found on Nostr relay"));
+		}, timeoutMs);
+		const subId = "pulsar-discover";
+		ws.send(JSON.stringify([
+			"REQ",
+			subId,
+			{
+				kinds: [DISCOVERY_KIND],
+				"#d": [D_TAG_ID],
+				limit: 0
+			}
+		]));
+		const onMessage = (event) => {
+			let msg;
+			try {
+				msg = JSON.parse(event.data);
+			} catch {
+				return;
+			}
+			if (msg[0] === "EVENT" && msg[1] === subId) {
+				const ev = msg[2];
+				if (pubkeyPrefix) {
+					if (ev.pubkey.startsWith(pubkeyPrefix)) {
+						clearTimeout(timeout);
+						ws.removeEventListener("message", onMessage);
+						ws.send(JSON.stringify(["CLOSE", subId]));
+						resolve(ev.pubkey);
+					}
+				} else {
+					clearTimeout(timeout);
+					ws.removeEventListener("message", onMessage);
+					ws.send(JSON.stringify(["CLOSE", subId]));
+					resolve(ev.pubkey);
+				}
+			}
+		};
+		ws.addEventListener("message", onMessage);
+	});
+}
+/**
+* Establish a Pulsar tunnel via Nostr relay signaling.
+*
+* 1. Connects to a Nostr relay (tries nostr.data.haus first,
+*    then kotukonostr.onrender.com)
+* 2. Looks up the tunnel's discovery event (Kind 38000, d="pulsar-tunnel").
+*    If `tunnelCode` is given (e.g. "a3f2"), filters to the tunnel
+*    whose pubkey begins with those 4 hex characters.
+* 3. Generates an ephemeral client keypair
+* 4. Creates a WebRTC offer
+* 5. Encrypts the offer and sends via a Kind 28000 ephemeral event
+* 6. Waits for the encrypted answer
+* 7. Sets the answer as remote description
+* 8. Returns the connected PulsarClientConnection
+*/
+async function connectNostr(tunnelCode) {
+	const ws = await connectToAnyRelay();
+	const pubkeyPrefix = tunnelCode ? tunnelCode.replace(/^pulsar/, "").slice(0, 4) : void 0;
+	console.log("[nostr] Looking up Pulsar tunnel" + (pubkeyPrefix ? ` (code ${tunnelCode})` : "") + "...");
+	const serverPubkey = await findServer(ws, pubkeyPrefix);
+	console.log(`[nostr] Found server: ${serverPubkey.slice(0, 16)}...`);
+	const clientKeys = generateKeypair();
+	console.log(`[nostr] Client pubkey: ${clientKeys.pubkey.slice(0, 16)}...`);
+	const pc = new RTCPeerConnection({ iceServers: defaultIceServers });
+	const keepalive = pc.createDataChannel(KEEPALIVE_LABEL, { ordered: true });
+	keepalive.binaryType = "arraybuffer";
+	const offer = await pc.createOffer();
+	await pc.setLocalDescription(offer);
+	await new Promise((resolve) => {
+		const timeout = setTimeout(() => resolve(), 2e3);
+		const onStateChange = () => {
+			if (pc.iceGatheringState === "complete") {
+				clearTimeout(timeout);
+				resolve();
+			}
+		};
+		const onCandidate = (event) => {
+			if (!event.candidate) {
+				clearTimeout(timeout);
+				resolve();
+			}
+		};
+		pc.addEventListener("icegatheringstatechange", onStateChange);
+		pc.addEventListener("icecandidate", onCandidate);
+	});
+	const localDesc = pc.localDescription;
+	if (!localDesc) throw new Error("Failed to create local offer");
+	const offerPayload = {
+		type: "offer",
+		sdp: localDesc.sdp
+	};
+	const encryptedOffer = await nip44Encrypt(JSON.stringify(offerPayload), clientKeys.seckey, serverPubkey);
+	const offerEvent = await signEvent({
+		pubkey: clientKeys.pubkey,
+		created_at: Math.floor(Date.now() / 1e3),
+		kind: SIGNALING_KIND,
+		tags: [["p", serverPubkey]],
+		content: encryptedOffer
+	}, hexToBytes(clientKeys.seckey));
+	const answerPromise = waitForEvent(ws, "pulsar-answer", {
+		kinds: [SIGNALING_KIND],
+		"#p": [clientKeys.pubkey],
+		limit: 1
+	}, 3e4);
+	ws.send(JSON.stringify(["EVENT", offerEvent]));
+	console.log("[nostr] Sent encrypted offer, waiting for answer...");
+	const answerPlaintext = await nip44Decrypt((await answerPromise).content, clientKeys.seckey, serverPubkey);
+	const answerPayload = JSON.parse(answerPlaintext);
+	if (answerPayload.type !== "answer" || !answerPayload.sdp) throw new Error("Invalid answer from server");
+	console.log("[nostr] Received answer, connecting WebRTC...");
+	await pc.setRemoteDescription({
+		type: "answer",
+		sdp: answerPayload.sdp
+	});
+	await new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => {
+			reject(/* @__PURE__ */ new Error("WebRTC connection timed out after 30s"));
+		}, 3e4);
+		pc.addEventListener("connectionstatechange", () => {
+			if (pc.connectionState === "connected") {
+				clearTimeout(timeout);
+				resolve();
+			} else if (pc.connectionState === "failed" || pc.connectionState === "disconnected") {
+				clearTimeout(timeout);
+				reject(/* @__PURE__ */ new Error(`Connection failed: ${pc.connectionState}`));
+			}
+		});
+	});
+	console.log("[nostr] WebRTC connected!");
+	return new NostrClientConnection(keepalive, pc, ws, clientKeys.seckey, serverPubkey);
 }
 //#endregion
 //#region lib/socket-channel.ts
@@ -272,14 +607,13 @@ var DataChannelSocket = class DataChannelSocket extends EventTarget {
 * import { connectDirect, libcurlTransport } from '@abndnce/pulsar-client';
 * import { libcurl } from 'libcurl.js';
 *
-* const tunnel = await connectDirect('216.250.119.217', 42069);
+* const tunnel = await connectDirect('1.2.3.4', 1234);
 * libcurl.transport = libcurlTransport(tunnel.pc);
 * libcurl.set_websocket('wss://pulsar-tunnel.local/');
 * ```
 *
 * libcurl.js calls the factory with URLs like:
 *   `wss://pulsar-tunnel.local/example.com:80`
-*   `wss://pulsar-tunnel.local/216.250.119.217:443`
 *
 * The factory parses `<hostname>:<port>` from the URL path, opens a
 * Pulsar socket data channel, and returns a WebSocket-like adapter.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abndnce/pulsar-client",
   "type": "module",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "homepage": "https://github.com/abndnce/pulsar",
   "license": "MIT",
   "exports": {
@@ -11,6 +11,9 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@noble/curves": "^1.8.1"
+  },
   "devDependencies": {
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3"