ncc-05-js

Nostr Community Convention 05 (NCC-05) implementation for JavaScript/TypeScript.

This library provides a standard way to publish and resolve Identity-Bound Service Locators on the Nostr network. It allows Nostr identities to dynamically publish endpoints (IPs, domains, Tor .onion addresses) that can be resolved by others, effectively functioning as a decentralized, identity-based DNS.

Features

* Identity-Bound: Records are signed by Nostr identities (npub), ensuring authenticity.
* Privacy-Focused: Supports NIP-44 encryption (public, self-encrypted, targeted, and multi-recipient).
* Dynamic: Updates propagate instantly across relays (Kind 30058 replaceable events).
* Resilient: Supports NIP-65 gossip for decentralized discovery, finding the relays where the target user actually publishes.
* Flexible: Works with any endpoint type (TCP, UDP, HTTP, Onion, etc.).
* Efficient: Supports sharing a SimplePool instance for connection management.
* Typed: Written in TypeScript with full type definitions.

Installation

``bash
npm install ncc-05-js
`

Quick Start

$3

`typescript
import { NCC05Publisher, NCC05Payload } from 'ncc-05-js';

const publisher = new NCC05Publisher();
const relays = ['wss://relay.damus.io', 'wss://npub1base64userpubkey...'];
const mySecretKey = '...'; // Hex string or Uint8Array

const payload: NCC05Payload = {
v: 1,
ttl: 3600,
updated_at: Math.floor(Date.now() / 1000),
endpoints: [
{ type: 'https', uri: '192.168.1.42:443', priority: 1, family: 'ipv4' }
]
};

// Publish a public record
try {
await publisher.publish(relays, mySecretKey, payload, { public: true });
console.log('Service published!');
} catch (error) {
console.error('Publishing failed:', error);
}

publisher.close(relays);
`

$3

`typescript
import { NCC05Resolver } from 'ncc-05-js';

const resolver = new NCC05Resolver();
const targetPubkey = 'npub1...'; // or hex

try {
const record = await resolver.resolve(targetPubkey);

if (record) {
console.log('Found endpoints:', record.endpoints);
} else {
console.log('No service record found.');
}
} catch (error) {
console.error('Resolution failed:', error);
}

resolver.close();
`

$3

When a single identity publishes multiple Kind 30058 records with different d tags, resolveLatest treats the pubkey as a DNS name and automatically returns the freshest valid locator across all of them. It scans every published record, decrypts the ones you are allowed to read, and prefers the entry with the most recent updated_at.

`typescript
const latest = await resolver.resolveLatest(targetPubkey);
if (latest) {
console.log('Freshest endpoints:', latest.endpoints);
}
`

---

Detailed Usage

$3

Both NCC05Resolver and NCC05Publisher accept configuration objects.

#### Shared Connection Pool
For efficiency, especially in long-running applications or when using other Nostr libraries, you should share a single SimplePool instance.

`typescript
import { SimplePool } from 'nostr-tools';
import { NCC05Resolver, NCC05Publisher } from 'ncc-05-js';

const pool = new SimplePool();

const resolver = new NCC05Resolver({ pool });
const publisher = new NCC05Publisher({ pool });

// ... usage ...

// You are responsible for closing the pool if you passed it in
// pool.close(usedRelays);
`

#### Custom Relays & Timeouts

`typescript
const resolver = new NCC05Resolver({
// Relays to start looking at (Bootstrap relays)
bootstrapRelays: ['wss://relay.custom.com'],
// Timeout for resolution in milliseconds (Default: 10000)
timeout: 5000
});
`

#### Asynchronous Signers

NCC05Publisher and NCC05Resolver accept SignerInput, which can be a raw secret (hex/Uint8Array) or a NostrSigner bridge (NIP-07, NIP-46, etc.). A signer must expose the identity's pubkey, sign events, and derive conversation keys for encrypted payloads.

`typescript
const extensionBridge = window.nostr;

const signer: NostrSigner = {
getPublicKey: async () => await extensionBridge.getPublicKey(),
signEvent: async (event) => await extensionBridge.signEvent(event),
getConversationKey: async (peer) => await extensionBridge.getSharedSecret(peer)
};

await publisher.publish(relays, signer, payload);
`

This keeps private keys inside the signer implementation while still allowing NCC-05 to encrypt, decrypt, and sign on-demand.

#### Transport-aware Resolution

NCC05Resolver accepts an optional urlTransformer hook that adjusts each endpoint before it is returned to you. This is ideal for automatically wrapping .onion targets in a locally configured bridge URL so browser-based clients are transport-aware.

`typescript
const resolver = new NCC05Resolver({
bootstrapRelays: ['wss://relay.damus.io'],
urlTransformer: endpoint => {
if (endpoint.family === 'onion' || endpoint.url.includes('.onion')) {
return {
...endpoint,
url: https://local-tor-proxy/?target=${encodeURIComponent(endpoint.url)}
};
}
return endpoint;
}
});
`

$3

The NCC05Publisher supports different privacy levels using NIP-44 encryption.

#### Public Records (Unencrypted)
Readable by anyone.

`typescript
await publisher.publish(relays, secretKey, payload, {
identifier: 'my-service', // 'd' tag
public: true
});
`

#### Private Records (Self-Encrypted)
Only readable by you (the publisher). Useful for personal device syncing or private configuration.

`typescript
await publisher.publish(relays, secretKey, payload, {
identifier: 'my-device'
// public: false is default
// recipient defaults to self if omitted
});
`

#### Targeted Records
Readable only by a specific recipient.

`typescript
await publisher.publish(relays, secretKey, payload, {
identifier: 'for-alice',
recipientPubkey: 'alice_hex_pubkey'
});
`

#### Wrapped Records (Multi-Recipient)
Readable by a group of users. Uses a "wrapping" pattern where the payload is encrypted with a random session key, and that session key is encrypted individually for each recipient.

`typescript
const recipients = ['hex_pubkey_1', 'hex_pubkey_2', 'hex_pubkey_3'];

await publisher.publishWrapped(
relays,
secretKey,
recipients,
payload,
'team-service'
);
`

$3

The NCC05Resolver finds the latest valid record for a given user and identifier.

`typescript
const payload = await resolver.resolve(
targetPubkey, // npub or hex
mySecretKey, // Required if the record is encrypted for you (can be null/undefined if public)
'my-service', // The 'd' tag identifier (default: 'addr')
{
gossip: true, // Enable NIP-65 relay discovery (Highly Recommended)
strict: false // If true, returns null for expired records instead of just logging a warning
}
);
`

Note that resolve now only returns a payload when the identity's latest event still advertises the requested d tag; otherwise it returns null, enforcing the identity's newest action as the single source of truth. If you only care about the freshest record regardless of metadata, call resolveLatest.

Note on Keys: All methods accept SignerInput, meaning a hex string, Uint8Array, or an asynchronous NostrSigner implementation.

API Reference

$3

The core data structure representing the service locator.

`typescript
interface NCC05Payload {
v: number; // Version (always 1)
ttl: number; // Time-to-live (seconds)
updated_at: number; // Unix timestamp
endpoints: NCC05Endpoint[];
caps?: string[]; // Optional capabilities (e.g. ['upload', 'stream'])
notes?: string; // Optional human-readable notes
}

interface NCC05Endpoint {
type: string; // e.g., 'tcp', 'http', 'ipfs', 'hyper'
uri: string; // e.g., '10.0.0.1:80', '[2001:db8::1]:443', 'onion_address:80'
priority: number; // Lower number = higher priority
family: string; // 'ipv4', 'ipv6', 'onion', 'unknown'
}
`

$3

* constructor(options?)
* bootstrapRelays: string[] (Default: ['wss://relay.damus.io', 'wss://npub1...'])
* timeout: number (ms) (Default: 10000)
* pool: SimplePool (optional)
* resolve(targetPubkey, secretKey?, identifier?, options?): Promise
* gossip: boolean - Fetch target's relay list (NIP-65) to find where they publish.
* strict: boolean - Enforce TTL expiration strictly.
* close(): Closes connections (only if pool was created internally).

$3

* constructor(options?)
* pool: SimplePool (optional)
* timeout: number (ms) (Default: 5000)
* publish(relays, secretKey, payload, options?): Promise
* identifier: string (Default: 'addr')
* public: boolean (Default: false)
* recipientPubkey: string (Default: self)
* privateLocator: boolean (Default: false) - Adds ["private", "true"] tag.
* publishWrapped(relays, secretKey, recipients, payload, options?): Promise
* options: { identifier?: string, privateLocator?: boolean } or string (identifier)
* close(relays): Closes connections to specific relays (only if pool was created internally).

Error Handling

Errors are typed for granular handling:

* NCC05TimeoutError: Relay operations took too long.
* NCC05RelayError: Failed to publish or query relays.
* NCC05DecryptionError: Bad key or invalid ciphertext.
* NCC05ArgumentError: Invalid inputs (e.g. malformed keys).

Utilities

* TAG_PRIVATE: Constant string 'private'.
* isPrivateLocator(event: Event): boolean: Helper to check if an event has the ["private", "true"]` tag.

Protocol Details

This library implements NCC-05, which uses Nostr Kind 30058 (Parametrized Replaceable Event) to store service locators.

It leverages:
* NIP-01: Basic protocol flow.
* NIP-19: bech32-encoded entities (npub, nsec).
* NIP-44: Encryption (XChaCha20-Poly1305).
* NIP-65: Relay discovery (Gossip).

License

CC0-1.0