ncc-02-js 0.3.1 → 0.4.0

package/dist/index.mjs

@@ -2464,12 +2464,73 @@ var KINDS = {
 };
 var NCC02Builder = class {
   /**
-   * @param {string | Uint8Array} privateKey - The private key to sign events with.
+   * @param {string | Uint8Array | NostrSigner} signer - Raw private key or asynchronous signer.
    */
-  constructor(privateKey) {
-    if (!privateKey) throw new Error("Private key is required");
-    this.sk = typeof privateKey === "string" ? hexToBytes2(privateKey) : privateKey;
-    this.pk = getPublicKey(this.sk);
+  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 = void 0;
+  }
+  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}
+   */
+  _normalizeSigner(signer) {
+    if (typeof signer === "string" || signer instanceof Uint8Array) {
+      const privateKey = typeof signer === "string" ? hexToBytes2(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((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) : void 0
+        };
+      }
+    }
+    throw new Error("Unsupported signer provided to NCC02Builder");
   }
   /**
    * Creates a signed Service Record (Kind 30059).
@@ -2479,7 +2540,7 @@ var NCC02Builder = class {
    * @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");
     const expiry = Math.floor(Date.now() / 1e3) + expiryDays * 24 * 60 * 60;
@@ -2493,10 +2554,9 @@ var NCC02Builder = class {
       kind: KINDS.SERVICE_RECORD,
       created_at: Math.floor(Date.now() / 1e3),
       tags,
-      content: `NCC-02 Service Record for ${serviceId}`,
-      pubkey: this.pk
+      content: `NCC-02 Service Record for ${serviceId}`
     };
-    return finalizeEvent(event, this.sk);
+    return this._finalizeEvent(event);
   }
   /**
    * Creates a signed Certificate Attestation (Kind 30060).
@@ -2507,7 +2567,7 @@ var NCC02Builder = class {
    * @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");
@@ -2526,10 +2586,9 @@ var NCC02Builder = class {
         ["nbf", now2.toString()],
         ["exp", expiry.toString()]
       ],
-      content: "NCC-02 Attestation",
-      pubkey: this.pk
+      content: "NCC-02 Attestation"
     };
-    return finalizeEvent(event, this.sk);
+    return this._finalizeEvent(event);
   }
   /**
    * Creates a signed Revocation (Kind 30061).
@@ -2537,7 +2596,7 @@ var NCC02Builder = class {
    * @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");
     const tags = [["e", attestationId]];
@@ -2546,15 +2605,22 @@ var NCC02Builder = class {
       kind: KINDS.REVOCATION,
       created_at: Math.floor(Date.now() / 1e3),
       tags,
-      content: "NCC-02 Revocation",
-      pubkey: this.pk
+      content: "NCC-02 Revocation"
     };
-    return finalizeEvent(event, this.sk);
+    return this._finalizeEvent(event);
   }
 };
 function verifyNCC02Event(event) {
   return verifyEvent(event);
 }
+function isExpired(event) {
+  if (!event || !Array.isArray(event.tags)) return false;
+  const expTag = event.tags.find((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() / 1e3);
+}
 
 // node_modules/@scure/base/lib/esm/index.js
 function assertNumber(n) {
@@ -7685,6 +7751,27 @@ var NCC02Resolver = class {
       });
     });
   }
+  /**
+   * 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.
    * 
@@ -7694,8 +7781,8 @@ var NCC02Resolver = class {
    * @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 {
@@ -7703,9 +7790,9 @@ var NCC02Resolver = class {
       minLevel = null,
       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]
@@ -7713,13 +7800,9 @@ var NCC02Resolver = class {
     } catch (err) {
       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}`);
     }
-    const serviceEvent = serviceEvents.sort((a, b) => {
-      if (b.created_at !== a.created_at) return b.created_at - a.created_at;
-      return a.id.localeCompare(b.id);
-    })[0];
     if (!verifyEvent2(serviceEvent)) {
       throw new NCC02Error("INVALID_SIGNATURE", "Service record signature verification failed");
     }
@@ -7738,88 +7821,135 @@ var NCC02Resolver = class {
     if (exp < now2) {
       throw new NCC02Error("EXPIRED", "Service record has expired");
     }
-    const validAttestations = [];
-    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}`);
-      }
+    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 && 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) {
-    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);
+    let revocations = [];
+    if (attestationIds.length) {
+      revocations = await this._query({
+        kinds: [KINDS.REVOCATION],
+        "#e": attestationIds
+      });
+    }
+    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[]>}
    */
-  _isAttestationValid(att, tags, revocations) {
-    if (!verifyEvent2(att)) return false;
+  /**
+   * @param {any[]} revocations
+   * @returns {Record<string, any[]>}
+   */
+  _groupValidRevocations(revocations) {
+    const indexed = {};
+    for (const rev of revocations) {
+      if (!verifyEvent2(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 (!verifyEvent2(att)) return { valid: false, revoked: false };
     const now2 = Math.floor(Date.now() / 1e3);
     if (tags.nbf) {
-      const nbf = parseInt(tags.nbf);
-      if (isNaN(nbf) || nbf > now2) return false;
+      const nbf = parseInt(tags.nbf, 10);
+      if (isNaN(nbf) || nbf > now2) return { valid: false, revoked: false };
     }
     if (tags.exp) {
-      const exp = parseInt(tags.exp);
-      if (isNaN(exp) || exp < now2) return false;
+      const exp = parseInt(tags.exp, 10);
+      if (isNaN(exp) || exp < now2) return { valid: false, revoked: false };
     }
-    for (const rev of revocations) {
-      const revTags = Object.fromEntries(rev.tags);
-      if (revTags.e === att.id && rev.pubkey === att.pubkey) {
-        if (verifyEvent2(rev)) {
-          return false;
-        }
-      }
-    }
-    return true;
+    return { valid: true, revoked: false };
+  }
+  /**
+   * @param {string | undefined} actual 
+   * @param {string} required 
+   */
+  _isLevelSufficient(actual, required) {
+    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}
    */
@@ -7876,6 +8006,7 @@ export {
   NCC02Builder,
   NCC02Error,
   NCC02Resolver,
+  isExpired,
   verifyNCC02Event
 };
 /*! Bundled license information:

package/dist/models.d.ts

@@ -3,6 +3,12 @@
  * @param {any} event
  */
 export function verifyNCC02Event(event: any): event is import("nostr-tools/core").VerifiedEvent;
+/**
+ * Checks whether an NCC event has expired based on its 'exp' tag.
+ * @param {any} event
+ * @returns {boolean}
+ */
+export function isExpired(event: any): boolean;
 export namespace KINDS {
     let SERVICE_RECORD: number;
     let ATTESTATION: number;
@@ -13,11 +19,22 @@ export namespace 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: string | Uint8Array | NostrSigner);
+    signer: NostrSigner;
+    _pubkeyPromise: Promise<string>;
+    _pubkey: string;
+    _getPublicKey(): Promise<string>;
+    /**
+     * @param {any} event
+     */
+    _finalizeEvent(event: any): Promise<any>;
+    /**
+     * @param {any} signer
+     * @returns {NostrSigner}
      */
-    constructor(privateKey: string | Uint8Array);
-    sk: Uint8Array<ArrayBufferLike>;
-    pk: string;
+    _normalizeSigner(signer: any): NostrSigner;
     /**
      * Creates a signed Service Record (Kind 30059).
      * @param {Object} options
@@ -31,7 +48,7 @@ export class NCC02Builder {
         endpoint?: string;
         fingerprint?: string;
         expiryDays?: number;
-    }): import("nostr-tools/core").VerifiedEvent;
+    }): Promise<any>;
     /**
      * Creates a signed Certificate Attestation (Kind 30060).
      * @param {Object} options
@@ -47,7 +64,7 @@ export class NCC02Builder {
         serviceEventId: string;
         level?: string;
         validDays?: number;
-    }): import("nostr-tools/core").VerifiedEvent;
+    }): Promise<any>;
     /**
      * Creates a signed Revocation (Kind 30061).
      * @param {Object} options
@@ -57,5 +74,10 @@ export class NCC02Builder {
     createRevocation(options: {
         attestationId: string;
         reason?: string;
-    }): import("nostr-tools/core").VerifiedEvent;
+    }): Promise<any>;
 }
+export type NostrSigner = {
+    getPublicKey: () => Promise<string>;
+    signEvent: (event: any) => Promise<any>;
+    decryptEvent?: (event: any) => Promise<any>;
+};

package/dist/resolver.d.ts

@@ -12,13 +12,16 @@ export class NCC02Error extends Error {
     cause: any;
 }
 /**
- * @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.
@@ -52,6 +55,18 @@ export class NCC02Resolver {
      * @returns {Promise<import('nostr-tools').Event[]>}
      */
     _query(filter: import("nostr-tools").Filter): Promise<import("nostr-tools").Event[]>;
+    /**
+     * 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: import("nostr-tools").Event[]): import("nostr-tools").Event | null;
+    /**
+     * Query helper that returns only the freshest event matching the filter.
+     * @param {import('nostr-tools').Filter} filter
+     * @returns {Promise<import('nostr-tools').Event | null>}
+     */
+    _queryFreshest(filter: import("nostr-tools").Filter): Promise<import("nostr-tools").Event | null>;
     /**
      * Resolves a service for a given pubkey and service identifier.
      *
@@ -61,41 +76,86 @@ 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.
      */
     resolve(pubkey: string, serviceId: string, options?: {
         requireAttestation?: boolean;
         minLevel?: string;
         standard?: string;
-    }): Promise<ResolvedService>;
+    }): Promise<ServiceStatus>;
     /**
-     * @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
+     */
+    _buildTrustData(serviceEvent: any, options: {
+        pubkey: string;
+        serviceId: string;
+        standard: string | null;
+        minLevel: string | null;
+    }): Promise<{
+        validAttestations: {
+            pubkey: string;
+            level: any;
+            eventId: string;
+        }[];
+        isRevoked: boolean;
+    }>;
+    /**
+     * @param {any[]} revocations
+     * @returns {Record<string, any[]>}
      */
-    _isLevelSufficient(actual: string | undefined, required: string): boolean;
+    /**
+     * @param {any[]} revocations
+     * @returns {Record<string, any[]>}
+     */
+    _groupValidRevocations(revocations: any[]): Record<string, any[]>;
     /**
      * @param {any} att
-     * @param {any} tags
+     * @param {Record<string, string>} tags
      * @param {any[]} revocations
      */
-    _isAttestationValid(att: any, tags: any, revocations: any[]): boolean;
+    /**
+     * @param {any} att
+     * @param {Record<string, string>} tags
+     * @param {any[]} [revocations]
+     */
+    _evaluateAttestation(att: any, tags: Record<string, string>, revocations?: any[]): {
+        valid: boolean;
+        revoked: boolean;
+    };
+    /**
+     * @param {string | undefined} actual
+     * @param {string} required
+     */
+    _isLevelSufficient(actual: string | undefined, required: string): boolean;
     /**
      * 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}
      */
-    verifyEndpoint(resolved: ResolvedService, actualFingerprint: string): boolean;
+    verifyEndpoint(resolved: ServiceStatus, actualFingerprint: string): boolean;
 }
-export type ResolvedService = {
+export type ServiceStatus = {
     endpoint: string | undefined;
     fingerprint: string | undefined;
     expiry: number;
-    attestations: any[];
+    isRevoked: boolean;
+    attestationCount: number;
+    attestations: Array<{
+        eventId: string;
+        level: string;
+        pubkey: string;
+    }>;
     eventId: string;
     pubkey: string;
+    serviceEvent: any;
 };
 import { SimplePool } from 'nostr-tools';

package/package.json

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