402-announce 2.1.0 → 2.1.1

package/README.md

@@ -47,7 +47,7 @@ const handle = await announceService({
   pricing: [
     { capability: 'get_joke', price: 1, currency: 'sats' },
   ],
-  paymentMethods: ['bitcoin-lightning-bolt11', 'bitcoin-cashu', 'bitcoin-cashu-xcashu'],
+  paymentMethods: [['l402', 'lightning'], ['cashu'], ['xcashu']],
   topics: ['comedy', 'ai'],
   capabilities: [
     { name: 'get_joke', description: 'Returns a random joke' },
@@ -77,7 +77,7 @@ const handle = await announceService({
   ],
   about: 'A joke-telling service behind an L402 paywall',
   pricing: [{ capability: 'get_joke', price: 1, currency: 'sats' }],
-  paymentMethods: ['bitcoin-lightning-bolt11'],
+  paymentMethods: [['l402', 'lightning']],
   topics: ['comedy', 'ai'],
 })
 ```
@@ -162,7 +162,7 @@ Lower-level function that builds and signs the event without publishing. Useful
 | `urls`           | `string[]`        | yes      | HTTP endpoints for the service (1–10 entries, any parseable URL) |
 | `about`          | `string`          | yes      | Short description                              |
 | `pricing`        | `PricingDef[]`    | yes      | Per-capability pricing                         |
-| `paymentMethods` | `string[]`        | yes      | Accepted payment methods                       |
+| `paymentMethods` | `string[][]`      | yes      | Accepted payment methods (each entry is `[rail, ...params]`) |
 | `picture`        | `string`          | no       | Icon URL                                       |
 | `topics`         | `string[]`        | no       | Topic tags for filtering                       |
 | `capabilities`   | `CapabilityDef[]` | no       | Capability details (stored in event content)   |
@@ -200,8 +200,8 @@ graph TB
             U1["url: https://jokes.example.com"]
             U2["url: https://jokesapi.example.onion (optional)"]
             AB["about: A joke-telling service"]
-            PMI1["pmi: bitcoin-lightning-bolt11"]
-            PMI2["pmi: bitcoin-cashu"]
+            PMI1["pmi: l402, lightning"]
+            PMI2["pmi: cashu"]
             P["price: get_joke, 1, sats"]
             T["t: comedy"]
         end
@@ -223,19 +223,22 @@ graph TB
 | `name`    | yes      | Human-readable service name                  | `Jokes API`                       |
 | `url`     | yes      | HTTP endpoint (one tag per URL; repeatable)  | `https://jokes.example.com`       |
 | `about`   | yes      | Short description                            | `A joke-telling service`          |
-| `pmi`     | yes      | Payment method identifier (repeatable)       | `bitcoin-lightning-bolt11`        |
+| `pmi`     | yes      | Payment method identifier (repeatable, multi-element) | `l402`, `lightning`        |
 | `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`    |
 
-### Recognised Payment Method Identifiers
+### Recognised Payment Method Rails
 
-| Identifier | Description |
-|------------|-------------|
-| `bitcoin-lightning-bolt11` | Lightning Network (BOLT-11 invoices) |
-| `bitcoin-cashu` | Cashu ecash (generic) |
-| `bitcoin-cashu-xcashu` | Cashu ecash via NUT-24 (X-Cashu header) |
-| `x402-evm` | x402 stablecoin payments (EVM chains) |
+Each `paymentMethods` entry is an array where the first element is the rail identifier and subsequent elements are rail-specific parameters.
+
+| Rail | Example | Description |
+|------|---------|-------------|
+| `l402` | `['l402', 'lightning']` | L402 protocol (Lightning BOLT-11 invoices) |
+| `cashu` | `['cashu']` | Cashu ecash (generic) |
+| `xcashu` | `['xcashu']` | Cashu ecash via NUT-24 (X-Cashu header) |
+| `x402` | `['x402', 'base', 'usdc', '0xabc...']` | x402 stablecoin payments (chain, token, receiver address) |
+| `payment` | `['payment', 'lightning']` | IETF Payment protocol |
 
 ### Content
 
@@ -277,6 +280,23 @@ In short: same service + different network paths → one event with multiple `ur
 | [402-mcp](https://github.com/forgesworn/402-mcp) | MCP server for AI agents to discover, pay, and consume 402 APIs |
 | [Live Dashboard](https://402.pub) | See every service announcing on the network |
 
+## Part of the ForgeSworn Toolkit
+
+[ForgeSworn](https://forgesworn.dev) builds open-source cryptographic identity, payments, and coordination tools for Nostr.
+
+| Library | What it does |
+|---------|-------------|
+| [nsec-tree](https://github.com/forgesworn/nsec-tree) | Deterministic sub-identity derivation |
+| [ring-sig](https://github.com/forgesworn/ring-sig) | SAG/LSAG ring signatures on secp256k1 |
+| [range-proof](https://github.com/forgesworn/range-proof) | Pedersen commitment range proofs |
+| [canary-kit](https://github.com/forgesworn/canary-kit) | Coercion-resistant spoken verification |
+| [spoken-token](https://github.com/forgesworn/spoken-token) | Human-speakable verification tokens |
+| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 payment middleware |
+| [geohash-kit](https://github.com/forgesworn/geohash-kit) | Geohash toolkit with polygon coverage |
+| [nostr-attestations](https://github.com/forgesworn/nostr-attestations) | NIP-VA verifiable attestations |
+| [dominion](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control |
+| [nostr-veil](https://github.com/forgesworn/nostr-veil) | Privacy-preserving Web of Trust |
+
 ## Licence
 
 [MIT](./LICENSE)

package/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/forgesworn/402-announce",
+  "public_key": "pk_vdoXns3QEblb1693KnlDH"
+}

package/llms-full.txt

@@ -10,6 +10,10 @@
 
 The library handles event construction, signing, and multi-relay publication. Secret key material is zeroised after use.
 
+## Kind 31402 — disambiguation
+
+This library uses kind 31402 for **L402/x402 service announcements** (paid API discovery). This is distinct from any SARA (Simple Autonomous Revenue Agreement) proposals that may also reference kind 31402. The 402-announce definition: a parameterised replaceable event (NIP-33) where pubkey + d-tag uniquely identifies one service listing.
+
 ## Installation
 
 ```bash
@@ -28,13 +32,13 @@ High-level function: builds a kind 31402 event, signs it, connects to relays in
 
 AnnounceConfig:
   - secretKey (string, required): 64-character hex-encoded Nostr secret key
-  - relays (string[], required): Relay URLs (must start with wss:// or ws://)
+  - relays (string[], required): Relay URLs (must start with wss:// or ws://). Maximum 50.
   - identifier (string, required): Unique listing ID, used as the Nostr `d` tag. Same pubkey + identifier = same listing.
   - name (string, required): Human-readable service name
-  - urls (string[], required): Transport endpoint URLs (1–10 entries, each max 2048 characters)
+  - urls (string[], required): Transport endpoint URLs (1–10 entries, each max 2048 characters). One `url` tag per entry in the event. Clients try in order.
   - 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
+  - paymentMethods (string[][], required): Accepted payment methods. Each entry is [rail, ...params]
   - picture (string, optional): Icon URL
   - topics (string[], optional): Topic tags for search/filtering
   - capabilities (CapabilityDef[], optional): Capability details stored in event content
@@ -42,31 +46,37 @@ AnnounceConfig:
 
 PricingDef:
   - capability (string): Capability name (e.g. "get_joke", "chat", "inference")
-  - price (number): Price amount
+  - price (number): Price amount (integer or fractional)
   - currency (string): Currency unit (e.g. "sats", "USD")
 
 CapabilityDef:
   - name (string): Capability name
   - description (string): Human-readable description
-  - schema (unknown, optional): JSON Schema describing the capability's input parameters
-  - outputSchema (unknown, optional): JSON Schema describing the capability's output
+  - endpoint (string, optional): Endpoint path or full URL for this capability (e.g. '/api/joke')
+  - schema (unknown, optional): JSON Schema describing the capability's input parameters (max depth 10)
+  - outputSchema (unknown, optional): JSON Schema describing the capability's output (max depth 10)
 
 **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
+  - close(): void — Disconnect from all connected relays (synchronous; call on shutdown to avoid WebSocket leaks)
 
 **Behaviour:**
   - Validates secretKey (must be 64-char hex) and relay URLs (must be wss:// or ws://)
+  - Rejects relay URLs pointing to private/loopback addresses (SSRF prevention)
+  - Rejects service configs where all urls are private/loopback (at least one public URL required)
   - 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
+  - Warns on insecure ws:// relay URLs
 
 **Throws:**
   - If secretKey is not a 64-character hex string
-  - If relays array is empty
+  - If relays array is empty or contains more than 50 entries
   - If any relay URL does not start with wss:// or ws://
+  - If any relay URL points to a private/loopback address
+  - If all service URLs are private/loopback addresses
 
 ### buildAnnounceEvent(secretKeyHex: string, config: Omit<AnnounceConfig, 'relays'>): VerifiedEvent
 
@@ -74,7 +84,11 @@ Lower-level function: builds and signs the kind 31402 event without publishing.
 
 **Returns** a nostr-tools VerifiedEvent ready for relay publication.
 
-Secret key bytes are zeroised after signing (via try/finally).
+Secret key bytes are zeroised after signing (via try/finally). Unlike announceService(), this function does not enforce the "at least one public URL" rule — it is a pure serialisation utility.
+
+### isPrivateHost(hostname: string): boolean
+
+Utility export. Returns true if the hostname is a private, loopback, link-local, or reserved address (IPv4 or IPv6). Used internally for SSRF prevention; exported for consumers who need the same guard.
 
 ### Constants
 
@@ -85,7 +99,7 @@ Secret key bytes are zeroised after signing (via try/finally).
 - AnnounceConfig — Configuration for announceService()
 - Announcement — Handle returned by announceService()
 - PricingDef — Pricing for a specific capability
-- CapabilityDef — Capability with description
+- CapabilityDef — Capability with description, optional endpoint and schemas
 
 ## Event Format Specification
 
@@ -99,12 +113,12 @@ A kind 31402 event is a Nostr parameterised replaceable event (NIP-33). This mea
 ### 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)
+  ["d", "<identifier>"]                                    — Unique listing identifier
+  ["name", "<service name>"]                               — Human-readable name
+  ["url", "<endpoint URL>"]                                — HTTP endpoint (one tag per URL; 1–10 allowed)
+  ["about", "<description>"]                               — Short description
+  ["pmi", "<rail>", ...params]                             — 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)
@@ -115,7 +129,13 @@ Optional tags:
 JSON object with optional fields:
 {
   "capabilities": [
-    { "name": "get_joke", "description": "Returns a random joke" }
+    {
+      "name": "get_joke",
+      "description": "Returns a random joke",
+      "endpoint": "/api/joke",
+      "schema": { "type": "object", "properties": { "category": { "type": "string" } } },
+      "outputSchema": { "type": "object", "properties": { "joke": { "type": "string" } } }
+    }
   ],
   "version": "1.0.0"
 }
@@ -130,9 +150,10 @@ JSON object with optional fields:
     ["d", "jokes-api"],
     ["name", "Jokes API"],
     ["url", "https://jokes.example.com"],
+    ["url", "http://jokesxyz...onion"],
     ["about", "A joke-telling service behind an L402 paywall"],
-    ["pmi", "bitcoin-lightning-bolt11"],
-    ["pmi", "bitcoin-cashu"],
+    ["pmi", "l402", "lightning"],
+    ["pmi", "cashu"],
     ["price", "get_joke", "1", "sats"],
     ["t", "comedy"],
     ["t", "ai"]
@@ -144,19 +165,25 @@ JSON object with optional fields:
 
 ## Payment Method Identifiers
 
-Known payment method identifiers for the `pmi` tag and `paymentMethods` config:
+Each `paymentMethods` entry is an array where the first element is the rail identifier and subsequent elements are rail-specific parameters. Known rails:
 
-  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
+  l402      — L402 protocol (Lightning BOLT-11 invoices). Example: ['l402', 'lightning']
+  cashu     — Cashu ecash. Example: ['cashu']
+  xcashu    — Cashu ecash via NUT-24 (X-Cashu header). Example: ['xcashu']
+  x402      — x402 stablecoin payments. Example: ['x402', 'base', 'usdc', '0xabc...']
+  payment   — IETF Payment protocol. Example: ['payment', 'lightning']
 
-## Integration Patterns
+## Multiple URLs vs Multiple Events
+
+**Multiple URLs in one event** — use `urls: ['...', '...']` when the URLs represent the **same service** on different transports (clearnet, Tor, Handshake). Pricing, credentials, and macaroon signing key are identical. Clients try in order and use whichever they can reach. This is for censorship resistance and redundancy.
 
-### Producer side: toll-booth + 402-announce
+**Separate kind 31402 events** — publish a new event (different `identifier`) when you have **genuinely different services**: different pricing tiers, different capabilities, or services that operate independently.
 
-A typical server setup protects an API with toll-booth and announces it with 402-announce:
+Rule: same service + different network paths → one event with multiple `url` tags. Different services → separate events.
+
+## Integration Patterns
+
+### Producer: toll-booth + 402-announce
 
 ```typescript
 import { createTollBooth } from 'toll-booth'
@@ -175,16 +202,31 @@ const handle = await announceService({
   urls: ['https://api.example.com'],
   about: 'A paid API service',
   pricing: [{ capability: 'query', price: 10, currency: 'sats' }],
-  paymentMethods: ['bitcoin-lightning-bolt11'],
+  paymentMethods: [['l402', 'lightning']],
 })
 
 // 3. Clean up on shutdown
 process.on('SIGTERM', () => handle.close())
 ```
 
-### Consumer side: 402-mcp
+### Producer shortcut: toll-booth-announce
+
+If you're using toll-booth, [toll-booth-announce](https://github.com/forgesworn/toll-booth-announce) maps booth config to 402-announce automatically — pricing and payment methods are derived from your booth config:
+
+```typescript
+import { announce } from 'toll-booth-announce'
+
+const handle = await announce(boothConfig, {
+  secretKey: process.env.NOSTR_SECRET_KEY,
+  relays: ['wss://relay.damus.io'],
+  urls: ['https://api.example.com'],
+  about: 'My toll-booth API',
+})
+```
+
+### Consumer: 402-mcp
 
-AI agents use 402-mcp to discover and consume announced services:
+AI agents use [402-mcp](https://github.com/forgesworn/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
@@ -197,20 +239,39 @@ The agent never needs to know about Nostr or payment protocols — 402-mcp abstr
 
 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.
 
+### Verify on relays
+
+```bash
+# Using nak (Nostr Army Knife)
+nak req -k 31402 wss://relay.damus.io
+
+# Filter by topic
+nak req -k 31402 -t t=ai wss://relay.damus.io
+```
+
+### Live dashboard
+
+[402.pub](https://402.pub) shows every service announcing on the network in real time.
+
 ## 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.
+- **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. Note: JavaScript strings are immutable and cannot be erased — minimise the lifetime of the string in your application.
+- **SSRF prevention**: Relay URLs and service URLs are checked against private/loopback address patterns. DNS rebinding (hostname resolves to private IP at connection time) is not caught — deploy behind network-level egress controls in production.
 - **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.
+- **Input limits**: URLs max 2048 chars, max 10 service URLs, max 50 relays, JSON schema depth capped at 10, control characters rejected in all string fields.
 
 ## Error Handling
 
 The library throws synchronously for invalid configuration:
 - secretKey not 64-char hex → Error
-- Empty relays array → Error
+- Empty relays array or more than 50 relays → Error
 - Invalid relay URL (not wss:// or ws://) → Error
+- Relay URL with credentials → Error
+- Relay URL pointing to private/loopback address → Error
+- All service URLs pointing to private/loopback addresses → Error
 
 Relay-level failures during publication are handled gracefully:
 - Connection timeouts → warning logged, other relays still tried
@@ -220,5 +281,7 @@ Relay-level failures during publication are handled gracefully:
 ## Source
 
 Repository: https://github.com/forgesworn/402-announce
+npm: https://www.npmjs.com/package/402-announce
+Live dashboard: https://402.pub
 Licence: MIT
 Runtime dependency: nostr-tools

package/llms.txt

@@ -6,26 +6,36 @@
 
 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.
 
+## Kind 31402 — disambiguation
+
+This library uses kind 31402 for **L402/x402 service announcements** (paid API discovery). This is distinct from any SARA (revenue share) proposals that may also reference kind 31402. The 402-announce definition: a parameterised replaceable event (NIP-33) where pubkey + d-tag uniquely identifies one service listing.
+
 ## 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`).
+- **Payment methods**: Services declare accepted payment methods via multi-element `pmi` tags. Each `paymentMethods` entry is `[rail, ...params]` (e.g. `['l402', 'lightning']`, `['cashu']`, `['x402', 'base', 'usdc', '<addr>']`, `['payment', 'lightning']`).
 - **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.
+- **Multi-transport**: A single event can carry multiple `url` tags (1–10). Use this when the same service is reachable via clearnet, Tor (.onion), or Handshake domains.
 
 ## API surface
 
-Two exports:
+Three exports:
 
 - `announceService(config)` — build, sign, and publish to relays. Returns `{ eventId, pubkey, close() }`.
 - `buildAnnounceEvent(secretKey, config)` — build and sign without publishing. Returns a `VerifiedEvent`.
+- `isPrivateHost(hostname)` — utility: returns true if hostname is a private/loopback address (SSRF guard).
+
+Exported constant: `L402_ANNOUNCE_KIND = 31402`
 
 ## 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
+toll-booth (paywall)         → protects your API with L402
+toll-booth-announce (bridge) → maps toll-booth config to 402-announce automatically
+402-announce (this)          → tells the world your API exists via kind 31402
+402-mcp (discovery)          → AI agents find, pay, and consume your API
+402.pub (dashboard)          → live view of all announcing services
 ```
 
 ## Details

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "402-announce",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "type": "module",
   "description": "Announce HTTP 402 services (L402 and x402) on Nostr for decentralised discovery. Kind 31402 parameterised replaceable events.",
   "license": "MIT",
@@ -17,7 +17,8 @@
     "LICENSE",
     "README.md",
     "llms.txt",
-    "llms-full.txt"
+    "llms-full.txt",
+    "context7.json"
   ],
   "scripts": {
     "build": "tsc",
@@ -62,5 +63,9 @@
   },
   "engines": {
     "node": ">=18"
+  },
+  "funding": {
+    "type": "lightning",
+    "url": "lightning:thedonkey@strike.me"
   }
 }