ncc-02-js 0.4.0 → 0.5.0

package/README.md

@@ -10,6 +10,7 @@ This library provides tools for service owners to publish records and for client
 - **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.
+- **Privacy Controls**: Required `private` tags and optional encrypted `privateRecipients` listings let you declare visibility and invite-only recipients.
 - **Fail-Closed**: Explicit error reporting for policy or verification failures.
 
 ## Installation
@@ -78,6 +79,9 @@ await builder.createRevocation({
 
 The builder helpers emit the expected NCC-02 event kinds: Kind 30059 for service records, 30060 for attestations, and 30061 for revocations. `createServiceRecord` always includes the `d` and `exp` tags while optionally populating `u` and `k`. Attestations include `subj`, `srv`, `e`, `std`, `lvl`, `nbf`, and `exp`. Revocations only need the `e` tag and an optional reason. You can supply either a raw private key (hex string or `Uint8Array`) or a signer implementing `getPublicKey`/`signEvent`.
 
+#### Private Service Metadata
+Service records now require a boolean `private` tag (set via `isPrivate` when calling `createServiceRecord`). When private services should only be used by a curated set of users, you can provide pre-encrypted `privateRecipients` values that contain authorized `npub` identifiers. The helper utilities derive NIP-44 conversation keys: `await encryptPrivateRecipients(ownerPrivateKey, recipients)` when publishing so each recipient gets a ciphertext they can decrypt, and `await isPrivateRecipientAuthorized(privateRecipients, ownerPubkey, recipientPrivateKey)` on the client-side to verify if the signed-in key is on the allowlist (or `await decryptPrivateRecipient(...)` if you need the raw `npub`). The helpers accept either raw private keys or NIP-07/NIP-46 style signer objects (they will call `nip44Encrypt/nip44Decrypt` or fall back to legacy `nip04` if present). The resolver surfaces `isPrivate` and `privateRecipients` on the returned `ServiceStatus`.
+
 ### 3. Trust Model & Security
 
 The resolver treats the service owner’s pubkey as the root authority. Certificates and revocations are additive layers that you opt into via `requireAttestation` or `minLevel`. Validation failures surface as `NCC02Error` instances with codes such as `INVALID_SIGNATURE`, `EXPIRED`, or `POLICY_FAILURE`, helping clients react instead of defaulting to insecure fallbacks.

package/dist/index.cjs

@@ -34,7 +34,12 @@ __export(index_exports, {
   NCC02Builder: () => NCC02Builder,
   NCC02Error: () => NCC02Error,
   NCC02Resolver: () => NCC02Resolver,
+  collectPrivateRecipients: () => collectPrivateRecipients,
+  decryptPrivateRecipient: () => decryptPrivateRecipient,
+  encryptPrivateRecipients: () => encryptPrivateRecipients,
   isExpired: () => isExpired,
+  isPrivateRecipientAuthorized: () => isPrivateRecipientAuthorized,
+  parsePrivateFlag: () => parsePrivateFlag,
   verifyNCC02Event: () => verifyNCC02Event
 });
 module.exports = __toCommonJS(index_exports);
@@ -2574,17 +2579,28 @@ 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.
    */
   async createServiceRecord(options) {
-    const { serviceId, endpoint, fingerprint, expiryDays = 14 } = 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),
@@ -7727,6 +7743,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 {
   /**
@@ -7843,6 +7989,10 @@ var NCC02Resolver = class {
     }
     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)");
     }
@@ -7872,6 +8022,8 @@ var NCC02Resolver = class {
       attestations: trustData.validAttestations,
       attestationCount: trustData.validAttestations.length,
       isRevoked: trustData.isRevoked,
+      isPrivate: privateFlag,
+      privateRecipients: collectPrivateRecipients(serviceEvent.tags),
       eventId: serviceEvent.id,
       pubkey: serviceEvent.pubkey,
       serviceEvent
@@ -8042,7 +8194,12 @@ var MockRelay = class {
   NCC02Builder,
   NCC02Error,
   NCC02Resolver,
+  collectPrivateRecipients,
+  decryptPrivateRecipient,
+  encryptPrivateRecipients,
   isExpired,
+  isPrivateRecipientAuthorized,
+  parsePrivateFlag,
   verifyNCC02Event
 });
 /*! Bundled license information:

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./models.js";
 export * from "./resolver.js";
 export * from "./mockRelay.js";
+export * from "./privacy.js";

package/dist/index.mjs

@@ -2539,17 +2539,28 @@ 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.
    */
   async createServiceRecord(options) {
-    const { serviceId, endpoint, fingerprint, expiryDays = 14 } = 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),
@@ -7692,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 {
   /**
@@ -7808,6 +7949,10 @@ var NCC02Resolver = class {
     }
     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)");
     }
@@ -7837,6 +7982,8 @@ var NCC02Resolver = class {
       attestations: trustData.validAttestations,
       attestationCount: trustData.validAttestations.length,
       isRevoked: trustData.isRevoked,
+      isPrivate: privateFlag,
+      privateRecipients: collectPrivateRecipients(serviceEvent.tags),
       eventId: serviceEvent.id,
       pubkey: serviceEvent.pubkey,
       serviceEvent
@@ -8006,7 +8153,12 @@ export {
   NCC02Builder,
   NCC02Error,
   NCC02Resolver,
+  collectPrivateRecipients,
+  decryptPrivateRecipient,
+  encryptPrivateRecipients,
   isExpired,
+  isPrivateRecipientAuthorized,
+  parsePrivateFlag,
   verifyNCC02Event
 };
 /*! Bundled license information:

package/dist/models.d.ts

@@ -42,12 +42,16 @@ 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;
+        isPrivate?: boolean;
+        privateRecipients?: string[];
     }): Promise<any>;
     /**
      * Creates a signed Certificate Attestation (Kind 30060).

package/dist/privacy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Parse the required `private` tag from an event.
+ * @param {any[]} tags
+ * @returns {boolean | null}
+ */
+export function parsePrivateFlag(tags: any[]): boolean | null;
+/**
+ * Extract all `privateRecipients` ciphertext values from an event.
+ * @param {any[]} tags
+ * @returns {string[]}
+ */
+export function collectPrivateRecipients(tags: any[]): string[];
+/**
+ * Encrypt a list of recipient pubkeys so they can be published in a service record.
+ * @param {string | Uint8Array | NipSigner} ownerPrivateKey
+ * @param {string[]} recipients
+ * @returns {Promise<string[]>}
+ */
+export function encryptPrivateRecipients(ownerPrivateKey: string | Uint8Array | NipSigner, recipients: string[]): Promise<string[]>;
+/**
+ * Decrypt a single private recipient ciphertext.
+ * @param {string} ciphertext
+ * @param {string} ownerPubkey
+ * @param {string | Uint8Array | NipSigner} recipientPrivateKey
+ * @returns {Promise<string>}
+ */
+export function decryptPrivateRecipient(ciphertext: string, ownerPubkey: string, recipientPrivateKey: string | Uint8Array | NipSigner): Promise<string>;
+/**
+ * Check whether the provided private key matches one of the encrypted recipients.
+ * @param {string[]} privateRecipients
+ * @param {string} ownerPubkey
+ * @param {string | Uint8Array | NipSigner} recipientPrivateKey
+ * @returns {Promise<boolean>}
+ */
+export function isPrivateRecipientAuthorized(privateRecipients: string[], ownerPubkey: string, recipientPrivateKey: string | Uint8Array | NipSigner): Promise<boolean>;
+export type NipSigner = {
+    nip44Encrypt?: (thirdPartyPubkey: string, plaintext: string) => Promise<string> | string;
+    nip44Decrypt?: (ownerPubkey: string, ciphertext: string) => Promise<string> | string;
+    nip04?: {
+        encrypt: (thirdPartyPubkey: string, plaintext: string) => Promise<string> | string;
+        decrypt: (ownerPubkey: string, ciphertext: string) => Promise<string> | string;
+    };
+    getPublicKey?: () => Promise<string> | string;
+};

package/dist/resolver.d.ts

@@ -22,6 +22,8 @@ export class NCC02Error extends Error {
  * @property {string} eventId
  * @property {string} pubkey
  * @property {any} serviceEvent
+ * @property {boolean} isPrivate
+ * @property {string[]} privateRecipients
  */
 /**
  * Resolver for NCC-02 Service Records.
@@ -157,5 +159,7 @@ export type ServiceStatus = {
     eventId: string;
     pubkey: string;
     serviceEvent: any;
+    isPrivate: boolean;
+    privateRecipients: string[];
 };
 import { SimplePool } from 'nostr-tools';

package/package.json

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

package/src/index.js

@@ -1,3 +1,4 @@
 export * from './models.js';
 export * from './resolver.js';
 export * from './mockRelay.js';
+export * from './privacy.js';

package/src/models.js

@@ -103,18 +103,29 @@ 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.
    */
   async createServiceRecord(options) {
-    const { serviceId, endpoint, fingerprint, expiryDays = 14 } = 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() / 1000) + (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,

package/src/privacy.js

@@ -0,0 +1,217 @@
+import { nip19, nip44 } from 'nostr-tools';
+import { hexToBytes } from 'nostr-tools/utils';
+import { getPublicKey } from 'nostr-tools/pure';
+
+const PRIVATE_TAG = 'private';
+const PRIVATE_RECIPIENTS_TAG = 'privateRecipients';
+const HEX_REGEX = /^[0-9a-f]{64}$/i;
+
+/**
+ * @typedef {Object} NipSigner
+ * @property {(thirdPartyPubkey: string, plaintext: string) => Promise<string> | string} [nip44Encrypt]
+ * @property {(ownerPubkey: string, ciphertext: string) => Promise<string> | string} [nip44Decrypt]
+ * @property {{encrypt: (thirdPartyPubkey: string, plaintext: string) => Promise<string> | string, decrypt: (ownerPubkey: string, ciphertext: string) => Promise<string> | string}} [nip04]
+ * @property {() => Promise<string> | string} [getPublicKey]
+ */
+
+/**
+ * Normalize a pubkey string (hex or npub) into a lowercase hex string.
+ * @param {string} value
+ * @returns {string}
+ */
+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.decode(value);
+    if (decoded.type === 'npub' && typeof decoded.data === 'string') {
+      return decoded.data.toLowerCase();
+    }
+  } catch {
+    /** fall through */
+  }
+  throw new Error('Unsupported pubkey format');
+}
+
+/**
+ * Convert a lowercase hex pubkey into a canonical npub value.
+ * @param {string} hexPubkey
+ * @returns {string}
+ */
+function toNpub(hexPubkey) {
+  return nip19.npubEncode(hexPubkey);
+}
+
+/**
+ * Ensure we work with Uint8Array private keys for NIP-44 helpers.
+ * @param {string|Uint8Array} key
+ * @returns {Uint8Array}
+ */
+function toUint8ArrayKey(key) {
+  if (typeof key === 'string') {
+    return hexToBytes(key);
+  }
+  if (key instanceof Uint8Array) {
+    return key;
+  }
+  throw new Error('Private key must be a hex string or Uint8Array');
+}
+
+/**
+ * @param {string | Uint8Array | NipSigner} owner
+ * @returns {(recipientHex: string, plaintext: string) => Promise<string>}
+ */
+function createNip44Encryptor(owner) {
+  if (typeof owner === 'string' || owner instanceof Uint8Array) {
+    const ownerKeyBytes = toUint8ArrayKey(owner);
+    return async (recipientHex, plaintext) => {
+      const conversationKey = nip44.getConversationKey(ownerKeyBytes, recipientHex);
+      return nip44.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');
+}
+
+/**
+ * @param {string | Uint8Array | NipSigner} recipient
+ * @returns {(ownerHex: string, ciphertext: string) => Promise<string>}
+ */
+function createNip44Decryptor(recipient) {
+  if (typeof recipient === 'string' || recipient instanceof Uint8Array) {
+    const recipientKeyBytes = toUint8ArrayKey(recipient);
+    return async (ownerHex, ciphertext) => {
+      const conversationKey = nip44.getConversationKey(recipientKeyBytes, ownerHex);
+      return nip44.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');
+}
+
+/**
+ * Resolve a pubkey for either a raw key or a signer object.
+ * @param {string | Uint8Array | NipSigner} recipient
+ * @returns {Promise<string>}
+ */
+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()');
+}
+
+/**
+ * Parse the required `private` tag from an event.
+ * @param {any[]} tags
+ * @returns {boolean | null}
+ */
+export 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;
+}
+
+/**
+ * Extract all `privateRecipients` ciphertext values from an event.
+ * @param {any[]} tags
+ * @returns {string[]}
+ */
+export 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]);
+}
+
+/**
+ * Encrypt a list of recipient pubkeys so they can be published in a service record.
+ * @param {string | Uint8Array | NipSigner} ownerPrivateKey
+ * @param {string[]} recipients
+ * @returns {Promise<string[]>}
+ */
+export 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;
+}
+
+/**
+ * Decrypt a single private recipient ciphertext.
+ * @param {string} ciphertext
+ * @param {string} ownerPubkey
+ * @param {string | Uint8Array | NipSigner} recipientPrivateKey
+ * @returns {Promise<string>}
+ */
+export async function decryptPrivateRecipient(ciphertext, ownerPubkey, recipientPrivateKey) {
+  const ownerHex = normalizeHexPubkey(ownerPubkey);
+  const decryptor = createNip44Decryptor(recipientPrivateKey);
+  return decryptor(ownerHex, ciphertext);
+}
+
+/**
+ * Check whether the provided private key matches one of the encrypted recipients.
+ * @param {string[]} privateRecipients
+ * @param {string} ownerPubkey
+ * @param {string | Uint8Array | NipSigner} recipientPrivateKey
+ * @returns {Promise<boolean>}
+ */
+export 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 {
+      // ignore decrypt errors, ciphertext might not target this recipient
+    }
+  }
+  return false;
+}

package/src/resolver.js

@@ -1,5 +1,6 @@
 import { SimplePool, verifyEvent } from 'nostr-tools';
 import { KINDS } from './models.js';
+import { collectPrivateRecipients, parsePrivateFlag } from './privacy.js';
 
 /**
  * Custom error class for NCC-02 specific failures.
@@ -28,6 +29,8 @@ export class NCC02Error extends Error {
  * @property {string} eventId
  * @property {string} pubkey
  * @property {any} serviceEvent
+ * @property {boolean} isPrivate
+ * @property {string[]} privateRecipients
  */
 /**
  * Resolver for NCC-02 Service Records.
@@ -143,6 +146,10 @@ export class NCC02Resolver {
 
     const serviceTags = Object.fromEntries(serviceEvent.tags);
     const now = Math.floor(Date.now() / 1000);
+    const privateFlag = parsePrivateFlag(serviceEvent.tags);
+    if (privateFlag === null) {
+      throw new NCC02Error('MALFORMED_RECORD', 'Service record is missing required tag (private)');
+    }
 
     // Security Fix: exp is REQUIRED by NCC-02 spec
     if (!serviceTags.exp) {
@@ -180,6 +187,8 @@ export class NCC02Resolver {
       attestations: trustData.validAttestations,
       attestationCount: trustData.validAttestations.length,
       isRevoked: trustData.isRevoked,
+      isPrivate: privateFlag,
+      privateRecipients: collectPrivateRecipients(serviceEvent.tags),
       eventId: serviceEvent.id,
       pubkey: serviceEvent.pubkey,
       serviceEvent