ncc-02-js 0.3.1 → 0.4.0

package/README.md

@@ -48,39 +48,107 @@ try {
 }
 ```
 
-### 2. Publish a Service Record
-...
-### Trust Model & Security
+### 2. Publish Service Records and Attestations
 
-### 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).
+```javascript
+import { NCC02Builder } from 'ncc-02-js';
+
+const builder = new NCC02Builder(privateKey);
+
+const serviceRecord = await builder.createServiceRecord({
+  serviceId: 'api',
+  endpoint: 'https://service.example.com',
+  fingerprint: '<spki fingerprint>',
+  expiryDays: 7
+});
+
+const attestation = await builder.createAttestation({
+  subjectPubkey: ownerPubkey,
+  serviceId: 'api',
+  serviceEventId: serviceRecord.id,
+  level: 'verified',
+  validDays: 30
+});
+
+await builder.createRevocation({
+  attestationId: attestation.id,
+  reason: 'Key rotation'
+});
+```
+
+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`.
+
+### 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.
+
+### 4. Resolution Optimization
+
+To avoid unnecessary relay traffic, attestation and revocation feeds are only fetched when the resolver’s policy requests them. Keep expiries short and rotate fingerprints with the `k` tag to reduce the blast radius of compromised keys.
+
+### 5. Threat Model
 
-### Resolution Optimization
-The resolver is designed to be network-efficient. It will only query for attestations (Kind 30060) and revocations (Kind 30061) if the provided policy requires them (e.g., when `requireAttestation` is set to `true` or a `minLevel` higher than `self` is requested).
+The library defends against endpoint impersonation, MITM, stale records, and relay censorship by enforcing signed records, short expiries, revocation checks, and optional third-party attestations. It deliberately keeps scope focused on application-layer trust and does not replace TLS or browser PKI.
 
-### Threat Model
-...
-### API Reference
+### 6. Testing with MockRelay
+
+```javascript
+import { MockRelay, NCC02Builder, NCC02Resolver } from 'ncc-02-js';
+
+const mock = new MockRelay();
+const builder = new NCC02Builder(privateKey);
+const serviceRecord = await builder.createServiceRecord({ serviceId: 'api', endpoint: 'https://example', fingerprint: '<fp>' });
+await mock.publish(serviceRecord);
+
+const resolver = new NCC02Resolver(['mock://local'], { pool: mock });
+await resolver.resolve(ownerPubkey, 'api');
+```
+
+`MockRelay` mimics a Nostr relay by verifying signatures and honoring `kinds`, `authors`, `ids`, and `#tag` filters. It makes writing unit tests and integration suites deterministic without external dependencies.
+
+### 7. Endpoint Verification Helpers
+
+After resolving a service, call `resolver.verifyEndpoint(serviceStatus, actualFingerprint)` to ensure the runtime transport fingerprint matches the declared `k` tag. Use `verifyNCC02Event` when you ingest raw events and `isExpired` to quickly skip expired records before attempting network validation.
+
+## 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.
+- `options.pool`: (Optional) Shared `nostr-tools` `SimplePool`.
+- `options.trustedCAPubkeys`: Optional array of certifier pubkeys that may issue trusted attestations.
 
 #### `resolve(pubkey, serviceId, options)`
-- `options.requireAttestation`: Fails if no trusted attestation is found.
-- `options.minLevel`: Minimum trust level required.
+- `options.requireAttestation`: Reject if no trusted attestation is available.
+- `options.minLevel`: Minimum `lvl` tag level (`self`, `verified`, `hardened`).
+- `options.standard`: Expected `std` tag value (defaults to `nostr-service-trust-v0.1`).
+- Returns `ServiceStatus` including `endpoint`, `fingerprint`, `expiry`, `attestations`, `attestationCount`, `isRevoked`, `eventId`, `pubkey`, and the raw `serviceEvent`.
+
+#### `verifyEndpoint(resolved, actualFingerprint)`
+- Compares the resolved fingerprint with the observed transport fingerprint for an additional rejection guard.
 
 #### `close()`
-Closes WebSocket connections to all relays. If the resolver was initialized with an external `pool`, this will *not* close the pool; it only untracks the relays for this instance. If the resolver created its own internal pool, it will close it entirely.
+- Closes relay subscriptions when the resolver owns the `SimplePool`.
+
+### `NCC02Builder(signer)`
+- `signer`: Hex private key, `Uint8Array`, or custom signer with `getPublicKey`/`signEvent`.
+
+#### `createServiceRecord({ serviceId, endpoint?, fingerprint?, expiryDays? })`
+- Returns a signed Kind 30059 event. `endpoint` maps to `u`, `fingerprint` to `k`, and `expiryDays` controls `exp`.
+
+#### `createAttestation({ subjectPubkey, serviceId, serviceEventId, level?, validDays? })`
+- Emits Kind 30060 with `subj`, `srv`, `e`, `std`, `lvl`, `nbf`, and `exp`.
+
+#### `createRevocation({ attestationId, reason? })`
+- Emits Kind 30061 pointing to the revoked attestation.
 
+### `MockRelay`
+- `publish(event)`: Verifies and stores the event (returns `true` if accepted).
+- `query(filter)`: Filters stored events by `kinds`, `authors`, `ids`, and `#tag` criteria.
 
-### `NCC02Builder(privateKey)`
-- `createServiceRecord({ serviceId, endpoint?, fingerprint?, expiryDays? })`
-- `createAttestation({ subjectPubkey, serviceId, serviceEventId, level, validDays })`
-- `createRevocation({ attestationId, reason })`
+### Helpers
+- `verifyNCC02Event(event)`: Signature verification wrapper.
+- `isExpired(event)`: Returns `true` when the `exp` tag is in the past.
+- `KINDS`: Enum with `SERVICE_RECORD`, `ATTESTATION`, and `REVOCATION`.
 
 ## License
 

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   NCC02Builder: () => NCC02Builder,
   NCC02Error: () => NCC02Error,
   NCC02Resolver: () => NCC02Resolver,
+  isExpired: () => isExpired,
   verifyNCC02Event: () => verifyNCC02Event
 });
 module.exports = __toCommonJS(index_exports);
@@ -2498,12 +2499,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).
@@ -2513,7 +2575,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;
@@ -2527,10 +2589,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).
@@ -2541,7 +2602,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");
@@ -2560,10 +2621,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).
@@ -2571,7 +2631,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]];
@@ -2580,15 +2640,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) {
@@ -7719,6 +7786,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.
    * 
@@ -7728,8 +7816,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 {
@@ -7737,9 +7825,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]
@@ -7747,13 +7835,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");
     }
@@ -7772,88 +7856,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}
    */
@@ -7911,6 +8042,7 @@ var MockRelay = class {
   NCC02Builder,
   NCC02Error,
   NCC02Resolver,
+  isExpired,
   verifyNCC02Event
 });
 /*! Bundled license information: