ncc-06-js 0.3.0 → 0.3.2

package/DOCS.md

@@ -79,7 +79,7 @@ Utilities for locator payload construction and evaluation.
 - Reads a config block (`k.mode`) and returns the expected `k` string for static/generate/tls modes; used by the sidecar.
 
 ### Key helpers
-- `generateKeypair()`, `toNpub()`, `fromNsec()` wrap `nostr-tools` key utilities for convenience.
+- `generateKeypair()`, `toNpub()`, `fromNpub()`, `toNsec()`, `fromNsec()` wrap `nostr-tools` key utilities for convenience.
 - `ensureSelfSignedCert(options)` generates a self-signed cert for local `wss://` endpoints.
 
 ## Endpoint helpers

package/README.md

@@ -14,6 +14,14 @@ Reusable helpers extracted from the NCC-06 example relay, sidecar, and client im
 ...
 - **Relay & Service mode helpers** (`getRelayMode`, `setRelayMode`) so you can control whether your service is *public* (publishes NCC-05 locators) or *private`.
 
+## Why NCC-06? (Identity vs Location)
+
+Unlike DNS, which binds a service to a **location** (domain/IP), NCC-06 binds a service to an **identity** (Public Key / Npub).
+
+- **Portability:** Move your service to a new IP, Tor address, or provider instantly. Clients follow the *key*, not the server.
+- **Censorship Resistance:** Discovery happens via decentralized relays, not centralized root servers.
+- **Trust:** End-to-end authentication is built-in. The "K" fingerprint ensures the server you connect to is authorized by the identity you resolved.
+
 ## Usage
 
 Install directly from the repository (example workspace):
@@ -27,6 +35,7 @@ npm install ../ncc-06-js
 ```js
 import { resolveServiceEndpoint } from 'ncc-06-js';
 
+// "Bootstrap Relays" act as the decentralized directory for finding the service's current location.
 const resolution = await resolveServiceEndpoint({
   bootstrapRelays: ['wss://relay.damus.io'],
   servicePubkey: '...',
@@ -39,15 +48,53 @@ const resolution = await resolveServiceEndpoint({
 console.log('Resolved API endpoint:', resolution.endpoint);
 ```
 
-### Building a Service Config
+### Resolving a Tor Service via Npub
+
+```js
+import { resolveServiceEndpoint, fromNpub } from 'ncc-06-js';
+
+const servicePubkey = fromNpub('npub1...');
+
+const resolution = await resolveServiceEndpoint({
+  bootstrapRelays: ['wss://relay.damus.io'],
+  servicePubkey,
+  serviceId: 'relay',
+  locatorId: 'relay-locator',
+  torPreferred: true // Prefer .onion endpoints if available
+});
+
+console.log('Resolved Onion Endpoint:', resolution.endpoint);
+```
+
+### Configuring an Onion Service Sidecar
+
+```js
+import { buildExternalEndpoints, buildSidecarConfig } from 'ncc-06-js';
+
+// 1. Build endpoints (detects Onion, IPv6, IPv4)
+const endpoints = await buildExternalEndpoints({
+  tor: { enabled: true },
+  ensureOnionService: async () => ({ address: 'abcdef...', servicePort: 80 })
+});
+
+// 2. Build config
+const config = buildSidecarConfig({
+  secretKey: '...',
+  serviceUrl: 'ws://abcdef....onion', // Primary identity URL
+  externalEndpoints: endpoints,
+  serviceMode: 'public'
+});
+```
+
+### Building a Service Config (No DNS)
 
 ```js
 import { buildSidecarConfig } from 'ncc-06-js';
 
 const config = buildSidecarConfig({
   secretKey: '...',
-  serviceUrl: 'https://api.example.com',
-  serviceId: 'my-api',
+  serviceUrl: 'tcp://203.0.113.1:9000', // Direct IP or any URI scheme
+  serviceId: 'my-custom-service',
   serviceMode: 'public'
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncc-06-js",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Reusable NCC-06 discovery helpers extracted from the example relay, sidecar, and client.",
   "type": "module",
   "main": "src/index.js",