ncc-02-js 0.3.0 → 0.3.1

package/README.md

@@ -43,64 +43,26 @@ try {
   }
 } catch (err) {
   console.error('Resolution failed:', err.code, err.message);
+} finally {
+  resolver.close(); // Clean up WebSocket connections
 }
 ```
 
 ### 2. Publish a Service Record
-
-```javascript
-import { NCC02Builder } from 'ncc-02-js';
-
-// Initialize with private key (hex)
-const builder = new NCC02Builder(privateKey);
-
-// Example 1: Public IP-based Service
-const event = builder.createServiceRecord({
-  serviceId: 'media',
-  endpoint: 'https://203.0.113.45:8443',
-  fingerprint: 'sha256:fingerprint',
-  expiryDays: 14
-});
-
-// Example 2: Private / Invite-Only Service
-const privateEvent = builder.createServiceRecord({
-  serviceId: 'wallet',
-  fingerprint: 'sha256:fingerprint',
-  expiryDays: 7
-});
-// publish events to relays...
-```
-
-### 3. Issue an Attestation (CA)
-
-```javascript
-const caBuilder = new NCC02Builder(caPrivateKey);
-const attestation = caBuilder.createAttestation({
-  subjectPubkey: 'npub1...', // The service owner being certified
-  serviceId: 'media',
-  serviceEventId: serviceRecordEventId,
-  level: 'verified',
-  validDays: 30
-});
-```
-
-## Trust Model & Security
+...
+### Trust Model & Security
 
 ### Trust Levels
 - `self`: Asserted by the service owner (default if no attestation).
 - `verified`: Attested by a trusted third party.
 - `hardened`: Attested by a third party with stricter verification (e.g., physical proof or long-term history).
 
-### Threat Model
-- **Endpoint Impersonation**: Prevented by binding the endpoint URI to a public key fingerprint (`k` tag).
-- **Man-in-the-Middle (MITM)**: Mitigated via cryptographic pinning of transport-level keys.
-- **Stale Records**: Limited by required expiry (`exp`) and support for revocations.
-- **Relay Censorship**: Mitigated by querying multiple relays (implemented via `SimplePool`).
+### Resolution Optimization
+The resolver is designed to be network-efficient. It will only query for attestations (Kind 30060) and revocations (Kind 30061) if the provided policy requires them (e.g., when `requireAttestation` is set to `true` or a `minLevel` higher than `self` is requested).
 
-### Fail-Closed Design
-The library follows a fail-closed principle. If a policy requirement is not met (e.g., `requireAttestation: true` but no valid attestation is found), it throws an `NCC02Error` rather than returning a partially verified record.
-
-## API Reference
+### Threat Model
+...
+### API Reference
 
 ### `NCC02Resolver(relays, options)`
 - `relays`: Array of relay URLs.
@@ -111,6 +73,10 @@ The library follows a fail-closed principle. If a policy requirement is not met
 - `options.requireAttestation`: Fails if no trusted attestation is found.
 - `options.minLevel`: Minimum trust level required.
 
+#### `close()`
+Closes WebSocket connections to all relays. If the resolver was initialized with an external `pool`, this will *not* close the pool; it only untracks the relays for this instance. If the resolver created its own internal pool, it will close it entirely.
+
+
 ### `NCC02Builder(privateKey)`
 - `createServiceRecord({ serviceId, endpoint?, fingerprint?, expiryDays? })`
 - `createAttestation({ subjectPubkey, serviceId, serviceEventId, level, validDays })`

package/dist/index.cjs

@@ -7692,6 +7692,14 @@ var NCC02Resolver = class {
     this.ownsPool = !options.pool;
     this.trustedCAPubkeys = new Set(options.trustedCAPubkeys || []);
   }
+  /**
+   * Closes the connection to the relays if the pool is owned by this resolver.
+   */
+  close() {
+    if (this.ownsPool && this.pool) {
+      this.pool.close(this.relays);
+    }
+  }
   /**
    * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
    * @param {import('nostr-tools').Filter} filter 
@@ -7764,35 +7772,37 @@ var NCC02Resolver = class {
     if (exp < now2) {
       throw new NCC02Error("EXPIRED", "Service record has expired");
     }
-    let attestations;
-    let revocations;
-    try {
-      [attestations, revocations] = await Promise.all([
-        this._query({ kinds: [KINDS.ATTESTATION], "#e": [serviceEvent.id] }),
-        this._query({ kinds: [KINDS.REVOCATION] })
-      ]);
-    } catch (err) {
-      throw new NCC02Error("RELAY_ERROR", "Failed to query relay for attestations/revocations", err);
-    }
     const validAttestations = [];
-    for (const att of attestations) {
-      if (this.trustedCAPubkeys.has(att.pubkey)) {
-        const attTags = Object.fromEntries(att.tags);
-        if (attTags.subj !== pubkey) continue;
-        if (attTags.srv !== serviceId) continue;
-        if (standard && attTags.std !== standard) continue;
-        if (minLevel && !this._isLevelSufficient(attTags.lvl, minLevel)) continue;
-        if (this._isAttestationValid(att, attTags, revocations)) {
-          validAttestations.push({
-            pubkey: att.pubkey,
-            level: attTags.lvl,
-            eventId: att.id
-          });
+    if (requireAttestation || minLevel === "verified" || minLevel === "hardened") {
+      let attestations;
+      let revocations;
+      try {
+        [attestations, revocations] = await Promise.all([
+          this._query({ kinds: [KINDS.ATTESTATION], "#e": [serviceEvent.id] }),
+          this._query({ kinds: [KINDS.REVOCATION] })
+        ]);
+      } catch (err) {
+        throw new NCC02Error("RELAY_ERROR", "Failed to query relay for attestations/revocations", err);
+      }
+      for (const att of attestations) {
+        if (this.trustedCAPubkeys.has(att.pubkey)) {
+          const attTags = Object.fromEntries(att.tags);
+          if (attTags.subj !== pubkey) continue;
+          if (attTags.srv !== serviceId) continue;
+          if (standard && attTags.std !== standard) continue;
+          if (minLevel && !this._isLevelSufficient(attTags.lvl, minLevel)) continue;
+          if (this._isAttestationValid(att, attTags, revocations)) {
+            validAttestations.push({
+              pubkey: att.pubkey,
+              level: attTags.lvl,
+              eventId: att.id
+            });
+          }
         }
       }
-    }
-    if (requireAttestation && validAttestations.length === 0) {
-      throw new NCC02Error("POLICY_FAILURE", `No trusted attestations meet the required policy for ${serviceId}`);
+      if (requireAttestation && validAttestations.length === 0) {
+        throw new NCC02Error("POLICY_FAILURE", `No trusted attestations meet the required policy for ${serviceId}`);
+      }
     }
     return {
       endpoint: serviceTags.u,

package/dist/index.mjs

@@ -7658,6 +7658,14 @@ var NCC02Resolver = class {
     this.ownsPool = !options.pool;
     this.trustedCAPubkeys = new Set(options.trustedCAPubkeys || []);
   }
+  /**
+   * Closes the connection to the relays if the pool is owned by this resolver.
+   */
+  close() {
+    if (this.ownsPool && this.pool) {
+      this.pool.close(this.relays);
+    }
+  }
   /**
    * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
    * @param {import('nostr-tools').Filter} filter 
@@ -7730,35 +7738,37 @@ var NCC02Resolver = class {
     if (exp < now2) {
       throw new NCC02Error("EXPIRED", "Service record has expired");
     }
-    let attestations;
-    let revocations;
-    try {
-      [attestations, revocations] = await Promise.all([
-        this._query({ kinds: [KINDS.ATTESTATION], "#e": [serviceEvent.id] }),
-        this._query({ kinds: [KINDS.REVOCATION] })
-      ]);
-    } catch (err) {
-      throw new NCC02Error("RELAY_ERROR", "Failed to query relay for attestations/revocations", err);
-    }
     const validAttestations = [];
-    for (const att of attestations) {
-      if (this.trustedCAPubkeys.has(att.pubkey)) {
-        const attTags = Object.fromEntries(att.tags);
-        if (attTags.subj !== pubkey) continue;
-        if (attTags.srv !== serviceId) continue;
-        if (standard && attTags.std !== standard) continue;
-        if (minLevel && !this._isLevelSufficient(attTags.lvl, minLevel)) continue;
-        if (this._isAttestationValid(att, attTags, revocations)) {
-          validAttestations.push({
-            pubkey: att.pubkey,
-            level: attTags.lvl,
-            eventId: att.id
-          });
+    if (requireAttestation || minLevel === "verified" || minLevel === "hardened") {
+      let attestations;
+      let revocations;
+      try {
+        [attestations, revocations] = await Promise.all([
+          this._query({ kinds: [KINDS.ATTESTATION], "#e": [serviceEvent.id] }),
+          this._query({ kinds: [KINDS.REVOCATION] })
+        ]);
+      } catch (err) {
+        throw new NCC02Error("RELAY_ERROR", "Failed to query relay for attestations/revocations", err);
+      }
+      for (const att of attestations) {
+        if (this.trustedCAPubkeys.has(att.pubkey)) {
+          const attTags = Object.fromEntries(att.tags);
+          if (attTags.subj !== pubkey) continue;
+          if (attTags.srv !== serviceId) continue;
+          if (standard && attTags.std !== standard) continue;
+          if (minLevel && !this._isLevelSufficient(attTags.lvl, minLevel)) continue;
+          if (this._isAttestationValid(att, attTags, revocations)) {
+            validAttestations.push({
+              pubkey: att.pubkey,
+              level: attTags.lvl,
+              eventId: att.id
+            });
+          }
         }
       }
-    }
-    if (requireAttestation && validAttestations.length === 0) {
-      throw new NCC02Error("POLICY_FAILURE", `No trusted attestations meet the required policy for ${serviceId}`);
+      if (requireAttestation && validAttestations.length === 0) {
+        throw new NCC02Error("POLICY_FAILURE", `No trusted attestations meet the required policy for ${serviceId}`);
+      }
     }
     return {
       endpoint: serviceTags.u,

package/dist/resolver.d.ts

@@ -42,6 +42,10 @@ export class NCC02Resolver {
     pool: SimplePool;
     ownsPool: boolean;
     trustedCAPubkeys: Set<string>;
+    /**
+     * Closes the connection to the relays if the pool is owned by this resolver.
+     */
+    close(): void;
     /**
      * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
      * @param {import('nostr-tools').Filter} filter

package/package.json

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

package/src/resolver.js

@@ -51,6 +51,15 @@ export class NCC02Resolver {
     this.trustedCAPubkeys = new Set(options.trustedCAPubkeys || []);
   }
 
+  /**
+   * Closes the connection to the relays if the pool is owned by this resolver.
+   */
+  close() {
+    if (this.ownsPool && this.pool) {
+      this.pool.close(this.relays);
+    }
+  }
+
   /**
    * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
    * @param {import('nostr-tools').Filter} filter 
@@ -134,42 +143,46 @@ export class NCC02Resolver {
       throw new NCC02Error('EXPIRED', 'Service record has expired');
     }
 
-    let attestations;
-    let revocations;
-    try {
-      [attestations, revocations] = await Promise.all([
-        this._query({ kinds: [KINDS.ATTESTATION], '#e': [serviceEvent.id] }),
-        this._query({ kinds: [KINDS.REVOCATION] })
-      ]);
-    } catch (err) {
-      throw new NCC02Error('RELAY_ERROR', 'Failed to query relay for attestations/revocations', err);
-    }
-
     const validAttestations = [];
-    for (const att of attestations) {
-      if (this.trustedCAPubkeys.has(att.pubkey)) {
-        const attTags = Object.fromEntries(att.tags);
-        
-        // Cross-validate subject, service ID, and standard
-        if (attTags.subj !== pubkey) continue;
-        if (attTags.srv !== serviceId) continue;
-        if (standard && attTags.std !== standard) continue;
-        
-        // Trust Level Filtering
-        if (minLevel && !this._isLevelSufficient(attTags.lvl, minLevel)) continue;
-
-        if (this._isAttestationValid(att, attTags, revocations)) {
-          validAttestations.push({
-            pubkey: att.pubkey,
-            level: attTags.lvl,
-            eventId: att.id
-          });
+
+    // Optimization: Only fetch attestations if policy requires it
+    if (requireAttestation || minLevel === 'verified' || minLevel === 'hardened') {
+      let attestations;
+      let revocations;
+      try {
+        [attestations, revocations] = await Promise.all([
+          this._query({ kinds: [KINDS.ATTESTATION], '#e': [serviceEvent.id] }),
+          this._query({ kinds: [KINDS.REVOCATION] })
+        ]);
+      } catch (err) {
+        throw new NCC02Error('RELAY_ERROR', 'Failed to query relay for attestations/revocations', err);
+      }
+
+      for (const att of attestations) {
+        if (this.trustedCAPubkeys.has(att.pubkey)) {
+          const attTags = Object.fromEntries(att.tags);
+          
+          // Cross-validate subject, service ID, and standard
+          if (attTags.subj !== pubkey) continue;
+          if (attTags.srv !== serviceId) continue;
+          if (standard && attTags.std !== standard) continue;
+          
+          // Trust Level Filtering
+          if (minLevel && !this._isLevelSufficient(attTags.lvl, minLevel)) continue;
+
+          if (this._isAttestationValid(att, attTags, revocations)) {
+            validAttestations.push({
+              pubkey: att.pubkey,
+              level: attTags.lvl,
+              eventId: att.id
+            });
+          }
         }
       }
-    }
 
-    if (requireAttestation && validAttestations.length === 0) {
-      throw new NCC02Error('POLICY_FAILURE', `No trusted attestations meet the required policy for ${serviceId}`);
+      if (requireAttestation && validAttestations.length === 0) {
+        throw new NCC02Error('POLICY_FAILURE', `No trusted attestations meet the required policy for ${serviceId}`);
+      }
     }
 
     return {