ncc-02-js 0.3.1 → 0.5.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).
@@ -2478,25 +2539,35 @@ var NCC02Builder = class {
    * @param {string} [options.endpoint] - The 'u' tag URI.
    * @param {string} [options.fingerprint] - The 'k' tag fingerprint.
    * @param {number} [options.expiryDays=14] - Expiry in days.
+   * @param {boolean} [options.isPrivate=false] - Whether the service is private (adds required `private` tag).
+   * @param {string[]} [options.privateRecipients] - Optional encrypted ciphertexts for authorized recipients.
    */
-  createServiceRecord(options) {
-    const { serviceId, endpoint, fingerprint, expiryDays = 14 } = options;
+  async createServiceRecord(options) {
+    const { serviceId, endpoint, fingerprint, expiryDays = 14, isPrivate = false, privateRecipients } = options;
     if (!serviceId) throw new Error("serviceId (d tag) is required");
+    if (typeof isPrivate !== "boolean") throw new Error("isPrivate must be a boolean value");
     const expiry = Math.floor(Date.now() / 1e3) + expiryDays * 24 * 60 * 60;
     const tags = [
       ["d", serviceId],
       ["exp", expiry.toString()]
     ];
+    tags.push(["private", isPrivate ? "true" : "false"]);
     if (endpoint) tags.push(["u", endpoint]);
     if (fingerprint) tags.push(["k", fingerprint]);
+    if (privateRecipients) {
+      if (!Array.isArray(privateRecipients)) throw new Error("privateRecipients must be an array");
+      privateRecipients.forEach((cipher) => {
+        if (typeof cipher !== "string") throw new Error("privateRecipients entries must be strings");
+        tags.push(["privateRecipients", cipher]);
+      });
+    }
     const event = {
       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 +2578,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 +2597,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 +2607,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 +2616,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) {
@@ -7626,6 +7703,136 @@ async function validateEvent22(event, url, method, body) {
   return true;
 }
 
+// src/privacy.js
+var PRIVATE_TAG = "private";
+var PRIVATE_RECIPIENTS_TAG = "privateRecipients";
+var HEX_REGEX = /^[0-9a-f]{64}$/i;
+function normalizeHexPubkey(value) {
+  if (typeof value !== "string") {
+    throw new Error("Pubkey must be a string");
+  }
+  const lower = value.toLowerCase();
+  if (HEX_REGEX.test(lower)) {
+    return lower;
+  }
+  try {
+    const decoded = nip19_exports.decode(value);
+    if (decoded.type === "npub" && typeof decoded.data === "string") {
+      return decoded.data.toLowerCase();
+    }
+  } catch {
+  }
+  throw new Error("Unsupported pubkey format");
+}
+function toNpub(hexPubkey) {
+  return nip19_exports.npubEncode(hexPubkey);
+}
+function toUint8ArrayKey(key) {
+  if (typeof key === "string") {
+    return hexToBytes2(key);
+  }
+  if (key instanceof Uint8Array) {
+    return key;
+  }
+  throw new Error("Private key must be a hex string or Uint8Array");
+}
+function createNip44Encryptor(owner) {
+  if (typeof owner === "string" || owner instanceof Uint8Array) {
+    const ownerKeyBytes = toUint8ArrayKey(owner);
+    return async (recipientHex, plaintext) => {
+      const conversationKey = nip44_exports.getConversationKey(ownerKeyBytes, recipientHex);
+      return nip44_exports.encrypt(plaintext, conversationKey);
+    };
+  }
+  if (owner && typeof owner === "object") {
+    if (typeof owner.nip44Encrypt === "function") {
+      const encryptFn = owner.nip44Encrypt.bind(owner);
+      return (recipientHex, plaintext) => Promise.resolve(encryptFn(recipientHex, plaintext));
+    }
+    if (owner.nip04 && typeof owner.nip04.encrypt === "function") {
+      const encryptFn = owner.nip04.encrypt.bind(owner.nip04);
+      return (recipientHex, plaintext) => Promise.resolve(encryptFn(recipientHex, plaintext));
+    }
+  }
+  throw new Error("Unsupported owner signer; must be private key or NIP-44/NIP-04 capable signer");
+}
+function createNip44Decryptor(recipient) {
+  if (typeof recipient === "string" || recipient instanceof Uint8Array) {
+    const recipientKeyBytes = toUint8ArrayKey(recipient);
+    return async (ownerHex, ciphertext) => {
+      const conversationKey = nip44_exports.getConversationKey(recipientKeyBytes, ownerHex);
+      return nip44_exports.decrypt(ciphertext, conversationKey);
+    };
+  }
+  if (recipient && typeof recipient === "object") {
+    if (typeof recipient.nip44Decrypt === "function") {
+      const decryptFn = recipient.nip44Decrypt.bind(recipient);
+      return (ownerHex, ciphertext) => Promise.resolve(decryptFn(ownerHex, ciphertext));
+    }
+    if (recipient.nip04 && typeof recipient.nip04.decrypt === "function") {
+      const decryptFn = recipient.nip04.decrypt.bind(recipient.nip04);
+      return (ownerHex, ciphertext) => Promise.resolve(decryptFn(ownerHex, ciphertext));
+    }
+  }
+  throw new Error("Unsupported recipient signer; must be private key or NIP-44/NIP-04 capable signer");
+}
+async function resolveRecipientPubkey(recipient) {
+  if (typeof recipient === "string" || recipient instanceof Uint8Array) {
+    return normalizeHexPubkey(getPublicKey(toUint8ArrayKey(recipient)));
+  }
+  if (recipient && typeof recipient.getPublicKey === "function") {
+    const pubkey = await recipient.getPublicKey();
+    return normalizeHexPubkey(pubkey);
+  }
+  throw new Error("Recipient must provide a private key or a NIP signer with getPublicKey()");
+}
+function parsePrivateFlag(tags) {
+  if (!Array.isArray(tags)) return null;
+  const tag = tags.find((t) => Array.isArray(t) && t[0] === PRIVATE_TAG);
+  if (!tag || typeof tag[1] !== "string") return null;
+  const normalized = tag[1].toLowerCase();
+  if (normalized === "true") return true;
+  if (normalized === "false") return false;
+  return null;
+}
+function collectPrivateRecipients(tags) {
+  if (!Array.isArray(tags)) return [];
+  return tags.filter((t) => Array.isArray(t) && t[0] === PRIVATE_RECIPIENTS_TAG && typeof t[1] === "string").map((t) => t[1]);
+}
+async function encryptPrivateRecipients(ownerPrivateKey, recipients) {
+  if (!Array.isArray(recipients)) {
+    throw new Error("recipients must be an array of pubkeys");
+  }
+  const encryptor = createNip44Encryptor(ownerPrivateKey);
+  const encrypted = [];
+  for (const recipient of recipients) {
+    const recipientHex = normalizeHexPubkey(recipient);
+    const recipientNpub = toNpub(recipientHex);
+    encrypted.push(await encryptor(recipientHex, recipientNpub));
+  }
+  return encrypted;
+}
+async function decryptPrivateRecipient(ciphertext, ownerPubkey, recipientPrivateKey) {
+  const ownerHex = normalizeHexPubkey(ownerPubkey);
+  const decryptor = createNip44Decryptor(recipientPrivateKey);
+  return decryptor(ownerHex, ciphertext);
+}
+async function isPrivateRecipientAuthorized(privateRecipients, ownerPubkey, recipientPrivateKey) {
+  if (!Array.isArray(privateRecipients) || privateRecipients.length === 0) return false;
+  const ownerHex = normalizeHexPubkey(ownerPubkey);
+  const recipientPubkey = await resolveRecipientPubkey(recipientPrivateKey);
+  const expectedNpub = toNpub(normalizeHexPubkey(recipientPubkey));
+  const decryptor = createNip44Decryptor(recipientPrivateKey);
+  for (const ciphertext of privateRecipients) {
+    try {
+      const decrypted = await decryptor(ownerHex, ciphertext);
+      if (decrypted === expectedNpub) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+
 // src/resolver.js
 var NCC02Error = class extends Error {
   /**
@@ -7685,6 +7892,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 +7922,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 +7931,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,18 +7941,18 @@ 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");
     }
     const serviceTags = Object.fromEntries(serviceEvent.tags);
     const now2 = Math.floor(Date.now() / 1e3);
+    const privateFlag = parsePrivateFlag(serviceEvent.tags);
+    if (privateFlag === null) {
+      throw new NCC02Error("MALFORMED_RECORD", "Service record is missing required tag (private)");
+    }
     if (!serviceTags.exp) {
       throw new NCC02Error("MALFORMED_RECORD", "Service record is missing required tag (exp)");
     }
@@ -7738,88 +7966,137 @@ 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,
+      isPrivate: privateFlag,
+      privateRecipients: collectPrivateRecipients(serviceEvent.tags),
       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[]>}
+   */
+  /**
+   * @param {any[]} revocations
+   * @returns {Record<string, any[]>}
    */
-  _isAttestationValid(att, tags, revocations) {
-    if (!verifyEvent2(att)) return false;
+  _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 +8153,12 @@ export {
   NCC02Builder,
   NCC02Error,
   NCC02Resolver,
+  collectPrivateRecipients,
+  decryptPrivateRecipient,
+  encryptPrivateRecipients,
+  isExpired,
+  isPrivateRecipientAuthorized,
+  parsePrivateFlag,
   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
@@ -25,13 +42,17 @@ export class NCC02Builder {
      * @param {string} [options.endpoint] - The 'u' tag URI.
      * @param {string} [options.fingerprint] - The 'k' tag fingerprint.
      * @param {number} [options.expiryDays=14] - Expiry in days.
+     * @param {boolean} [options.isPrivate=false] - Whether the service is private (adds required `private` tag).
+     * @param {string[]} [options.privateRecipients] - Optional encrypted ciphertexts for authorized recipients.
      */
     createServiceRecord(options: {
         serviceId: string;
         endpoint?: string;
         fingerprint?: string;
         expiryDays?: number;
-    }): import("nostr-tools/core").VerifiedEvent;
+        isPrivate?: boolean;
+        privateRecipients?: string[];
+    }): Promise<any>;
     /**
      * Creates a signed Certificate Attestation (Kind 30060).
      * @param {Object} options
@@ -47,7 +68,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 +78,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>;
+};