ncc-02-js 0.2.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ncc-02-js",
+  "version": "0.2.0",
+  "description": "Nostr-native service discovery and trust implementation (NCC-02)",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "type": "module",
+  "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",
+    "lint": "eslint src/**/*.js",
+    "type-check": "tsc -p jsconfig.json"
+  },
+  "keywords": [
+    "nostr",
+    "ncc-02",
+    "service-discovery",
+    "trust",
+    "verification"
+  ],
+  "author": "lostcause",
+  "license": "CC0-1.0",
+  "dependencies": {
+    "nostr-tools": "^2.10.4"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.25.0",
+    "@typescript-eslint/parser": "^8.25.0",
+    "esbuild": "^0.25.0",
+    "eslint": "^9.21.0",
+    "globals": "^16.0.0",
+    "typescript": "^5.8.2"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imattau/ncc-02.git"
+  }
+}

package/src/index.js

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

package/src/mockRelay.js

@@ -0,0 +1,54 @@
+import { verifyEvent } from 'nostr-tools/pure';
+
+/**
+ * Simple in-memory mock relay for testing NCC-02 resolution.
+ * Adheres to standard Nostr relay filtering rules.
+ */
+export class MockRelay {
+  constructor() {
+    /** @type {any[]} */
+    this.events = [];
+  }
+
+  /**
+   * Publishes an event to the relay. 
+   * Mimics a standard relay by verifying signatures before acceptance.
+   * @param {any} event 
+   */
+  async publish(event) {
+    if (!verifyEvent(event)) {
+      return false;
+    }
+    this.events.push(event);
+    return true;
+  }
+
+  /**
+   * Queries events using standard Nostr filters.
+   * Supports kinds, authors, ids, and tag filters (e.g. #d, #e).
+   * @param {any} filter 
+   * @returns {Promise<any[]>}
+   */
+  async query(filter) {
+    return this.events.filter(event => {
+      if (filter.kinds && !filter.kinds.includes(event.kind)) return false;
+      if (filter.authors && !filter.authors.includes(event.pubkey)) return false;
+      if (filter.ids && !filter.ids.includes(event.id)) return false;
+      
+      for (const key in filter) {
+        if (key.startsWith('#')) {
+          const tagName = key.slice(1);
+          const filterValues = filter[key];
+          const eventTagValues = event.tags
+            .filter((/** @type {any[]} */ t) => t[0] === tagName)
+            .map((/** @type {any[]} */ t) => t[1]);
+          
+          if (!filterValues.some((/** @type {string} */ fv) => eventTagValues.includes(fv))) {
+            return false;
+          }
+        }
+      }
+      return true;
+    });
+  }
+}

package/src/models.js

@@ -0,0 +1,115 @@
+import { finalizeEvent, verifyEvent, getPublicKey } from 'nostr-tools/pure';
+import { hexToBytes } from 'nostr-tools/utils';
+
+/**
+ * NCC-02 Nostr Event Kinds
+ */
+export const KINDS = {
+  SERVICE_RECORD: 30059,
+  ATTESTATION: 30060,
+  REVOCATION: 30061
+};
+
+/**
+ * Utility for building and signing NCC-02 events.
+ */
+export class NCC02Builder {
+  /**
+   * @param {string | Uint8Array} privateKey - The private key to sign events with.
+   */
+  constructor(privateKey) {
+    if (!privateKey) throw new Error('Private key is required');
+    this.sk = typeof privateKey === 'string' ? hexToBytes(privateKey) : privateKey;
+    this.pk = getPublicKey(this.sk);
+  }
+
+  /**
+   * Creates a signed Service Record (Kind 30059).
+   * @param {string} serviceId
+   * @param {string} endpoint
+   * @param {string} fingerprint
+   * @param {number} [expiryDays=14]
+   */
+  createServiceRecord(serviceId, endpoint, fingerprint, expiryDays = 14) {
+    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');
+
+    const expiry = Math.floor(Date.now() / 1000) + (expiryDays * 24 * 60 * 60);
+    const event = {
+      kind: KINDS.SERVICE_RECORD,
+      created_at: Math.floor(Date.now() / 1000),
+      tags: [
+        ['d', serviceId],
+        ['u', endpoint],
+        ['k', fingerprint],
+        ['exp', expiry.toString()]
+      ],
+      content: `NCC-02 Service Record for ${serviceId}`,
+      pubkey: this.pk
+    };
+    return finalizeEvent(event, this.sk);
+  }
+
+  /**
+   * Creates a signed Certificate Attestation (Kind 30060).
+   * @param {string} subjectPubkey
+   * @param {string} serviceId
+   * @param {string} serviceEventId
+   * @param {string} [level='verified']
+   * @param {number} [validDays=30]
+   */
+  createAttestation(subjectPubkey, serviceId, serviceEventId, level = 'verified', validDays = 30) {
+    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');
+
+    const now = Math.floor(Date.now() / 1000);
+    const expiry = now + (validDays * 24 * 60 * 60);
+    const event = {
+      kind: KINDS.ATTESTATION,
+      created_at: now,
+      tags: [
+        ['subj', subjectPubkey],
+        ['srv', serviceId],
+        ['e', serviceEventId],
+        ['std', 'nostr-service-trust-v0.1'],
+        ['lvl', level],
+        ['nbf', now.toString()],
+        ['exp', expiry.toString()]
+      ],
+      content: 'NCC-02 Attestation',
+      pubkey: this.pk
+    };
+    return finalizeEvent(event, this.sk);
+  }
+
+  /**
+   * Creates a signed Revocation (Kind 30061).
+   * @param {string} attestationId
+   * @param {string} [reason='']
+   */
+  createRevocation(attestationId, reason = '') {
+    if (!attestationId) throw new Error('attestationId (e tag) is required');
+
+    const tags = [['e', attestationId]];
+    if (reason) tags.push(['reason', reason]);
+    
+    const event = {
+      kind: KINDS.REVOCATION,
+      created_at: Math.floor(Date.now() / 1000),
+      tags: tags,
+      content: 'NCC-02 Revocation',
+      pubkey: this.pk
+    };
+    return finalizeEvent(event, this.sk);
+  }
+}
+
+/**
+ * Verifies a Nostr event signature.
+ * @param {any} event
+ */
+export function verifyNCC02Event(event) {
+  return verifyEvent(event);
+}

package/src/resolver.js

@@ -0,0 +1,212 @@
+import { verifyEvent } from 'nostr-tools/pure';
+import { KINDS } from './models.js';
+
+/**
+ * Custom error class for NCC-02 specific failures.
+ */
+export class NCC02Error extends Error {
+  /**
+   * @param {string} code 
+   * @param {string} message 
+   * @param {any} [cause]
+   */
+  constructor(code, message, cause) {
+    super(message);
+    this.code = code;
+    if (cause) this.cause = cause;
+  }
+}
+
+/**
+ * @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 {any} relay - A relay client providing a `query` method.
+   * @param {string[]} [trustedCAPubkeys=[]] - List of CA pubkeys trusted by this client.
+   */
+  constructor(relay, trustedCAPubkeys = []) {
+    this.relay = relay;
+    this.trustedCAPubkeys = new Set(trustedCAPubkeys);
+  }
+
+  /**
+   * 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.
+   */
+  async resolve(pubkey, serviceId, options = {}) {
+    const { 
+      requireAttestation = false, 
+      minLevel = null,
+      standard = 'nostr-service-trust-v0.1'
+    } = options;
+
+    let serviceEvents;
+    try {
+      serviceEvents = await this.relay.query({
+        kinds: [KINDS.SERVICE_RECORD],
+        authors: [pubkey],
+        '#d': [serviceId]
+      });
+    } catch (err) {
+      throw new NCC02Error('RELAY_ERROR', `Failed to query relay for ${serviceId}`, err);
+    }
+
+    if (!serviceEvents || !serviceEvents.length) {
+      throw new NCC02Error('NOT_FOUND', `No service record found for ${serviceId}`);
+    }
+
+    // Stable tie-breaking: Sort by created_at DESC, then ID ASC
+    const serviceEvent = serviceEvents.sort((/** @type {any} */ a, /** @type {any} */ b) => {
+      if (b.created_at !== a.created_at) return b.created_at - a.created_at;
+      return a.id.localeCompare(b.id);
+    })[0];
+
+    if (!verifyEvent(serviceEvent)) {
+      throw new NCC02Error('INVALID_SIGNATURE', 'Service record signature verification failed');
+    }
+
+    const serviceTags = Object.fromEntries(serviceEvent.tags);
+    const now = Math.floor(Date.now() / 1000);
+
+    // Security Fix: exp is REQUIRED by NCC-02 spec
+    if (!serviceTags.u || !serviceTags.k || !serviceTags.exp) {
+      throw new NCC02Error('MALFORMED_RECORD', 'Service record is missing required tags (u, k, or exp)');
+    }
+
+    const exp = parseInt(serviceTags.exp);
+    if (isNaN(exp)) {
+      throw new NCC02Error('MALFORMED_RECORD', 'Service record expiry tag is not a valid number');
+    }
+    if (exp < now) {
+      throw new NCC02Error('EXPIRED', 'Service record has expired');
+    }
+
+    let attestations;
+    let revocations;
+    try {
+      [attestations, revocations] = await Promise.all([
+        this.relay.query({ kinds: [KINDS.ATTESTATION], '#e': [serviceEvent.id] }),
+        this.relay.query({ kinds: [KINDS.REVOCATION] })
+      ]);
+    } catch (err) {
+      throw new NCC02Error('RELAY_ERROR', 'Failed to query relay for attestations/revocations', err);
+    }
+
+    const validAttestations = [];
+    for (const att of attestations) {
+      if (this.trustedCAPubkeys.has(att.pubkey)) {
+        const attTags = Object.fromEntries(att.tags);
+        
+        // Cross-validate subject, service ID, and standard
+        if (attTags.subj !== pubkey) continue;
+        if (attTags.srv !== serviceId) continue;
+        if (standard && attTags.std !== standard) continue;
+        
+        // Trust Level Filtering
+        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}`);
+    }
+
+    return {
+      endpoint: serviceTags.u,
+      fingerprint: serviceTags.k,
+      expiry: exp,
+      attestations: validAttestations,
+      eventId: serviceEvent.id,
+      pubkey: serviceEvent.pubkey
+    };
+  }
+
+  /**
+   * @param {string | undefined} actual 
+   * @param {string} required 
+   */
+  _isLevelSufficient(actual, required) {
+    /** @type {Record<string, number>} */
+    const levels = { 'self': 0, 'verified': 1, 'hardened': 2 };
+    const actualVal = actual ? (levels[actual] ?? -1) : -1;
+    const requiredVal = levels[required] ?? 0;
+    return actualVal >= requiredVal;
+  }
+
+  /**
+   * @param {any} att 
+   * @param {any} tags 
+   * @param {any[]} revocations 
+   */
+  _isAttestationValid(att, tags, revocations) {
+    // 1. Verify Attestation signature
+    if (!verifyEvent(att)) return false;
+
+    const now = Math.floor(Date.now() / 1000);
+    
+    // 2. NBF validation
+    if (tags.nbf) {
+      const nbf = parseInt(tags.nbf);
+      if (isNaN(nbf) || nbf > now) return false;
+    }
+
+    // 3. EXP validation
+    if (tags.exp) {
+      const exp = parseInt(tags.exp);
+      if (isNaN(exp) || exp < now) return false;
+    }
+
+    // 4. Revocation validation
+    // A revocation is valid only if it matches the attestation ID, is from the same CA, AND has a valid signature.
+    for (const rev of revocations) {
+      const revTags = Object.fromEntries(rev.tags);
+      if (revTags.e === att.id && rev.pubkey === att.pubkey) {
+        if (verifyEvent(rev)) {
+          return false; // Valid revocation found
+        }
+      }
+    }
+
+    return true; // No valid revocation found
+  }
+
+  /**
+   * 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, actualFingerprint) {
+    return resolved.fingerprint === actualFingerprint;
+  }
+}