ncc-02-js 0.2.0 → 0.2.3

package/dist/mockRelay.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Simple in-memory mock relay for testing NCC-02 resolution.
+ * Adheres to standard Nostr relay filtering rules.
+ */
+export class MockRelay {
+    /** @type {any[]} */
+    events: any[];
+    /**
+     * Publishes an event to the relay.
+     * Mimics a standard relay by verifying signatures before acceptance.
+     * @param {any} event
+     */
+    publish(event: any): Promise<boolean>;
+    /**
+     * Queries events using standard Nostr filters.
+     * Supports kinds, authors, ids, and tag filters (e.g. #d, #e).
+     * @param {any} filter
+     * @returns {Promise<any[]>}
+     */
+    query(filter: any): Promise<any[]>;
+}

package/dist/models.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Verifies a Nostr event signature.
+ * @param {any} event
+ */
+export function verifyNCC02Event(event: any): event is import("nostr-tools/core").VerifiedEvent;
+export namespace KINDS {
+    let SERVICE_RECORD: number;
+    let ATTESTATION: number;
+    let REVOCATION: number;
+}
+/**
+ * Utility for building and signing NCC-02 events.
+ */
+export class NCC02Builder {
+    /**
+     * @param {string | Uint8Array} privateKey - The private key to sign events with.
+     */
+    constructor(privateKey: string | Uint8Array);
+    sk: Uint8Array<ArrayBufferLike>;
+    pk: string;
+    /**
+     * Creates a signed Service Record (Kind 30059).
+     * @param {Object} options
+     * @param {string} options.serviceId - The 'd' tag identifier.
+     * @param {string} options.endpoint - The 'u' tag URI.
+     * @param {string} options.fingerprint - The 'k' tag fingerprint.
+     * @param {number} [options.expiryDays=14] - Expiry in days.
+     */
+    createServiceRecord(options: {
+        serviceId: string;
+        endpoint: string;
+        fingerprint: string;
+        expiryDays?: number;
+    }): import("nostr-tools/core").VerifiedEvent;
+    /**
+     * Creates a signed Certificate Attestation (Kind 30060).
+     * @param {Object} options
+     * @param {string} options.subjectPubkey - The 'subj' tag pubkey.
+     * @param {string} options.serviceId - The 'srv' tag identifier.
+     * @param {string} options.serviceEventId - The 'e' tag referencing the Service Record.
+     * @param {string} [options.level='verified'] - The 'lvl' tag level.
+     * @param {number} [options.validDays=30] - Validity in days.
+     */
+    createAttestation(options: {
+        subjectPubkey: string;
+        serviceId: string;
+        serviceEventId: string;
+        level?: string;
+        validDays?: number;
+    }): import("nostr-tools/core").VerifiedEvent;
+    /**
+     * Creates a signed Revocation (Kind 30061).
+     * @param {Object} options
+     * @param {string} options.attestationId - The 'e' tag referencing the attestation.
+     * @param {string} [options.reason=''] - Optional reason.
+     */
+    createRevocation(options: {
+        attestationId: string;
+        reason?: string;
+    }): import("nostr-tools/core").VerifiedEvent;
+}

package/dist/resolver.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Custom error class for NCC-02 specific failures.
+ */
+export class NCC02Error extends Error {
+    /**
+     * @param {string} code
+     * @param {string} message
+     * @param {any} [cause]
+     */
+    constructor(code: string, message: string, cause?: any);
+    code: string;
+    cause: any;
+}
+/**
+ * @typedef {Object} ResolvedService
+ * @property {string} endpoint
+ * @property {string} fingerprint
+ * @property {number} expiry
+ * @property {any[]} attestations
+ * @property {string} eventId
+ * @property {string} pubkey
+ */
+/**
+ * Resolver for NCC-02 Service Records.
+ * Implements the client-side resolution and trust verification algorithm.
+ */
+export class NCC02Resolver {
+    /**
+     * @param {string[]} relays - List of relay URLs.
+     * @param {Object} [options={}]
+     * @param {SimplePool} [options.pool] - Shared SimplePool instance.
+     * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys.
+     */
+    constructor(relays: string[], options?: {
+        pool?: SimplePool;
+        trustedCAPubkeys?: string[];
+    });
+    relays: string[];
+    pool: SimplePool;
+    ownsPool: boolean;
+    trustedCAPubkeys: Set<string>;
+    /**
+     * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
+     * @param {import('nostr-tools').Filter} filter
+     * @returns {Promise<import('nostr-tools').Event[]>}
+     */
+    _query(filter: import("nostr-tools").Filter): Promise<import("nostr-tools").Event[]>;
+    /**
+     * Resolves a service for a given pubkey and service identifier.
+     *
+     * @param {string} pubkey - The pubkey of the service owner.
+     * @param {string} serviceId - The 'd' tag identifier of the service (e.g., 'api').
+     * @param {Object} [options={}] - Policy options.
+     * @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.
+     */
+    resolve(pubkey: string, serviceId: string, options?: {
+        requireAttestation?: boolean;
+        minLevel?: string;
+        standard?: string;
+    }): Promise<ResolvedService>;
+    /**
+     * @param {string | undefined} actual
+     * @param {string} required
+     */
+    _isLevelSufficient(actual: string | undefined, required: string): boolean;
+    /**
+     * @param {any} att
+     * @param {any} tags
+     * @param {any[]} revocations
+     */
+    _isAttestationValid(att: any, tags: any, revocations: any[]): 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 {string} actualFingerprint - The fingerprint obtained from the service.
+     * @returns {boolean}
+     */
+    verifyEndpoint(resolved: ResolvedService, actualFingerprint: string): boolean;
+}
+export type ResolvedService = {
+    endpoint: string;
+    fingerprint: string;
+    expiry: number;
+    attestations: any[];
+    eventId: string;
+    pubkey: string;
+};
+import { SimplePool } from 'nostr-tools';

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "ncc-02-js",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Nostr-native service discovery and trust implementation (NCC-02)",
-  "main": "dist/index.js",
+  "main": "dist/index.cjs",
   "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
   "scripts": {
     "test": "node tests/test.js",
-    "build": "esbuild src/index.js --bundle --platform=node --format=cjs --outfile=dist/index.js && esbuild src/index.js --bundle --platform=node --format=esm --outfile=dist/index.mjs",
+    "build": "esbuild src/index.js --bundle --platform=node --format=cjs --outfile=dist/index.cjs && esbuild src/index.js --bundle --platform=node --format=esm --outfile=dist/index.mjs && tsc --emitDeclarationOnly",
+    "prepublishOnly": "npm run build",
     "lint": "eslint src/**/*.js",
     "type-check": "tsc -p jsconfig.json"
   },

package/src/models.js

@@ -25,12 +25,14 @@ export class NCC02Builder {
 
   /**
    * Creates a signed Service Record (Kind 30059).
-   * @param {string} serviceId
-   * @param {string} endpoint
-   * @param {string} fingerprint
-   * @param {number} [expiryDays=14]
+   * @param {Object} options
+   * @param {string} options.serviceId - The 'd' tag identifier.
+   * @param {string} options.endpoint - The 'u' tag URI.
+   * @param {string} options.fingerprint - The 'k' tag fingerprint.
+   * @param {number} [options.expiryDays=14] - Expiry in days.
    */
-  createServiceRecord(serviceId, endpoint, fingerprint, expiryDays = 14) {
+  createServiceRecord(options) {
+    const { serviceId, endpoint, fingerprint, expiryDays = 14 } = options;
     if (!serviceId) throw new Error('serviceId (d tag) is required');
     if (!endpoint) throw new Error('endpoint (u tag) is required');
     if (!fingerprint) throw new Error('fingerprint (k tag) is required');
@@ -53,13 +55,15 @@ export class NCC02Builder {
 
   /**
    * Creates a signed Certificate Attestation (Kind 30060).
-   * @param {string} subjectPubkey
-   * @param {string} serviceId
-   * @param {string} serviceEventId
-   * @param {string} [level='verified']
-   * @param {number} [validDays=30]
+   * @param {Object} options
+   * @param {string} options.subjectPubkey - The 'subj' tag pubkey.
+   * @param {string} options.serviceId - The 'srv' tag identifier.
+   * @param {string} options.serviceEventId - The 'e' tag referencing the Service Record.
+   * @param {string} [options.level='verified'] - The 'lvl' tag level.
+   * @param {number} [options.validDays=30] - Validity in days.
    */
-  createAttestation(subjectPubkey, serviceId, serviceEventId, level = 'verified', validDays = 30) {
+  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');
     if (!serviceEventId) throw new Error('serviceEventId (e tag) is required');
@@ -86,10 +90,12 @@ export class NCC02Builder {
 
   /**
    * Creates a signed Revocation (Kind 30061).
-   * @param {string} attestationId
-   * @param {string} [reason='']
+   * @param {Object} options
+   * @param {string} options.attestationId - The 'e' tag referencing the attestation.
+   * @param {string} [options.reason=''] - Optional reason.
    */
-  createRevocation(attestationId, reason = '') {
+  createRevocation(options) {
+    const { attestationId, reason = '' } = options;
     if (!attestationId) throw new Error('attestationId (e tag) is required');
 
     const tags = [['e', attestationId]];
@@ -112,4 +118,4 @@ export class NCC02Builder {
  */
 export function verifyNCC02Event(event) {
   return verifyEvent(event);
-}
+}

package/src/resolver.js

@@ -1,4 +1,4 @@
-import { verifyEvent } from 'nostr-tools/pure';
+import { SimplePool, verifyEvent } from 'nostr-tools';
 import { KINDS } from './models.js';
 
 /**
@@ -33,12 +33,37 @@ export class NCC02Error extends Error {
  */
 export class NCC02Resolver {
   /**
-   * @param {any} relay - A relay client providing a `query` method.
-   * @param {string[]} [trustedCAPubkeys=[]] - List of CA pubkeys trusted by this client.
+   * @param {string[]} relays - List of relay URLs.
+   * @param {Object} [options={}]
+   * @param {SimplePool} [options.pool] - Shared SimplePool instance.
+   * @param {string[]} [options.trustedCAPubkeys=[]] - List of trusted CA pubkeys.
    */
-  constructor(relay, trustedCAPubkeys = []) {
-    this.relay = relay;
-    this.trustedCAPubkeys = new Set(trustedCAPubkeys);
+  constructor(relays, options = {}) {
+    if (!Array.isArray(relays)) {
+       throw new Error("NCC02Resolver expects an array of relay URLs.");
+    }
+    this.relays = relays;
+    this.pool = options.pool || new SimplePool();
+    this.ownsPool = !options.pool;
+    this.trustedCAPubkeys = new Set(options.trustedCAPubkeys || []);
+  }
+
+  /**
+   * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
+   * @param {import('nostr-tools').Filter} filter 
+   * @returns {Promise<import('nostr-tools').Event[]>}
+   */
+  async _query(filter) {
+      return new Promise((resolve) => {
+          /** @type {import('nostr-tools').Event[]} */
+          const events = [];
+          // subscribeMany(relays, filters, callbacks)
+          // @ts-ignore - subscribeMany filters parameter type mismatch with simple Object
+          const sub = this.pool.subscribeMany(this.relays, [filter], {
+              onevent(e) { events.push(e); },
+              oneose() { sub.close(); resolve(events); }
+          });
+      });
   }
 
   /**
@@ -62,7 +87,7 @@ export class NCC02Resolver {
 
     let serviceEvents;
     try {
-      serviceEvents = await this.relay.query({
+      serviceEvents = await this._query({
         kinds: [KINDS.SERVICE_RECORD],
         authors: [pubkey],
         '#d': [serviceId]
@@ -105,8 +130,8 @@ export class NCC02Resolver {
     let revocations;
     try {
       [attestations, revocations] = await Promise.all([
-        this.relay.query({ kinds: [KINDS.ATTESTATION], '#e': [serviceEvent.id] }),
-        this.relay.query({ kinds: [KINDS.REVOCATION] })
+        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);
@@ -209,4 +234,4 @@ export class NCC02Resolver {
   verifyEndpoint(resolved, actualFingerprint) {
     return resolved.fingerprint === actualFingerprint;
   }
-}
+}