ncc-02-js 0.3.1 → 0.4.0

package/src/models.js

@@ -1,6 +1,13 @@
 import { finalizeEvent, verifyEvent, getPublicKey } from 'nostr-tools/pure';
 import { hexToBytes } from 'nostr-tools/utils';
 
+/**
+ * @typedef {Object} NostrSigner
+ * @property {() => Promise<string>} getPublicKey
+ * @property {(event: any) => Promise<any>} signEvent
+ * @property {(event: any) => Promise<any>} [decryptEvent]
+ */
+
 /**
  * NCC-02 Nostr Event Kinds
  */
@@ -15,12 +22,78 @@ export const KINDS = {
  */
 export class NCC02Builder {
   /**
-   * @param {string | Uint8Array} privateKey - The private key to sign events with.
+   * @param {string | Uint8Array | NostrSigner} signer - Raw private key or asynchronous signer.
+   */
+  constructor(signer) {
+    if (!signer) throw new Error('Signer or private key is required');
+    this.signer = this._normalizeSigner(signer);
+    this._pubkeyPromise = this.signer.getPublicKey();
+    this._pubkey = undefined;
+  }
+
+  async _getPublicKey() {
+    if (!this._pubkey) {
+      this._pubkey = await this._pubkeyPromise;
+    }
+    return this._pubkey;
+  }
+
+  /**
+   * @param {any} event
+   */
+  async _finalizeEvent(event) {
+    const pubkey = await this._getPublicKey();
+    const eventWithPubkey = { ...event, pubkey };
+    const signed = await this.signer.signEvent(eventWithPubkey);
+    if (!signed || typeof signed.id !== 'string' || typeof signed.sig !== 'string') {
+      throw new Error('Signer must return a signed event with id and sig');
+    }
+    return signed;
+  }
+
+  /**
+   * @param {any} signer
+   * @returns {NostrSigner}
    */
-  constructor(privateKey) {
-    if (!privateKey) throw new Error('Private key is required');
-    this.sk = typeof privateKey === 'string' ? hexToBytes(privateKey) : privateKey;
-    this.pk = getPublicKey(this.sk);
+  _normalizeSigner(signer) {
+    if (typeof signer === 'string' || signer instanceof Uint8Array) {
+      const privateKey = typeof signer === 'string' ? hexToBytes(signer) : signer;
+      const pubkey = getPublicKey(privateKey);
+      return {
+        getPublicKey: async () => pubkey,
+        /** @param {any} event */
+        signEvent: async (event) => {
+          const clonedEvent = {
+            ...event,
+            tags: Array.isArray(event.tags) ? event.tags.map((/** @type {any[]} */ tag) => [...tag]) : []
+          };
+          return finalizeEvent(clonedEvent, privateKey);
+        }
+      };
+    }
+
+    if (typeof signer === 'object' && signer !== null) {
+      if (typeof signer.getPublicKey === 'function' && typeof signer.signEvent === 'function') {
+        return {
+          getPublicKey: async () => {
+            const pubkey = await signer.getPublicKey();
+            if (typeof pubkey !== 'string') throw new Error('Signer.getPublicKey must return a hex string');
+            return pubkey;
+          },
+          /** @param {any} event */
+          signEvent: async (event) => {
+            const signed = await signer.signEvent(event);
+            if (!signed || typeof signed.id !== 'string' || typeof signed.sig !== 'string') {
+              throw new Error('Signer.signEvent must return a signed event');
+            }
+            return signed;
+          },
+          decryptEvent: typeof signer.decryptEvent === 'function' ? signer.decryptEvent.bind(signer) : undefined
+        };
+      }
+    }
+
+    throw new Error('Unsupported signer provided to NCC02Builder');
   }
 
   /**
@@ -31,7 +104,7 @@ export class NCC02Builder {
    * @param {string} [options.fingerprint] - The 'k' tag fingerprint.
    * @param {number} [options.expiryDays=14] - Expiry in days.
    */
-  createServiceRecord(options) {
+  async createServiceRecord(options) {
     const { serviceId, endpoint, fingerprint, expiryDays = 14 } = options;
     if (!serviceId) throw new Error('serviceId (d tag) is required');
 
@@ -40,17 +113,16 @@ export class NCC02Builder {
       ['d', serviceId],
       ['exp', expiry.toString()]
     ];
-    if(endpoint) tags.push(['u', endpoint]);
-    if(fingerprint) tags.push(['k', fingerprint]);
+    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: tags,
-      content: `NCC-02 Service Record for ${serviceId}`,
-      pubkey: this.pk
+      tags,
+      content: `NCC-02 Service Record for ${serviceId}`
     };
-    return finalizeEvent(event, this.sk);
+    return this._finalizeEvent(event);
   }
 
   /**
@@ -62,7 +134,7 @@ export class NCC02Builder {
    * @param {string} [options.level='verified'] - The 'lvl' tag level.
    * @param {number} [options.validDays=30] - Validity in days.
    */
-  createAttestation(options) {
+  async createAttestation(options) {
     const { subjectPubkey, serviceId, serviceEventId, level = 'verified', validDays = 30 } = options;
     if (!subjectPubkey) throw new Error('subjectPubkey is required');
     if (!serviceId) throw new Error('serviceId is required');
@@ -82,10 +154,9 @@ export class NCC02Builder {
         ['nbf', now.toString()],
         ['exp', expiry.toString()]
       ],
-      content: 'NCC-02 Attestation',
-      pubkey: this.pk
+      content: 'NCC-02 Attestation'
     };
-    return finalizeEvent(event, this.sk);
+    return this._finalizeEvent(event);
   }
 
   /**
@@ -94,7 +165,7 @@ export class NCC02Builder {
    * @param {string} options.attestationId - The 'e' tag referencing the attestation.
    * @param {string} [options.reason=''] - Optional reason.
    */
-  createRevocation(options) {
+  async createRevocation(options) {
     const { attestationId, reason = '' } = options;
     if (!attestationId) throw new Error('attestationId (e tag) is required');
 
@@ -104,11 +175,10 @@ export class NCC02Builder {
     const event = {
       kind: KINDS.REVOCATION,
       created_at: Math.floor(Date.now() / 1000),
-      tags: tags,
-      content: 'NCC-02 Revocation',
-      pubkey: this.pk
+      tags,
+      content: 'NCC-02 Revocation'
     };
-    return finalizeEvent(event, this.sk);
+    return this._finalizeEvent(event);
   }
 }
 
@@ -119,3 +189,17 @@ export class NCC02Builder {
 export function verifyNCC02Event(event) {
   return verifyEvent(event);
 }
+
+/**
+ * Checks whether an NCC event has expired based on its 'exp' tag.
+ * @param {any} event
+ * @returns {boolean}
+ */
+export function isExpired(event) {
+  if (!event || !Array.isArray(event.tags)) return false;
+  const expTag = event.tags.find((/** @type {any[]} */ tag) => tag[0] === 'exp');
+  if (!expTag) return false;
+  const expiry = parseInt(expTag[1], 10);
+  if (Number.isNaN(expiry)) return false;
+  return expiry <= Math.floor(Date.now() / 1000);
+}

package/src/resolver.js

@@ -18,15 +18,17 @@ export class NCC02Error extends Error {
 }
 
 /**
- * @typedef {Object} ResolvedService
+ * @typedef {Object} ServiceStatus
  * @property {string|undefined} endpoint
  * @property {string|undefined} fingerprint
  * @property {number} expiry
- * @property {any[]} attestations
+ * @property {boolean} isRevoked
+ * @property {number} attestationCount
+ * @property {Array<{eventId:string, level:string, pubkey:string}>} attestations
  * @property {string} eventId
  * @property {string} pubkey
+ * @property {any} serviceEvent
  */
-
 /**
  * Resolver for NCC-02 Service Records.
  * Implements the client-side resolution and trust verification algorithm.
@@ -78,6 +80,29 @@ export class NCC02Resolver {
     });
   }
 
+  /**
+   * Returns the first event sorted by freshness (newest created_at, tie broken by id).
+   * @param {import('nostr-tools').Event[]} events
+   * @returns {import('nostr-tools').Event|null}
+   */
+  _freshestEvent(events) {
+    if (!events || !events.length) return null;
+    return events.sort((a, b) => {
+      if (b.created_at !== a.created_at) return b.created_at - a.created_at;
+      return a.id.localeCompare(b.id);
+    })[0];
+  }
+
+  /**
+   * Query helper that returns only the freshest event matching the filter.
+   * @param {import('nostr-tools').Filter} filter
+   * @returns {Promise<import('nostr-tools').Event | null>}
+   */
+  async _queryFreshest(filter) {
+    const events = await this._query(filter);
+    return this._freshestEvent(events);
+  }
+
   /**
    * Resolves a service for a given pubkey and service identifier.
    * 
@@ -87,8 +112,8 @@ export class NCC02Resolver {
    * @param {boolean} [options.requireAttestation=false] - If true, fails if no trusted attestation is found.
    * @param {string} [options.minLevel=null] - Minimum trust level ('self', 'verified', 'hardened').
    * @param {string} [options.standard='nostr-service-trust-v0.1'] - Expected trust standard.
-   * @throws {NCC02Error} If verification or policy checks fail.
-   * @returns {Promise<ResolvedService>} The verified service details.
+  * @throws {NCC02Error} If verification or policy checks fail.
+  * @returns {Promise<ServiceStatus>} The service status including trust metadata.
    */
   async resolve(pubkey, serviceId, options = {}) {
     const { 
@@ -97,9 +122,9 @@ export class NCC02Resolver {
       standard = 'nostr-service-trust-v0.1'
     } = options;
 
-    let serviceEvents;
+    let serviceEvent;
     try {
-      serviceEvents = await this._query({
+      serviceEvent = await this._queryFreshest({
         kinds: [KINDS.SERVICE_RECORD],
         authors: [pubkey],
         '#d': [serviceId]
@@ -108,16 +133,10 @@ export class NCC02Resolver {
       throw new NCC02Error('RELAY_ERROR', `Failed to query relay for ${serviceId}`, err);
     }
 
-    if (!serviceEvents || !serviceEvents.length) {
+    if (!serviceEvent) {
       throw new NCC02Error('NOT_FOUND', `No service record found for ${serviceId}`);
     }
 
-    // Stable tie-breaking: Sort by created_at DESC, then ID ASC
-    const serviceEvent = serviceEvents.sort((/** @type {any} */ a, /** @type {any} */ b) => {
-      if (b.created_at !== a.created_at) return b.created_at - a.created_at;
-      return a.id.localeCompare(b.id);
-    })[0];
-
     if (!verifyEvent(serviceEvent)) {
       throw new NCC02Error('INVALID_SIGNATURE', 'Service record signature verification failed');
     }
@@ -143,112 +162,158 @@ export class NCC02Resolver {
       throw new NCC02Error('EXPIRED', 'Service record has expired');
     }
 
-    const validAttestations = [];
-
-    // 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
-            });
-          }
-        }
-      }
+    let trustData;
+    try {
+      trustData = await this._buildTrustData(serviceEvent, { pubkey, serviceId, standard, minLevel });
+    } catch (err) {
+      throw new NCC02Error('RELAY_ERROR', 'Failed to query relay for attestations/revocations', err);
+    }
 
-      if (requireAttestation && validAttestations.length === 0) {
-        throw new NCC02Error('POLICY_FAILURE', `No trusted attestations meet the required policy for ${serviceId}`);
-      }
+    if (requireAttestation && trustData.validAttestations.length === 0) {
+      throw new NCC02Error('POLICY_FAILURE', `No trusted attestations meet the required policy for ${serviceId}`);
     }
 
     return {
       endpoint: serviceTags.u,
       fingerprint: serviceTags.k,
       expiry: exp,
-      attestations: validAttestations,
+      attestations: trustData.validAttestations,
+      attestationCount: trustData.validAttestations.length,
+      isRevoked: trustData.isRevoked,
       eventId: serviceEvent.id,
-      pubkey: serviceEvent.pubkey
+      pubkey: serviceEvent.pubkey,
+      serviceEvent
     };
   }
 
   /**
-   * @param {string | undefined} actual 
-   * @param {string} required 
+   * @param {any} serviceEvent
+   * @param {Object} options
+   * @param {string} options.pubkey
+   * @param {string} options.serviceId
+   * @param {string|null} options.standard
+   * @param {string|null} options.minLevel
    */
-  _isLevelSufficient(actual, required) {
-    /** @type {Record<string, number>} */
-    const levels = { 'self': 0, 'verified': 1, 'hardened': 2 };
-    const actualVal = actual ? (levels[actual] ?? -1) : -1;
-    const requiredVal = levels[required] ?? 0;
-    return actualVal >= requiredVal;
+  async _buildTrustData(serviceEvent, options) {
+    const attestations = await this._query({
+      kinds: [KINDS.ATTESTATION],
+      '#e': [serviceEvent.id]
+    });
+
+    const attestationIds = attestations.map(att => att.id);
+    /** @type {any[]} */
+    let revocations = [];
+    if (attestationIds.length) {
+      revocations = await this._query({
+        kinds: [KINDS.REVOCATION],
+        '#e': attestationIds
+      });
+    }
+
+    /** @type {Record<string, any[]>} */
+    const revocationIndex = this._groupValidRevocations(revocations);
+    const validAttestations = [];
+    let isRevoked = false;
+
+    for (const att of attestations) {
+      if (!this.trustedCAPubkeys.has(att.pubkey)) continue;
+      const attTags = Object.fromEntries(att.tags);
+      if (attTags.subj !== options.pubkey) continue;
+      if (attTags.srv !== options.serviceId) continue;
+      if (options.standard && attTags.std !== options.standard) continue;
+
+      const { valid, revoked } = this._evaluateAttestation(att, attTags, revocationIndex[att.id]);
+      if (revoked) {
+        isRevoked = true;
+        continue;
+      }
+      if (!valid) continue;
+
+      if (options.minLevel && !this._isLevelSufficient(attTags.lvl, options.minLevel)) continue;
+
+      validAttestations.push({
+        pubkey: att.pubkey,
+        level: attTags.lvl,
+        eventId: att.id
+      });
+    }
+
+    return { validAttestations, isRevoked };
   }
 
   /**
-   * @param {any} att 
-   * @param {any} tags 
-   * @param {any[]} revocations 
+   * @param {any[]} revocations
+   * @returns {Record<string, any[]>}
+   */
+  /**
+   * @param {any[]} revocations
+   * @returns {Record<string, any[]>}
    */
-  _isAttestationValid(att, tags, revocations) {
-    // 1. Verify Attestation signature
-    if (!verifyEvent(att)) return false;
+  _groupValidRevocations(revocations) {
+    /** @type {Record<string, any[]>} */
+    const indexed = {};
+    for (const rev of revocations) {
+      if (!verifyEvent(rev)) continue;
+      const tags = Object.fromEntries(rev.tags);
+      const targetId = tags.e;
+      if (!targetId) continue;
+      if (!indexed[targetId]) indexed[targetId] = [];
+      indexed[targetId].push(rev);
+    }
+    return indexed;
+  }
+
+  /**
+   * @param {any} att
+   * @param {Record<string, string>} tags
+   * @param {any[]} revocations
+   */
+  /**
+   * @param {any} att
+   * @param {Record<string, string>} tags
+   * @param {any[]} [revocations]
+   */
+  _evaluateAttestation(att, tags, revocations = []) {
+    for (const rev of revocations) {
+      if (rev.pubkey === att.pubkey) {
+        return { valid: false, revoked: true };
+      }
+    }
+
+    if (!verifyEvent(att)) return { valid: false, revoked: false };
 
     const now = Math.floor(Date.now() / 1000);
-    
-    // 2. NBF validation
+
     if (tags.nbf) {
-      const nbf = parseInt(tags.nbf);
-      if (isNaN(nbf) || nbf > now) return false;
+      const nbf = parseInt(tags.nbf, 10);
+      if (isNaN(nbf) || nbf > now) return { valid: false, revoked: false };
     }
 
-    // 3. EXP validation
     if (tags.exp) {
-      const exp = parseInt(tags.exp);
-      if (isNaN(exp) || exp < now) return false;
+      const exp = parseInt(tags.exp, 10);
+      if (isNaN(exp) || exp < now) return { valid: false, revoked: false };
     }
 
-    // 4. Revocation validation
-    // A revocation is valid only if it matches the attestation ID, is from the same CA, AND has a valid signature.
-    for (const rev of revocations) {
-      const revTags = Object.fromEntries(rev.tags);
-      if (revTags.e === att.id && rev.pubkey === att.pubkey) {
-        if (verifyEvent(rev)) {
-          return false; // Valid revocation found
-        }
-      }
-    }
+    return { valid: true, revoked: false };
+  }
 
-    return true; // No valid revocation found
+  /**
+   * @param {string | undefined} actual 
+   * @param {string} required 
+   */
+  _isLevelSufficient(actual, required) {
+    /** @type {Record<string, number>} */
+    const levels = { 'self': 0, 'verified': 1, 'hardened': 2 };
+    const actualVal = actual ? (levels[actual] ?? -1) : -1;
+    const requiredVal = levels[required] ?? 0;
+    return actualVal >= requiredVal;
   }
 
   /**
    * Verifies that the actual fingerprint found during transport-level connection
    * matches the one declared in the signed service record.
    * 
-   * @param {ResolvedService} resolved - The object returned by resolve().
+   * @param {ServiceStatus} resolved - The object returned by resolve().
    * @param {string} actualFingerprint - The fingerprint obtained from the service.
    * @returns {boolean}
    */