ncc-02-js 0.2.4 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ This library provides tools for service owners to publish records and for client
 
 ## Features
 
-- **Service Discovery**: Resolve Kind 30059 service records.
+- **Service Discovery**: Resolve Kind 30059 service records for both public and private services.
 - **Verification**: Built-in signature and expiry validation.
 - **Trust Policy**: Support for third-party attestations (Kind 30060) and revocations (Kind 30061).
 - **Security**: Cross-validation of subject and service identifiers to prevent impersonation.
@@ -26,7 +26,7 @@ npm install ncc-02-js
 import { NCC02Resolver } from 'ncc-02-js';
 
 // Initialize with relay URLs and optional trusted CA pubkeys
-const resolver = new NCC02Resolver(['wss://relay.damus.io'], {
+const resolver = new NCC02Resolver(['wss://192.0.2.1:443'], {
   trustedCAPubkeys: ['npub1...'] // Trusted third-party certifiers
 });
 
@@ -36,7 +36,11 @@ try {
     requireAttestation: true,
     minLevel: 'verified' // 'self', 'verified', 'hardened'
   });
-  console.log('Resolved endpoint:', service.endpoint);
+  if(service.endpoint) {
+    console.log('Resolved endpoint:', service.endpoint);
+  } else {
+    console.log('Resolved private service, use NCC-05 for endpoint discovery.');
+  }
 } catch (err) {
   console.error('Resolution failed:', err.code, err.message);
 }
@@ -50,7 +54,7 @@ import { NCC02Builder } from 'ncc-02-js';
 // Initialize with private key (hex)
 const builder = new NCC02Builder(privateKey);
 
-// Example 1: IP-based Service
+// Example 1: Public IP-based Service
 const event = builder.createServiceRecord({
   serviceId: 'media',
   endpoint: 'https://203.0.113.45:8443',
@@ -58,10 +62,9 @@ const event = builder.createServiceRecord({
   expiryDays: 14
 });
 
-// Example 2: Tor Onion Service
-const onionEvent = builder.createServiceRecord({
+// Example 2: Private / Invite-Only Service
+const privateEvent = builder.createServiceRecord({
   serviceId: 'wallet',
-  endpoint: 'tcp://vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd.onion:80',
   fingerprint: 'sha256:fingerprint',
   expiryDays: 7
 });
@@ -109,7 +112,7 @@ The library follows a fail-closed principle. If a policy requirement is not met
 - `options.minLevel`: Minimum trust level required.
 
 ### `NCC02Builder(privateKey)`
-- `createServiceRecord({ serviceId, endpoint, fingerprint, expiryDays })`
+- `createServiceRecord({ serviceId, endpoint?, fingerprint?, expiryDays? })`
 - `createAttestation({ subjectPubkey, serviceId, serviceEventId, level, validDays })`
 - `createRevocation({ attestationId, reason })`
 

package/dist/index.cjs

@@ -2509,25 +2509,24 @@ var NCC02Builder = class {
    * Creates a signed Service Record (Kind 30059).
    * @param {Object} options
    * @param {string} options.serviceId - The 'd' tag identifier.
-   * @param {string} options.endpoint - The 'u' tag URI.
-   * @param {string} options.fingerprint - The 'k' tag fingerprint.
+   * @param {string} [options.endpoint] - The 'u' tag URI.
+   * @param {string} [options.fingerprint] - The 'k' tag fingerprint.
    * @param {number} [options.expiryDays=14] - Expiry in days.
    */
   createServiceRecord(options) {
     const { serviceId, endpoint, fingerprint, expiryDays = 14 } = options;
     if (!serviceId) throw new Error("serviceId (d tag) is required");
-    if (!endpoint) throw new Error("endpoint (u tag) is required");
-    if (!fingerprint) throw new Error("fingerprint (k tag) is required");
     const expiry = Math.floor(Date.now() / 1e3) + expiryDays * 24 * 60 * 60;
+    const tags = [
+      ["d", serviceId],
+      ["exp", expiry.toString()]
+    ];
+    if (endpoint) tags.push(["u", endpoint]);
+    if (fingerprint) tags.push(["k", fingerprint]);
     const event = {
       kind: KINDS.SERVICE_RECORD,
       created_at: Math.floor(Date.now() / 1e3),
-      tags: [
-        ["d", serviceId],
-        ["u", endpoint],
-        ["k", fingerprint],
-        ["exp", expiry.toString()]
-      ],
+      tags,
       content: `NCC-02 Service Record for ${serviceId}`,
       pubkey: this.pk
     };
@@ -7679,7 +7678,10 @@ var NCC02Resolver = class {
    * @param {string[]} relays - List of relay URLs.
    * @param {Object} [options={}]
    * @param {SimplePool} [options.pool] - Shared SimplePool instance.
-   * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys.
+   * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys (hex or npub).
+   * These are the ONLY pubkeys whose attestation signatures (Kind 30060) will be accepted
+   * by the resolver. This allows you to define your own web of trust or rely on specific
+   * community auditors. If empty, all attestations are ignored (effectively disabling attestation checks).
    */
   constructor(relays, options = {}) {
     if (!Array.isArray(relays)) {
@@ -7749,8 +7751,11 @@ var NCC02Resolver = class {
     }
     const serviceTags = Object.fromEntries(serviceEvent.tags);
     const now2 = Math.floor(Date.now() / 1e3);
-    if (!serviceTags.u || !serviceTags.k || !serviceTags.exp) {
-      throw new NCC02Error("MALFORMED_RECORD", "Service record is missing required tags (u, k, or exp)");
+    if (!serviceTags.exp) {
+      throw new NCC02Error("MALFORMED_RECORD", "Service record is missing required tag (exp)");
+    }
+    if (serviceTags.u && (serviceTags.u.startsWith("wss://") || serviceTags.u.startsWith("https://")) && !serviceTags.k) {
+      throw new NCC02Error("MALFORMED_RECORD", "Service record with 'https' or 'wss' endpoint must have a 'k' tag");
     }
     const exp = parseInt(serviceTags.exp);
     if (isNaN(exp)) {

package/dist/index.mjs

@@ -2475,25 +2475,24 @@ var NCC02Builder = class {
    * Creates a signed Service Record (Kind 30059).
    * @param {Object} options
    * @param {string} options.serviceId - The 'd' tag identifier.
-   * @param {string} options.endpoint - The 'u' tag URI.
-   * @param {string} options.fingerprint - The 'k' tag fingerprint.
+   * @param {string} [options.endpoint] - The 'u' tag URI.
+   * @param {string} [options.fingerprint] - The 'k' tag fingerprint.
    * @param {number} [options.expiryDays=14] - Expiry in days.
    */
   createServiceRecord(options) {
     const { serviceId, endpoint, fingerprint, expiryDays = 14 } = options;
     if (!serviceId) throw new Error("serviceId (d tag) is required");
-    if (!endpoint) throw new Error("endpoint (u tag) is required");
-    if (!fingerprint) throw new Error("fingerprint (k tag) is required");
     const expiry = Math.floor(Date.now() / 1e3) + expiryDays * 24 * 60 * 60;
+    const tags = [
+      ["d", serviceId],
+      ["exp", expiry.toString()]
+    ];
+    if (endpoint) tags.push(["u", endpoint]);
+    if (fingerprint) tags.push(["k", fingerprint]);
     const event = {
       kind: KINDS.SERVICE_RECORD,
       created_at: Math.floor(Date.now() / 1e3),
-      tags: [
-        ["d", serviceId],
-        ["u", endpoint],
-        ["k", fingerprint],
-        ["exp", expiry.toString()]
-      ],
+      tags,
       content: `NCC-02 Service Record for ${serviceId}`,
       pubkey: this.pk
     };
@@ -7645,7 +7644,10 @@ var NCC02Resolver = class {
    * @param {string[]} relays - List of relay URLs.
    * @param {Object} [options={}]
    * @param {SimplePool} [options.pool] - Shared SimplePool instance.
-   * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys.
+   * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys (hex or npub).
+   * These are the ONLY pubkeys whose attestation signatures (Kind 30060) will be accepted
+   * by the resolver. This allows you to define your own web of trust or rely on specific
+   * community auditors. If empty, all attestations are ignored (effectively disabling attestation checks).
    */
   constructor(relays, options = {}) {
     if (!Array.isArray(relays)) {
@@ -7715,8 +7717,11 @@ var NCC02Resolver = class {
     }
     const serviceTags = Object.fromEntries(serviceEvent.tags);
     const now2 = Math.floor(Date.now() / 1e3);
-    if (!serviceTags.u || !serviceTags.k || !serviceTags.exp) {
-      throw new NCC02Error("MALFORMED_RECORD", "Service record is missing required tags (u, k, or exp)");
+    if (!serviceTags.exp) {
+      throw new NCC02Error("MALFORMED_RECORD", "Service record is missing required tag (exp)");
+    }
+    if (serviceTags.u && (serviceTags.u.startsWith("wss://") || serviceTags.u.startsWith("https://")) && !serviceTags.k) {
+      throw new NCC02Error("MALFORMED_RECORD", "Service record with 'https' or 'wss' endpoint must have a 'k' tag");
     }
     const exp = parseInt(serviceTags.exp);
     if (isNaN(exp)) {

package/dist/models.d.ts

@@ -22,14 +22,14 @@ export class NCC02Builder {
      * Creates a signed Service Record (Kind 30059).
      * @param {Object} options
      * @param {string} options.serviceId - The 'd' tag identifier.
-     * @param {string} options.endpoint - The 'u' tag URI.
-     * @param {string} options.fingerprint - The 'k' tag fingerprint.
+     * @param {string} [options.endpoint] - The 'u' tag URI.
+     * @param {string} [options.fingerprint] - The 'k' tag fingerprint.
      * @param {number} [options.expiryDays=14] - Expiry in days.
      */
     createServiceRecord(options: {
         serviceId: string;
-        endpoint: string;
-        fingerprint: string;
+        endpoint?: string;
+        fingerprint?: string;
         expiryDays?: number;
     }): import("nostr-tools/core").VerifiedEvent;
     /**

package/dist/resolver.d.ts

@@ -13,8 +13,8 @@ export class NCC02Error extends Error {
 }
 /**
  * @typedef {Object} ResolvedService
- * @property {string} endpoint
- * @property {string} fingerprint
+ * @property {string|undefined} endpoint
+ * @property {string|undefined} fingerprint
  * @property {number} expiry
  * @property {any[]} attestations
  * @property {string} eventId
@@ -29,7 +29,10 @@ export class NCC02Resolver {
      * @param {string[]} relays - List of relay URLs.
      * @param {Object} [options={}]
      * @param {SimplePool} [options.pool] - Shared SimplePool instance.
-     * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys.
+     * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys (hex or npub).
+     * These are the ONLY pubkeys whose attestation signatures (Kind 30060) will be accepted
+     * by the resolver. This allows you to define your own web of trust or rely on specific
+     * community auditors. If empty, all attestations are ignored (effectively disabling attestation checks).
      */
     constructor(relays: string[], options?: {
         pool?: SimplePool;
@@ -84,8 +87,8 @@ export class NCC02Resolver {
     verifyEndpoint(resolved: ResolvedService, actualFingerprint: string): boolean;
 }
 export type ResolvedService = {
-    endpoint: string;
-    fingerprint: string;
+    endpoint: string | undefined;
+    fingerprint: string | undefined;
     expiry: number;
     attestations: any[];
     eventId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncc-02-js",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Nostr-native service discovery and trust implementation (NCC-02)",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

package/src/models.js

@@ -27,26 +27,26 @@ export class NCC02Builder {
    * Creates a signed Service Record (Kind 30059).
    * @param {Object} options
    * @param {string} options.serviceId - The 'd' tag identifier.
-   * @param {string} options.endpoint - The 'u' tag URI.
-   * @param {string} options.fingerprint - The 'k' tag fingerprint.
+   * @param {string} [options.endpoint] - The 'u' tag URI.
+   * @param {string} [options.fingerprint] - The 'k' tag fingerprint.
    * @param {number} [options.expiryDays=14] - Expiry in days.
    */
   createServiceRecord(options) {
     const { serviceId, endpoint, fingerprint, expiryDays = 14 } = options;
     if (!serviceId) throw new Error('serviceId (d tag) is required');
-    if (!endpoint) throw new Error('endpoint (u tag) is required');
-    if (!fingerprint) throw new Error('fingerprint (k tag) is required');
 
     const expiry = Math.floor(Date.now() / 1000) + (expiryDays * 24 * 60 * 60);
+    const tags = [
+      ['d', serviceId],
+      ['exp', expiry.toString()]
+    ];
+    if(endpoint) tags.push(['u', endpoint]);
+    if(fingerprint) tags.push(['k', fingerprint]);
+
     const event = {
       kind: KINDS.SERVICE_RECORD,
       created_at: Math.floor(Date.now() / 1000),
-      tags: [
-        ['d', serviceId],
-        ['u', endpoint],
-        ['k', fingerprint],
-        ['exp', expiry.toString()]
-      ],
+      tags: tags,
       content: `NCC-02 Service Record for ${serviceId}`,
       pubkey: this.pk
     };

package/src/resolver.js

@@ -19,8 +19,8 @@ export class NCC02Error extends Error {
 
 /**
  * @typedef {Object} ResolvedService
- * @property {string} endpoint
- * @property {string} fingerprint
+ * @property {string|undefined} endpoint
+ * @property {string|undefined} fingerprint
  * @property {number} expiry
  * @property {any[]} attestations
  * @property {string} eventId
@@ -36,11 +36,14 @@ export class NCC02Resolver {
    * @param {string[]} relays - List of relay URLs.
    * @param {Object} [options={}]
    * @param {SimplePool} [options.pool] - Shared SimplePool instance.
-   * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys.
+   * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys (hex or npub).
+   * These are the ONLY pubkeys whose attestation signatures (Kind 30060) will be accepted
+   * by the resolver. This allows you to define your own web of trust or rely on specific
+   * community auditors. If empty, all attestations are ignored (effectively disabling attestation checks).
    */
   constructor(relays, options = {}) {
     if (!Array.isArray(relays)) {
-       throw new Error("NCC02Resolver expects an array of relay URLs.");
+      throw new Error('NCC02Resolver expects an array of relay URLs.');
     }
     this.relays = relays;
     this.pool = options.pool || new SimplePool();
@@ -54,16 +57,16 @@ export class NCC02Resolver {
    * @returns {Promise<import('nostr-tools').Event[]>}
    */
   async _query(filter) {
-      return new Promise((resolve) => {
-          /** @type {import('nostr-tools').Event[]} */
-          const events = [];
-          // subscribeMany(relays, filters, callbacks)
-          // @ts-ignore - subscribeMany filters parameter type mismatch with simple Object
-          const sub = this.pool.subscribeMany(this.relays, [filter], {
-              onevent(e) { events.push(e); },
-              oneose() { sub.close(); resolve(events); }
-          });
+    return new Promise((resolve) => {
+      /** @type {import('nostr-tools').Event[]} */
+      const events = [];
+      // subscribeMany(relays, filters, callbacks)
+      // @ts-ignore - subscribeMany filters parameter type mismatch with simple Object
+      const sub = this.pool.subscribeMany(this.relays, [filter], {
+        onevent(e) { events.push(e); },
+        oneose() { sub.close(); resolve(events); }
       });
+    });
   }
 
   /**
@@ -114,8 +117,13 @@ export class NCC02Resolver {
     const now = Math.floor(Date.now() / 1000);
 
     // Security Fix: exp is REQUIRED by NCC-02 spec
-    if (!serviceTags.u || !serviceTags.k || !serviceTags.exp) {
-      throw new NCC02Error('MALFORMED_RECORD', 'Service record is missing required tags (u, k, or exp)');
+    if (!serviceTags.exp) {
+      throw new NCC02Error('MALFORMED_RECORD', 'Service record is missing required tag (exp)');
+    }
+    
+    // 'k' is required for TLS-based endpoints
+    if (serviceTags.u && (serviceTags.u.startsWith('wss://') || serviceTags.u.startsWith('https://')) && !serviceTags.k) {
+      throw new NCC02Error('MALFORMED_RECORD', 'Service record with \'https\' or \'wss\' endpoint must have a \'k\' tag');
     }
 
     const exp = parseInt(serviceTags.exp);