402-announce 1.0.0 → 1.1.1

package/README.md

@@ -6,6 +6,22 @@ Announce HTTP 402 services on Nostr for decentralised discovery. Supports both L
 
 Publishes **kind 31402** parameterised replaceable events so that AI agents (and any Nostr client) can discover paid APIs without a central registry.
 
+## How it works
+
+```mermaid
+flowchart LR
+    A[Your API] -->|"npm install<br/>402-announce"| B[402-announce]
+    B -->|"kind 31402<br/>signed event"| C[(Nostr Relays)]
+    C -->|subscribe & filter| D[402-mcp]
+    D -->|discover + pay| A
+
+    style B fill:#f59e0b,color:#000
+    style C fill:#8b5cf6,color:#fff
+    style D fill:#3b82f6,color:#fff
+```
+
+Your API publishes a service announcement to Nostr relays. AI agents (via [402-mcp](https://github.com/TheCryptoDonkey/402-mcp)) discover it, pay the invoice, and consume the API. No central registry required.
+
 ## Quick start
 
 ```bash
@@ -40,22 +56,64 @@ console.log('From pubkey:', handle.pubkey)
 handle.close()
 ```
 
+## Announce flow
+
+```mermaid
+flowchart TD
+    A[announceService config] --> B{Validate}
+    B -->|"secretKey: 64-char hex"| C[Derive pubkey]
+    B -->|"relays: wss:// URLs"| C
+    C --> D[Build kind 31402 event]
+    D --> E[Sign with secret key]
+    E --> F[Zeroise key bytes]
+    F --> G["Connect relays (parallel, 10s timeout)"]
+    G --> H{Each relay}
+    H -->|success| I[Publish event]
+    H -->|failure| J[Log warning, continue]
+    I --> K["Return { eventId, pubkey, close() }"]
+    J --> K
+```
+
 ## Event format
 
-Each announcement is a **kind 31402** parameterised replaceable event. The combination of `pubkey` + `d` tag uniquely identifies a listing -- publishing again with the same values updates the existing listing.
+Each announcement is a **kind 31402** parameterised replaceable event. The combination of `pubkey` + `d` tag uniquely identifies a listing — publishing again with the same values updates the existing listing.
+
+```mermaid
+graph TB
+    subgraph "Kind 31402 Event"
+        direction TB
+        subgraph Tags
+            D["d: jokes-api"]
+            N["name: Jokes API"]
+            U["url: https://jokes.example.com"]
+            AB["about: A joke-telling service"]
+            PMI1["pmi: bitcoin-lightning-bolt11"]
+            PMI2["pmi: bitcoin-cashu"]
+            P["price: get_joke, 1, sats"]
+            T["t: comedy"]
+        end
+        subgraph Content["Content (JSON)"]
+            CAP["capabilities: [{ name, description }]"]
+            VER["version: 1.0.0"]
+        end
+    end
+
+    style Tags fill:#1e293b,color:#e2e8f0
+    style Content fill:#1e293b,color:#e2e8f0
+```
 
 ### Tags
 
-| Tag       | Description                                  | Example                           |
-|-----------|----------------------------------------------|-----------------------------------|
-| `d`       | Unique identifier for this listing           | `jokes-api`                       |
-| `name`    | Human-readable service name                  | `Jokes API`                       |
-| `url`     | HTTP endpoint for the 402 service            | `https://jokes.example.com`       |
-| `about`   | Short description                            | `A joke-telling service`          |
-| `pmi`     | Payment method identifier (repeatable)       | `bitcoin-lightning-bolt11`        |
-| `price`   | Capability pricing (repeatable)              | `get_joke`, `1`, `sats`           |
-| `t`       | Topic tag for search/filtering (repeatable)  | `comedy`                          |
-| `picture` | Optional icon URL                            | `https://example.com/icon.png`    |
+| Tag       | Required | Description                                  | Example                           |
+|-----------|----------|----------------------------------------------|-----------------------------------|
+| `d`       | yes      | Unique identifier for this listing           | `jokes-api`                       |
+| `name`    | yes      | Human-readable service name                  | `Jokes API`                       |
+| `url`     | yes      | HTTP endpoint for the 402 service            | `https://jokes.example.com`       |
+| `about`   | yes      | Short description                            | `A joke-telling service`          |
+| `pmi`     | yes      | Payment method identifier (repeatable)       | `bitcoin-lightning-bolt11`        |
+| `price`   | yes      | Capability pricing (repeatable)              | `get_joke`, `1`, `sats`           |
+| `t`       | no       | Topic tag for search/filtering (repeatable)  | `comedy`                          |
+| `picture` | no       | Icon URL                                     | `https://example.com/icon.png`    |
 
 ### Content
 
@@ -70,10 +128,85 @@ The event content is a JSON object with optional fields:
 }
 ```
 
+## API
+
+### `announceService(config): Promise<Announcement>`
+
+High-level function that builds, signs, and publishes the event to multiple relays.
+
+**Returns** an `Announcement` handle:
+- `eventId` — the published Nostr event ID
+- `pubkey` — the Nostr pubkey derived from your secret key
+- `close()` — disconnect from all relays
+
+### `buildAnnounceEvent(secretKey, config): VerifiedEvent`
+
+Lower-level function that builds and signs the event without publishing. Useful if you manage relay connections yourself.
+
+### Config options
+
+| Field            | Type              | Required | Description                                    |
+|------------------|-------------------|----------|------------------------------------------------|
+| `secretKey`      | `string`          | yes      | 64-char hex Nostr secret key                   |
+| `relays`         | `string[]`        | yes      | Relay URLs (`wss://` or `ws://`)               |
+| `identifier`     | `string`          | yes      | Unique listing ID (Nostr `d` tag)              |
+| `name`           | `string`          | yes      | Human-readable service name                    |
+| `url`            | `string`          | yes      | HTTP endpoint for the service                  |
+| `about`          | `string`          | yes      | Short description                              |
+| `pricing`        | `PricingDef[]`    | yes      | Per-capability pricing                         |
+| `paymentMethods` | `string[]`        | yes      | Accepted payment methods                       |
+| `picture`        | `string`          | no       | Icon URL                                       |
+| `topics`         | `string[]`        | no       | Topic tags for filtering                       |
+| `capabilities`   | `CapabilityDef[]` | no       | Capability details (stored in event content)   |
+| `version`        | `string`          | no       | Service version (stored in event content)      |
+
+## How it fits together
+
+```mermaid
+flowchart LR
+    subgraph "Your Server"
+        API[Your API]
+        TB[toll-booth<br/>L402 paywall]
+        AN[402-announce]
+    end
+
+    subgraph "Nostr Network"
+        R1[(Relay 1)]
+        R2[(Relay 2)]
+    end
+
+    subgraph "AI Agent"
+        MCP[402-mcp<br/>discovery + payment]
+    end
+
+    API --> TB
+    TB -->|"protects"| API
+    AN -->|"kind 31402"| R1
+    AN -->|"kind 31402"| R2
+    R1 -->|"subscribe"| MCP
+    R2 -->|"subscribe"| MCP
+    MCP -->|"HTTP + L402 token"| TB
+
+    style TB fill:#ef4444,color:#fff
+    style AN fill:#f59e0b,color:#000
+    style MCP fill:#3b82f6,color:#fff
+```
+
+1. **[toll-booth](https://github.com/TheCryptoDonkey/toll-booth)** wraps your API with an L402 paywall
+2. **402-announce** publishes a kind 31402 event describing the service, pricing, and payment methods
+3. **[402-mcp](https://github.com/TheCryptoDonkey/402-mcp)** discovers the announcement, pays the invoice, and calls your API
+
+## Security
+
+- Secret key bytes are zeroised immediately after signing (in both `announceService` and `buildAnnounceEvent`)
+- Never log or persist the secret key — pass it in and let the library handle cleanup
+- Relay connections use a 10-second timeout to prevent hanging
+- Individual relay failures are logged as warnings but don't reject the promise
+
 ## What it does
 
 - Builds and signs kind 31402 Nostr events
-- Publishes to one or more Nostr relays
+- Publishes to one or more Nostr relays in parallel
 - Zeroises secret key bytes after use
 - Degrades gracefully when individual relays fail
 - Provides a `close()` handle for clean disconnection
@@ -81,16 +214,16 @@ The event content is a JSON object with optional fields:
 ## What it does not do
 
 - Does not run an L402 paywall (use [toll-booth](https://github.com/TheCryptoDonkey/toll-booth) for that)
-- Does not subscribe to or search for announcements (use [l402-mcp](https://github.com/TheCryptoDonkey/l402-mcp) for that)
+- Does not subscribe to or search for announcements (use [402-mcp](https://github.com/TheCryptoDonkey/402-mcp) for that)
 - Does not handle payments or token verification
 
 ## Ecosystem
 
 | Package | Purpose |
 |---------|---------|
-| [toll-booth](https://github.com/TheCryptoDonkey/toll-booth) | L402 middleware -- any API becomes a toll booth in minutes |
+| [toll-booth](https://github.com/TheCryptoDonkey/toll-booth) | L402 middleware — any API becomes a toll booth in minutes |
 | [satgate](https://github.com/TheCryptoDonkey/satsgate) | Production L402 gateway with Lightning and Cashu support |
-| [l402-mcp](https://github.com/TheCryptoDonkey/l402-mcp) | MCP server for AI agents to discover, pay, and consume L402 APIs |
+| [402-mcp](https://github.com/TheCryptoDonkey/402-mcp) | MCP server for AI agents to discover, pay, and consume 402 APIs |
 
 ## Licence
 

package/build/announce.js

@@ -1,7 +1,6 @@
-import { getPublicKey } from 'nostr-tools/pure';
 import { Relay } from 'nostr-tools/relay';
 import { buildAnnounceEvent } from './event.js';
-import { hexToBytes } from './utils.js';
+import { isPrivateHost } from './utils.js';
 /**
  * Publish a kind 31402 L402 service announcement to Nostr relays.
  *
@@ -25,21 +24,48 @@ export async function announceService(config) {
         if (!/^wss?:\/\//i.test(url)) {
             throw new Error(`Invalid relay URL: ${url} — must start with wss:// or ws://`);
         }
+        // H3: Reject private/loopback relay URLs (SSRF prevention)
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new Error(`Invalid relay URL: ${url}`);
+        }
+        if (isPrivateHost(parsed.hostname)) {
+            throw new Error(`Relay URL points to a private/loopback address: ${url}`);
+        }
+        // M4: Warn on insecure ws:// usage
+        if (url.startsWith('ws://')) {
+            console.warn(`[402-announce] Insecure WebSocket (ws://) relay: ${url} — use wss:// in production`);
+        }
     }
-    // Derive pubkey (zeroises sk bytes internally)
-    const skBytes = hexToBytes(secretKey);
-    const pubkey = getPublicKey(skBytes);
-    skBytes.fill(0);
-    // Build and sign the event
+    // Build and sign the event (H2: no redundant key decode — pubkey comes from the event)
     const event = buildAnnounceEvent(secretKey, config);
     // Connect to relays in parallel and publish
     const connectedRelays = [];
     let accepted = 0;
     const results = await Promise.allSettled(relays.map(async (url) => {
+        // H4: Track the relay reference before the race so it can be closed on timeout.
+        // Relay.connect() is started, then we race against the timeout. If the timeout
+        // fires first we close the relay once the connect promise eventually resolves,
+        // preventing the connection from leaking in the background.
+        const connectPromise = Relay.connect(url);
+        let timedOut = false;
         const relay = await Promise.race([
-            Relay.connect(url),
-            new Promise((_, reject) => setTimeout(() => reject(new Error(`Relay connection timeout: ${url}`)), 10_000)),
-        ]);
+            connectPromise,
+            new Promise((_, reject) => setTimeout(() => {
+                timedOut = true;
+                reject(new Error(`Relay connection timeout: ${url}`));
+            }, 10_000)),
+        ]).catch(async (err) => {
+            // If the timeout fired, wait for the connect promise to settle so we
+            // can close any relay that connected after the deadline.
+            if (timedOut) {
+                connectPromise.then((r) => r.close()).catch(() => { });
+            }
+            throw err;
+        });
         connectedRelays.push(relay);
         await relay.publish(event);
         accepted++;
@@ -54,7 +80,7 @@ export async function announceService(config) {
     }
     return {
         eventId: event.id,
-        pubkey,
+        pubkey: event.pubkey,
         close() {
             for (const relay of connectedRelays) {
                 try {

package/build/announce.js.map

@@ -1 +1 @@
-{"version":3,"file":"announce.js","sourceRoot":"","sources":["../src/announce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAGvC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAsB;IAC1D,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAA;IAEpC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAChE,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;IACvD,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,oCAAoC,CAAC,CAAA;QAChF,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,CAAA;IACrC,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAA;IACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAEf,2BAA2B;IAC3B,MAAM,KAAK,GAAG,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IAEnD,4CAA4C;IAC5C,MAAM,eAAe,GAAiC,EAAE,CAAA;IACxD,IAAI,QAAQ,GAAG,CAAC,CAAA;IAEhB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACvB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAC/B,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAClB,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,6BAA6B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAChF;SACF,CAAC,CAAA;QACF,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC3B,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAC1B,QAAQ,EAAE,CAAA;IACZ,CAAC,CAAC,CACH,CAAA;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC,mCAAmC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;QAClE,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAA;IAC7D,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,EAAE;QACjB,MAAM;QACN,KAAK;YACH,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;gBACpC,IAAI,CAAC;oBACH,KAAK,CAAC,KAAK,EAAE,CAAA;gBACf,CAAC;gBAAC,MAAM,CAAC;oBACP,sBAAsB;gBACxB,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"announce.js","sourceRoot":"","sources":["../src/announce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAsB;IAC1D,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAA;IAEpC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAChE,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;IACvD,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,oCAAoC,CAAC,CAAA;QAChF,CAAC;QAED,2DAA2D;QAC3D,IAAI,MAAW,CAAA;QACf,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,EAAE,CAAC,CAAA;QAC9C,CAAC;QACD,IAAI,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,mDAAmD,GAAG,EAAE,CAAC,CAAA;QAC3E,CAAC;QAED,mCAAmC;QACnC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CACV,oDAAoD,GAAG,6BAA6B,CACrF,CAAA;QACH,CAAC;IACH,CAAC;IAED,uFAAuF;IACvF,MAAM,KAAK,GAAG,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IAEnD,4CAA4C;IAC5C,MAAM,eAAe,GAAiC,EAAE,CAAA;IACxD,IAAI,QAAQ,GAAG,CAAC,CAAA;IAEhB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACvB,gFAAgF;QAChF,+EAA+E;QAC/E,+EAA+E;QAC/E,4DAA4D;QAC5D,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAEzC,IAAI,QAAQ,GAAG,KAAK,CAAA;QACpB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAC/B,cAAc;YACd,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CAAC,GAAG,EAAE;gBACd,QAAQ,GAAG,IAAI,CAAA;gBACf,MAAM,CAAC,IAAI,KAAK,CAAC,6BAA6B,GAAG,EAAE,CAAC,CAAC,CAAA;YACvD,CAAC,EAAE,MAAM,CAAC,CACX;SACF,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACrB,qEAAqE;YACrE,yDAAyD;YACzD,IAAI,QAAQ,EAAE,CAAC;gBACb,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;YACvD,CAAC;YACD,MAAM,GAAG,CAAA;QACX,CAAC,CAAC,CAAA;QAEF,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC3B,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAC1B,QAAQ,EAAE,CAAA;IACZ,CAAC,CAAC,CACH,CAAA;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC,mCAAmC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;QAClE,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAA;IAC7D,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,EAAE;QACjB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK;YACH,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;gBACpC,IAAI,CAAC;oBACH,KAAK,CAAC,KAAK,EAAE,CAAA;gBACf,CAAC;gBAAC,MAAM,CAAC;oBACP,sBAAsB;gBACxB,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/build/event.d.ts

@@ -3,7 +3,8 @@ import type { VerifiedEvent } from 'nostr-tools/pure';
 /**
  * Build and sign a kind 31402 Nostr event announcing an L402 service.
  *
- * The secret key bytes are zeroised after signing.
+ * The caller's secret key buffer is zeroed after signing. Library-internal
+ * copies made by @noble/curves are subject to GC timing.
  *
  * @param secretKeyHex - 64-character hex-encoded Nostr secret key
  * @param config - Service announcement configuration

package/build/event.js

@@ -4,7 +4,8 @@ import { hexToBytes } from './utils.js';
 /**
  * Build and sign a kind 31402 Nostr event announcing an L402 service.
  *
- * The secret key bytes are zeroised after signing.
+ * The caller's secret key buffer is zeroed after signing. Library-internal
+ * copies made by @noble/curves are subject to GC timing.
  *
  * @param secretKeyHex - 64-character hex-encoded Nostr secret key
  * @param config - Service announcement configuration
@@ -14,6 +15,29 @@ export function buildAnnounceEvent(secretKeyHex, config) {
     if (!/^[0-9a-f]{64}$/i.test(secretKeyHex)) {
         throw new Error('secretKey must be a 64-character hex string');
     }
+    // M1: Validate url field
+    if (!config.url.startsWith('http://') && !config.url.startsWith('https://')) {
+        throw new Error('config.url must start with http:// or https://');
+    }
+    // M1: Validate picture field when present
+    if (config.picture !== undefined) {
+        if (!config.picture.startsWith('http://') && !config.picture.startsWith('https://')) {
+            throw new Error('config.picture must start with http:// or https://');
+        }
+    }
+    // M2: Validate identifier is non-empty and within length limit
+    if (config.identifier.trim().length === 0) {
+        throw new Error('config.identifier must not be empty or whitespace-only');
+    }
+    if (config.identifier.length > 256) {
+        throw new Error('config.identifier must not exceed 256 characters');
+    }
+    // M3: Validate all pricing entries
+    for (const p of config.pricing) {
+        if (!Number.isFinite(p.price) || p.price < 0) {
+            throw new Error(`config.pricing price must be a finite non-negative number, got: ${p.price}`);
+        }
+    }
     const sk = hexToBytes(secretKeyHex);
     try {
         const tags = [

package/build/event.js.map

@@ -1 +1 @@
-{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAIvC;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAAoB,EACpB,MAAsC;IAEtC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAChE,CAAC;IAED,MAAM,EAAE,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IACnC,IAAI,CAAC;QACH,MAAM,IAAI,GAAe;YACvB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;YACxB,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC;YACrB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;YACnB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;SACxB,CAAA;QAED,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;QACxC,CAAC;QAED,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YACvC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAA;QACxB,CAAC;QAED,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;QACjE,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;YACzB,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAA4B,EAAE,CAAA;QAC9C,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACxB,UAAU,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAA;QAC/C,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;QACrC,CAAC;QAED,MAAM,KAAK,GAAG,aAAa,CACzB;YACE,IAAI,EAAE,kBAAkB;YACxB,IAAI;YACJ,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;YACnC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;SAC1C,EACD,EAAE,CACH,CAAA;QAED,OAAO,KAAK,CAAA;IACd,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -11,6 +11,10 @@ export interface PricingDef {
 export interface CapabilityDef {
     name: string;
     description: string;
+    /** Optional JSON Schema describing the capability's input parameters. */
+    schema?: unknown;
+    /** Optional JSON Schema describing the capability's output. */
+    outputSchema?: unknown;
 }
 /** Configuration for announceService(). */
 export interface AnnounceConfig {

package/build/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAsDA,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAA"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0DA,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAA"}

package/build/utils.d.ts

@@ -1 +1,17 @@
 export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Returns true if the hostname resolves to a loopback, link-local, or
+ * RFC-1918 private address. Used to prevent SSRF via relay URLs.
+ *
+ * Rejects:
+ *   - localhost
+ *   - 127.0.0.0/8 (IPv4 loopback)
+ *   - ::1 (IPv6 loopback)
+ *   - 0.0.0.0
+ *   - 169.254.0.0/16 (IPv4 link-local)
+ *   - fe80::/10 (IPv6 link-local)
+ *   - 10.0.0.0/8 (RFC-1918)
+ *   - 172.16.0.0/12 (RFC-1918)
+ *   - 192.168.0.0/16 (RFC-1918)
+ */
+export declare function isPrivateHost(hostname: string): boolean;

package/build/utils.js

@@ -5,4 +5,50 @@ export function hexToBytes(hex) {
     }
     return bytes;
 }
+/**
+ * Returns true if the hostname resolves to a loopback, link-local, or
+ * RFC-1918 private address. Used to prevent SSRF via relay URLs.
+ *
+ * Rejects:
+ *   - localhost
+ *   - 127.0.0.0/8 (IPv4 loopback)
+ *   - ::1 (IPv6 loopback)
+ *   - 0.0.0.0
+ *   - 169.254.0.0/16 (IPv4 link-local)
+ *   - fe80::/10 (IPv6 link-local)
+ *   - 10.0.0.0/8 (RFC-1918)
+ *   - 172.16.0.0/12 (RFC-1918)
+ *   - 192.168.0.0/16 (RFC-1918)
+ */
+export function isPrivateHost(hostname) {
+    const h = hostname.toLowerCase();
+    // Reject literal "localhost"
+    if (h === 'localhost')
+        return true;
+    // IPv6 loopback ::1 (may appear as [::1] in URLs — strip brackets)
+    const stripped = h.replace(/^\[|\]$/g, '');
+    if (stripped === '::1')
+        return true;
+    // IPv6 link-local fe80::/10 (prefix fe80 through febf)
+    if (/^fe[89ab][0-9a-f]:/i.test(stripped))
+        return true;
+    // Parse dotted-decimal IPv4
+    const ipv4 = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (ipv4) {
+        const [, a, b, c] = ipv4.map(Number);
+        if (a === 127)
+            return true; // 127.0.0.0/8
+        if (a === 0 && b === 0 && c === 0)
+            return true; // 0.0.0.0
+        if (a === 10)
+            return true; // 10.0.0.0/8
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // 172.16.0.0/12
+        if (a === 192 && b === 168)
+            return true; // 192.168.0.0/16
+        if (a === 169 && b === 254)
+            return true; // 169.254.0.0/16
+    }
+    return false;
+}
 //# sourceMappingURL=utils.js.map

package/build/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACtD,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACtD,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAA;IAEhC,6BAA6B;IAC7B,IAAI,CAAC,KAAK,WAAW;QAAE,OAAO,IAAI,CAAA;IAElC,mEAAmE;IACnE,MAAM,QAAQ,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;IAC1C,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,IAAI,CAAA;IAEnC,uDAAuD;IACvD,IAAI,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAA;IAErD,4BAA4B;IAC5B,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAA;IACpE,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACpC,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,IAAI,CAAA,CAAsC,cAAc;QAC9E,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA,CAAkB,UAAU;QAC1E,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO,IAAI,CAAA,CAAuC,aAAa;QAC7E,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;YAAE,OAAO,IAAI,CAAA,CAAe,gBAAgB;QAC/E,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,IAAI,CAAA,CAAyB,iBAAiB;QACjF,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,IAAI,CAAA,CAAyB,iBAAiB;IACnF,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC"}

package/llms-full.txt

@@ -0,0 +1,222 @@
+# 402-announce — Full Reference
+
+> Announce HTTP 402 services on Nostr for decentralised discovery.
+> Supports both L402 and x402 payment protocols.
+> Source: https://github.com/TheCryptoDonkey/402-announce
+
+## Overview
+
+402-announce is a TypeScript library that publishes kind 31402 Nostr events describing paid HTTP APIs. These events enable decentralised service discovery — AI agents and Nostr clients can find, evaluate, and pay for APIs without a central registry.
+
+The library handles event construction, signing, and multi-relay publication. Secret key material is zeroised after use.
+
+## Installation
+
+```bash
+npm install 402-announce
+```
+
+Requires Node.js >= 18. ESM only. Single runtime dependency: nostr-tools.
+
+## API Reference
+
+### announceService(config: AnnounceConfig): Promise<Announcement>
+
+High-level function: builds a kind 31402 event, signs it, connects to relays in parallel, and publishes.
+
+**Parameters:**
+
+AnnounceConfig:
+  - secretKey (string, required): 64-character hex-encoded Nostr secret key
+  - relays (string[], required): Relay URLs (must start with wss:// or ws://)
+  - identifier (string, required): Unique listing ID, used as the Nostr `d` tag. Same pubkey + identifier = same listing.
+  - name (string, required): Human-readable service name
+  - url (string, required): HTTP endpoint where the 402 service is accessible
+  - about (string, required): Short description of the service
+  - pricing (PricingDef[], required): Per-capability pricing. Each entry: { capability, price, currency }
+  - paymentMethods (string[], required): Accepted payment method identifiers
+  - picture (string, optional): Icon URL
+  - topics (string[], optional): Topic tags for search/filtering
+  - capabilities (CapabilityDef[], optional): Capability details stored in event content
+  - version (string, optional): Service version stored in event content
+
+PricingDef:
+  - capability (string): Capability name (e.g. "get_joke", "chat", "inference")
+  - price (number): Price amount
+  - currency (string): Currency unit (e.g. "sats", "USD")
+
+CapabilityDef:
+  - name (string): Capability name
+  - description (string): Human-readable description
+
+**Returns** Announcement:
+  - eventId (string): The published Nostr event ID
+  - pubkey (string): Nostr pubkey derived from the secret key
+  - close(): void — Disconnect from all connected relays
+
+**Behaviour:**
+  - Validates secretKey (must be 64-char hex) and relay URLs (must be wss:// or ws://)
+  - Connects to all relays in parallel with a 10-second timeout per relay
+  - Individual relay failures are logged as warnings but do not reject the promise
+  - If no relay accepts the event, a warning is emitted (but the promise still resolves)
+  - Secret key bytes are zeroised after signing
+
+**Throws:**
+  - If secretKey is not a 64-character hex string
+  - If relays array is empty
+  - If any relay URL does not start with wss:// or ws://
+
+### buildAnnounceEvent(secretKeyHex: string, config: Omit<AnnounceConfig, 'relays'>): VerifiedEvent
+
+Lower-level function: builds and signs the kind 31402 event without publishing. Use this if you manage relay connections yourself.
+
+**Returns** a nostr-tools VerifiedEvent ready for relay publication.
+
+Secret key bytes are zeroised after signing (via try/finally).
+
+### Constants
+
+- L402_ANNOUNCE_KIND = 31402 — The Nostr event kind for service announcements
+
+### Exported types
+
+- AnnounceConfig — Configuration for announceService()
+- Announcement — Handle returned by announceService()
+- PricingDef — Pricing for a specific capability
+- CapabilityDef — Capability with description
+
+## Event Format Specification
+
+### Kind 31402 — Parameterised Replaceable Event
+
+A kind 31402 event is a Nostr parameterised replaceable event (NIP-33). This means:
+- The combination of pubkey + kind + d-tag uniquely identifies a listing
+- Publishing a new event with the same pubkey + kind + d-tag replaces the previous one
+- This allows services to update their announcements (e.g. change pricing) without creating duplicates
+
+### Tag structure
+
+Required tags:
+  ["d", "<identifier>"]           — Unique listing identifier
+  ["name", "<service name>"]      — Human-readable name
+  ["url", "<endpoint URL>"]       — HTTP endpoint
+  ["about", "<description>"]      — Short description
+  ["pmi", "<payment method>"]     — Payment method identifier (one tag per method)
+  ["price", "<capability>", "<amount>", "<currency>"]  — Pricing (one tag per capability)
+
+Optional tags:
+  ["t", "<topic>"]                — Topic tag for filtering (one tag per topic)
+  ["picture", "<icon URL>"]       — Service icon
+
+### Content field
+
+JSON object with optional fields:
+{
+  "capabilities": [
+    { "name": "get_joke", "description": "Returns a random joke" }
+  ],
+  "version": "1.0.0"
+}
+
+### Example event
+
+{
+  "kind": 31402,
+  "pubkey": "ab1234...ef5678",
+  "created_at": 1710000000,
+  "tags": [
+    ["d", "jokes-api"],
+    ["name", "Jokes API"],
+    ["url", "https://jokes.example.com"],
+    ["about", "A joke-telling service behind an L402 paywall"],
+    ["pmi", "bitcoin-lightning-bolt11"],
+    ["pmi", "bitcoin-cashu"],
+    ["price", "get_joke", "1", "sats"],
+    ["t", "comedy"],
+    ["t", "ai"]
+  ],
+  "content": "{\"capabilities\":[{\"name\":\"get_joke\",\"description\":\"Returns a random joke\"}],\"version\":\"1.0.0\"}",
+  "id": "...",
+  "sig": "..."
+}
+
+## Payment Method Identifiers
+
+Known payment method identifiers for the `pmi` tag and `paymentMethods` config:
+
+  bitcoin-lightning-bolt11   — Lightning Network BOLT-11 invoices
+  bitcoin-cashu              — Cashu ecash tokens
+  bitcoin-onchain            — On-chain Bitcoin
+  x402-evm                   — x402 protocol on EVM chains
+  x402-solana                — x402 protocol on Solana
+
+## Integration Patterns
+
+### Producer side: toll-booth + 402-announce
+
+A typical server setup protects an API with toll-booth and announces it with 402-announce:
+
+```typescript
+import { createTollBooth } from 'toll-booth'
+import { announceService } from '402-announce'
+
+// 1. Protect your API with a paywall
+const booth = createTollBooth({ /* payment config */ })
+app.use('/api', booth.middleware)
+
+// 2. Announce it on Nostr
+const handle = await announceService({
+  secretKey: process.env.NOSTR_SECRET_KEY,
+  relays: ['wss://relay.damus.io'],
+  identifier: 'my-api',
+  name: 'My API',
+  url: 'https://api.example.com',
+  about: 'A paid API service',
+  pricing: [{ capability: 'query', price: 10, currency: 'sats' }],
+  paymentMethods: ['bitcoin-lightning-bolt11'],
+})
+
+// 3. Clean up on shutdown
+process.on('SIGTERM', () => handle.close())
+```
+
+### Consumer side: 402-mcp
+
+AI agents use 402-mcp to discover and consume announced services:
+
+1. 402-mcp subscribes to kind 31402 events on configured relays
+2. Agent searches for services by topic, capability, or payment method
+3. 402-mcp handles L402 payment negotiation automatically
+4. Agent receives the API response
+
+The agent never needs to know about Nostr or payment protocols — 402-mcp abstracts it all.
+
+### Updating a listing
+
+Because kind 31402 is a parameterised replaceable event, calling announceService() again with the same identifier and pubkey replaces the previous listing. Use this to update pricing, add capabilities, or change the endpoint URL.
+
+## Security Considerations
+
+- **Key zeroisation**: Secret key bytes (Uint8Array) are filled with zeros immediately after signing, in both announceService() and buildAnnounceEvent(). This limits the window during which key material exists in memory.
+- **Key handling**: Pass the secret key as a hex string. The library converts to bytes, signs, and zeroises. Never log or persist the key yourself.
+- **Relay trust**: Relays are untrusted infrastructure. Events are cryptographically signed — relay operators cannot forge announcements. However, relays can choose not to store or serve your events.
+- **Connection timeouts**: Relay connections time out after 10 seconds to prevent indefinite hangs.
+- **Graceful degradation**: If some relays fail, the event is still published to the others. A warning is emitted only if no relay accepts the event.
+
+## Error Handling
+
+The library throws synchronously for invalid configuration:
+- secretKey not 64-char hex → Error
+- Empty relays array → Error
+- Invalid relay URL (not wss:// or ws://) → Error
+
+Relay-level failures during publication are handled gracefully:
+- Connection timeouts → warning logged, other relays still tried
+- Publish rejections → warning logged, other relays still tried
+- All relays fail → warning logged, promise resolves with eventId from the signed event
+
+## Source
+
+Repository: https://github.com/TheCryptoDonkey/402-announce
+Licence: MIT
+Runtime dependency: nostr-tools

package/llms.txt

@@ -0,0 +1,36 @@
+# 402-announce
+
+> Announce HTTP 402 services on Nostr for decentralised discovery
+
+## What it does
+
+402-announce publishes kind 31402 parameterised replaceable Nostr events that describe paid HTTP APIs. AI agents and Nostr clients discover these announcements to find services they can pay for and consume — no central registry needed.
+
+## Key concepts
+
+- **Kind 31402**: Nostr event kind for L402/x402 service announcements. Parameterised replaceable — same pubkey + identifier updates the existing listing.
+- **Payment methods**: Services declare accepted payment methods via `pmi` tags (e.g. `bitcoin-lightning-bolt11`, `bitcoin-cashu`).
+- **Pricing**: Per-capability pricing via `price` tags (capability name, amount, currency).
+- **Decentralised discovery**: Events are published to standard Nostr relays. Any client can subscribe and filter.
+
+## API surface
+
+Two exports:
+
+- `announceService(config)` — build, sign, and publish to relays. Returns `{ eventId, pubkey, close() }`.
+- `buildAnnounceEvent(secretKey, config)` — build and sign without publishing. Returns a `VerifiedEvent`.
+
+## Ecosystem position
+
+```
+toll-booth (paywall) → protects your API
+402-announce (this)  → tells the world your API exists
+402-mcp (discovery)  → AI agents find, pay, and consume your API
+```
+
+## Details
+
+For full API reference, event format, integration patterns, and examples see:
+- llms-full.txt (comprehensive reference)
+- README.md (human-oriented documentation with diagrams)
+- Source: https://github.com/TheCryptoDonkey/402-announce

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "402-announce",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "type": "module",
   "description": "Announce HTTP 402 services (L402 and x402) on Nostr for decentralised discovery. Kind 31402 parameterised replaceable events.",
   "license": "MIT",
@@ -15,7 +15,9 @@
   "files": [
     "build",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "scripts": {
     "build": "tsc",