ncc-02-js 0.2.2 → 0.2.4

package/README.md

@@ -25,12 +25,16 @@ npm install ncc-02-js
 ```javascript
 import { NCC02Resolver } from 'ncc-02-js';
 
-const resolver = new NCC02Resolver(relay, [trustedCAPubkey]);
+// Initialize with relay URLs and optional trusted CA pubkeys
+const resolver = new NCC02Resolver(['wss://relay.damus.io'], {
+  trustedCAPubkeys: ['npub1...'] // Trusted third-party certifiers
+});
 
 try {
-  const service = await resolver.resolve(ownerPubkey, 'api', {
+  // ownerPubkey can be hex or npub
+  const service = await resolver.resolve(ownerPubkey, 'media', {
     requireAttestation: true,
-    minLevel: 'verified'
+    minLevel: 'verified' // 'self', 'verified', 'hardened'
   });
   console.log('Resolved endpoint:', service.endpoint);
 } catch (err) {
@@ -43,21 +47,71 @@ try {
 ```javascript
 import { NCC02Builder } from 'ncc-02-js';
 
+// Initialize with private key (hex)
 const builder = new NCC02Builder(privateKey);
-const event = builder.createServiceRecord('api', 'https://api.example.com', 'sha256:fingerprint');
-// publish event to relays...
+
+// Example 1: IP-based Service
+const event = builder.createServiceRecord({
+  serviceId: 'media',
+  endpoint: 'https://203.0.113.45:8443',
+  fingerprint: 'sha256:fingerprint',
+  expiryDays: 14
+});
+
+// Example 2: Tor Onion Service
+const onionEvent = builder.createServiceRecord({
+  serviceId: 'wallet',
+  endpoint: 'tcp://vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd.onion:80',
+  fingerprint: 'sha256:fingerprint',
+  expiryDays: 7
+});
+// publish events to relays...
+```
+
+### 3. Issue an Attestation (CA)
+
+```javascript
+const caBuilder = new NCC02Builder(caPrivateKey);
+const attestation = caBuilder.createAttestation({
+  subjectPubkey: 'npub1...', // The service owner being certified
+  serviceId: 'media',
+  serviceEventId: serviceRecordEventId,
+  level: 'verified',
+  validDays: 30
+});
 ```
 
-## API
+## Trust Model & Security
+
+### Trust Levels
+- `self`: Asserted by the service owner (default if no attestation).
+- `verified`: Attested by a trusted third party.
+- `hardened`: Attested by a third party with stricter verification (e.g., physical proof or long-term history).
+
+### Threat Model
+- **Endpoint Impersonation**: Prevented by binding the endpoint URI to a public key fingerprint (`k` tag).
+- **Man-in-the-Middle (MITM)**: Mitigated via cryptographic pinning of transport-level keys.
+- **Stale Records**: Limited by required expiry (`exp`) and support for revocations.
+- **Relay Censorship**: Mitigated by querying multiple relays (implemented via `SimplePool`).
+
+### Fail-Closed Design
+The library follows a fail-closed principle. If a policy requirement is not met (e.g., `requireAttestation: true` but no valid attestation is found), it throws an `NCC02Error` rather than returning a partially verified record.
+
+## API Reference
+
+### `NCC02Resolver(relays, options)`
+- `relays`: Array of relay URLs.
+- `options.pool`: (Optional) Existing `nostr-tools` SimplePool.
+- `options.trustedCAPubkeys`: (Optional) Array of pubkeys trusted to issue attestations.
 
-### `NCC02Resolver`
-- `resolve(pubkey, serviceId, options)`: Resolves and verifies a service record.
-- `verifyEndpoint(resolved, actualFingerprint)`: Helper to check if a connected endpoint matches the record.
+#### `resolve(pubkey, serviceId, options)`
+- `options.requireAttestation`: Fails if no trusted attestation is found.
+- `options.minLevel`: Minimum trust level required.
 
-### `NCC02Builder`
-- `createServiceRecord(id, uri, fingerprint, expiryDays)`
-- `createAttestation(subject, srv, eventId, level, validDays)`
-- `createRevocation(attestationId, reason)`
+### `NCC02Builder(privateKey)`
+- `createServiceRecord({ serviceId, endpoint, fingerprint, expiryDays })`
+- `createAttestation({ subjectPubkey, serviceId, serviceEventId, level, validDays })`
+- `createRevocation({ attestationId, reason })`
 
 ## License
 

package/dist/index.cjs

@@ -2535,13 +2535,15 @@ var NCC02Builder = class {
   }
   /**
    * 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");
@@ -2566,10 +2568,12 @@ var NCC02Builder = class {
   }
   /**
    * 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]];
     if (reason) tags.push(["reason", reason]);
@@ -7688,8 +7692,8 @@ var NCC02Resolver = class {
   }
   /**
    * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
-   * @param {Object} filter 
-   * @returns {Promise<any[]>}
+   * @param {import('nostr-tools').Filter} filter 
+   * @returns {Promise<import('nostr-tools').Event[]>}
    */
   async _query(filter) {
     return new Promise((resolve) => {

package/dist/index.mjs

@@ -2501,13 +2501,15 @@ var NCC02Builder = class {
   }
   /**
    * 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");
@@ -2532,10 +2534,12 @@ var NCC02Builder = class {
   }
   /**
    * 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]];
     if (reason) tags.push(["reason", reason]);
@@ -7654,8 +7658,8 @@ var NCC02Resolver = class {
   }
   /**
    * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
-   * @param {Object} filter 
-   * @returns {Promise<any[]>}
+   * @param {import('nostr-tools').Filter} filter 
+   * @returns {Promise<import('nostr-tools').Event[]>}
    */
   async _query(filter) {
     return new Promise((resolve) => {

package/dist/models.d.ts

@@ -34,17 +34,28 @@ export class NCC02Builder {
     }): import("nostr-tools/core").VerifiedEvent;
     /**
      * 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: string, serviceId: string, serviceEventId: string, level?: string, validDays?: number): import("nostr-tools/core").VerifiedEvent;
+    createAttestation(options: {
+        subjectPubkey: string;
+        serviceId: string;
+        serviceEventId: string;
+        level?: string;
+        validDays?: number;
+    }): import("nostr-tools/core").VerifiedEvent;
     /**
      * 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: string, reason?: string): import("nostr-tools/core").VerifiedEvent;
+    createRevocation(options: {
+        attestationId: string;
+        reason?: string;
+    }): import("nostr-tools/core").VerifiedEvent;
 }

package/dist/resolver.d.ts

@@ -41,10 +41,10 @@ export class NCC02Resolver {
     trustedCAPubkeys: Set<string>;
     /**
      * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
-     * @param {Object} filter
-     * @returns {Promise<any[]>}
+     * @param {import('nostr-tools').Filter} filter
+     * @returns {Promise<import('nostr-tools').Event[]>}
      */
-    _query(filter: any): Promise<any[]>;
+    _query(filter: import("nostr-tools").Filter): Promise<import("nostr-tools").Event[]>;
     /**
      * Resolves a service for a given pubkey and service identifier.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncc-02-js",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Nostr-native service discovery and trust implementation (NCC-02)",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -8,9 +8,9 @@
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     }
   },
   "sideEffects": false,

package/src/models.js

@@ -55,17 +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) {
-    // Keeping signature backward compatible for now unless requested, 
-    // but improving internal logic slightly if needed.
-    // Ideally this should also be options object but user only asked for createServiceRecord fix.
-    // I'll leave it to minimize breaking changes scope creep.
+  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');
@@ -92,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]];

package/src/resolver.js

@@ -50,13 +50,15 @@ export class NCC02Resolver {
 
   /**
    * Internal query helper using SimplePool.subscribeMany (since list() is deprecated).
-   * @param {Object} filter 
-   * @returns {Promise<any[]>}
+   * @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); }