ncc-02-js 0.3.1 → 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
@@ -48,39 +49,110 @@ 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`.
+
+#### 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.
+
+### 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.
 
-### 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).
+### 5. Threat Model
 
-### Threat Model
-...
-### API Reference
+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.
+
+### 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