nostr-crypto-utils 0.1.6 → 0.2.0

package/README.md

@@ -1,14 +1,17 @@
-# @humanjavaenterprises/nostr-crypto-utils
+# nostr-crypto-utils
 
 A comprehensive TypeScript library providing cryptographic utilities and protocol-compliant message handling for Nostr applications, designed to work seamlessly with [@humanjavaenterprises/nostr-nsec-seedphrase](https://github.com/HumanjavaEnterprises/nostr-nsec-seedphrase).
 
 [![npm version](https://badge.fury.io/js/%40humanjavaenterprises%2Fnostr-crypto-utils.svg)](https://www.npmjs.com/package/@humanjavaenterprises/nostr-crypto-utils)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/HumanjavaEnterprises/nostr-crypto-utils/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-TypeDoc-blue.svg)](https://humanjavaenterprises.github.io/nostr-crypto-utils/)
 
-⚠️ **Important Security Notice**
+## Security Notice
 
-This library handles cryptographic keys and operations that are critical for securing your Nostr identity and data. All cryptographic operations, including key generation, signing, and encryption, must be handled with appropriate security measures.
+⚠️ **Important**: This library handles cryptographic keys and operations that are critical for securing your Nostr identity and data. All cryptographic operations, including key generation, signing, and encryption, must be handled with appropriate security measures.
+
+If you discover a security vulnerability, please follow our [Security Policy](SECURITY.md) and report it through [GitHub's Security Advisory feature](https://github.com/humanjavaenterprises/nostr-crypto-utils/security/advisories/new).
 
 ## Features
 
@@ -19,117 +22,81 @@ This library handles cryptographic keys and operations that are critical for sec
 - **Encryption**: Secure encryption and decryption for direct messages (NIP-04)
 - **Validation**: Comprehensive validation for events, filters, and subscriptions
 
+## Features and Capabilities
+
+| Feature                    | Status | Description                                           |
+|---------------------------|--------|-------------------------------------------------------|
+| Key Management            | ✅     | Generate, validate, and manage Nostr keypairs         |
+| Event Creation            | ✅     | Create and validate Nostr events                      |
+| Event Signing             | ✅     | Sign events with schnorr signatures                   |
+| Event Verification        | ✅     | Verify event signatures and validate event structure  |
+| Message Encryption        | ✅     | NIP-04 compliant message encryption                   |
+| Message Decryption        | ✅     | NIP-04 compliant message decryption                  |
+| Event Serialization       | ✅     | Protocol-compliant event serialization               |
+| Event Hashing            | ✅     | Generate and verify event IDs                        |
+
 ## Installation
 
 ```bash
-npm install @humanjavaenterprises/nostr-crypto-utils
+npm install nostr-crypto-utils
 ```
 
-## Usage
-
-### Key Management
+## Quick Start
 
 ```typescript
-import { generateKeyPair, getPublicKey } from '@humanjavaenterprises/nostr-crypto-utils';
+import { generateKeyPair, signEvent, verifyEvent } from 'nostr-crypto-utils';
 
-// Generate a new key pair
+// Generate a new keypair
 const keyPair = await generateKeyPair();
 console.log('Public Key:', keyPair.publicKey);
 console.log('Private Key:', keyPair.privateKey);
 
-// Get public key from private key
-const pubKey = getPublicKey(privateKey);
-```
-
-### Event Operations
-
-```typescript
-import { createEvent, signEvent, validateEvent } from '@humanjavaenterprises/nostr-crypto-utils';
-
 // Create and sign an event
-const event = createEvent({
-  kind: NostrEventKind.TEXT_NOTE,
+const event = await signEvent({
+  kind: 1,
   content: 'Hello Nostr!',
   tags: []
-});
-const signedEvent = await signEvent(event, privateKey);
-
-// Validate an event
-const validation = validateEvent(event);
-if (validation.isValid) {
-  console.log('Event is valid');
-} else {
-  console.log('Validation errors:', validation.errors);
-}
-```
+}, keyPair.privateKey);
 
-### Message Handling
-
-```typescript
-import { 
-  formatEventForRelay, 
-  formatSubscriptionForRelay,
-  parseNostrMessage 
-} from '@humanjavaenterprises/nostr-crypto-utils';
-
-// Format event for relay
-const eventMessage = formatEventForRelay(signedEvent);
-
-// Format subscription request
-const subscription = {
-  id: 'sub1',
-  filters: [{ kinds: [1], limit: 10 }]
-};
-const subMessage = formatSubscriptionForRelay(subscription);
-
-// Parse incoming messages
-const message = ['EVENT', signedEvent];
-const parsed = parseNostrMessage(message);
+// Verify the event
+const isValidEvent = await verifyEvent(event);
 ```
 
-### Encryption (NIP-04)
+## Documentation
 
-```typescript
-import { encrypt, decrypt } from '@humanjavaenterprises/nostr-crypto-utils';
-
-// Encrypt a message
-const encrypted = await encrypt(
-  'Secret message',
-  recipientPublicKey,
-  senderPrivateKey
-);
-
-// Decrypt a message
-const decrypted = await decrypt(
-  encrypted,
-  senderPublicKey,
-  recipientPrivateKey
-);
-```
+For detailed API documentation, visit our [TypeDoc Documentation](https://humanjavaenterprises.github.io/nostr-crypto-utils/).
 
-## Protocol Compliance
+## Support & Community
 
-This library implements the following Nostr Implementation Possibilities (NIPs):
+We welcome your feedback and contributions! Here's how you can get involved:
 
-- NIP-01: Basic protocol flow description
-- NIP-02: Contact List and Petnames
-- NIP-04: Encrypted Direct Message
-- NIP-09: Event Deletion
-- NIP-25: Reactions
-- NIP-28: Public Chat Channels
+- 🐛 [Report bugs](https://github.com/humanjavaenterprises/nostr-crypto-utils/issues/new?labels=bug&template=bug_report.md)
+- 💡 [Request features](https://github.com/humanjavaenterprises/nostr-crypto-utils/issues/new?labels=enhancement&template=feature_request.md)
+- 💬 [Start a discussion](https://github.com/humanjavaenterprises/nostr-crypto-utils/discussions)
+- 📖 [Read documentation](https://humanjavaenterprises.github.io/nostr-crypto-utils/)
+- 🔒 [Report security issues](https://github.com/humanjavaenterprises/nostr-crypto-utils/security/advisories/new)
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+We welcome contributions! Please follow these steps:
 
-## Security
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-If you discover a security vulnerability within this library, please send an e-mail to security@humanjavaenterprises.com. All security vulnerabilities will be promptly addressed.
+Before contributing:
+- Read our [Code of Conduct](CODE_OF_CONDUCT.md)
+- Check our [Contributing Guidelines](.github/CONTRIBUTING.md)
+- Review our [Security Policy](SECURITY.md)
+- Search [existing issues](https://github.com/humanjavaenterprises/nostr-crypto-utils/issues) before creating a new one
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](https://github.com/HumanjavaEnterprises/nostr-crypto-utils/blob/main/LICENSE) file for details.
+[MIT](LICENSE)
 
 ---
-
-Built with ❤️ by [Human Java Enterprises](https://github.com/HumanjavaEnterprises)
+<div align="center">
+Made with ❤️ by <a href="https://github.com/humanjavaenterprises">Humanjava Enterprises</a>
+</div>

package/dist/__tests__/crypto.test.js

@@ -1,4 +1,4 @@
-/// <reference types="jest" />
+import { describe, it, expect } from 'vitest';
 import { generateKeyPair, getPublicKey, validateKeyPair, signEvent, verifySignature, encrypt, decrypt } from '../index';
 describe('NOSTR Crypto Utils', () => {
     describe('Key Management', () => {
@@ -63,7 +63,7 @@ describe('NOSTR Crypto Utils', () => {
                 tags: [],
                 content: 'Hello, World!'
             };
-            const privateKey = await generateKeyPair().privateKey;
+            const privateKey = await (await generateKeyPair()).privateKey;
             const signedEvent = await signEvent(event, privateKey);
             expect(await verifySignature(signedEvent)).toBe(true);
         });
@@ -74,7 +74,7 @@ describe('NOSTR Crypto Utils', () => {
                 tags: [],
                 content: 'Hello, World!'
             };
-            const privateKey = await generateKeyPair().privateKey;
+            const privateKey = await (await generateKeyPair()).privateKey;
             const signedEvent = await signEvent(event, privateKey);
             // Tamper with the signature
             signedEvent.sig = signedEvent.sig.replace('a', 'b');
@@ -87,7 +87,7 @@ describe('NOSTR Crypto Utils', () => {
                 tags: [],
                 content: 'Hello, World!'
             };
-            const privateKey = await generateKeyPair().privateKey;
+            const privateKey = await (await generateKeyPair()).privateKey;
             const signedEvent = await signEvent(event, privateKey);
             // Tamper with the content which affects the hash
             signedEvent.content = 'Modified content';
@@ -100,7 +100,7 @@ describe('NOSTR Crypto Utils', () => {
                 tags: [],
                 content: 'Hello, World!'
             };
-            const privateKey = await generateKeyPair().privateKey;
+            const privateKey = await (await generateKeyPair()).privateKey;
             const signedEvent = await signEvent(event, privateKey);
             // Add invalid hex character
             signedEvent.sig = 'XYZ' + signedEvent.sig.slice(3);
@@ -109,22 +109,22 @@ describe('NOSTR Crypto Utils', () => {
     });
     describe('validateKeyPair', () => {
         it('should validate a correct key pair', async () => {
-            const privateKey = await generateKeyPair().privateKey;
+            const privateKey = await (await generateKeyPair()).privateKey;
             const publicKey = await getPublicKey(privateKey);
             const result = await validateKeyPair(publicKey, privateKey);
             expect(result.isValid).toBe(true);
             expect(result.error).toBeUndefined();
         });
         it('should reject mismatched key pair', async () => {
-            const privateKey1 = await generateKeyPair().privateKey;
-            const privateKey2 = await generateKeyPair().privateKey;
+            const privateKey1 = await (await generateKeyPair()).privateKey;
+            const privateKey2 = await (await generateKeyPair()).privateKey;
             const publicKey = await getPublicKey(privateKey1);
             const result = await validateKeyPair(publicKey, privateKey2);
             expect(result.isValid).toBe(false);
             expect(result.error).toBe('Public key does not match private key');
         });
         it('should handle invalid private key', async () => {
-            const publicKey = await getPublicKey(await generateKeyPair().privateKey);
+            const publicKey = await getPublicKey(await (await generateKeyPair()).privateKey);
             const result = await validateKeyPair(publicKey, 'invalid-private-key');
             expect(result.isValid).toBe(false);
             expect(result.error).toBe('Invalid key pair');
@@ -138,7 +138,7 @@ describe('NOSTR Crypto Utils', () => {
                 tags: [['p', '1234']],
                 content: 'Hello, World!'
             };
-            const privateKey = await generateKeyPair().privateKey;
+            const privateKey = await (await generateKeyPair()).privateKey;
             const signedEvent = await signEvent(event, privateKey);
             expect(signedEvent.sig).toBeTruthy();
             expect(signedEvent.id).toBeTruthy();
@@ -151,7 +151,7 @@ describe('NOSTR Crypto Utils', () => {
                 content: 'Hello, World!',
                 tags: [] // Adding the required tags property
             };
-            const privateKey = await generateKeyPair().privateKey;
+            const privateKey = await (await generateKeyPair()).privateKey;
             const signedEvent = await signEvent(event, privateKey);
             expect(signedEvent.sig).toBeTruthy();
             expect(signedEvent.id).toBeTruthy();
@@ -166,7 +166,7 @@ describe('NOSTR Crypto Utils', () => {
                 content: 'Hello, World!',
                 tags: [] // Add empty tags array to satisfy NostrEvent interface
             };
-            const privateKey = await generateKeyPair().privateKey;
+            const privateKey = await (await generateKeyPair()).privateKey;
             const signedEvent = await signEvent(event, privateKey);
             expect(signedEvent.tags).toEqual([]);
         });
@@ -177,7 +177,7 @@ describe('NOSTR Crypto Utils', () => {
                 tags: [],
                 created_at: Math.floor(Date.now() / 1000)
             };
-            const privateKey = await generateKeyPair().privateKey;
+            const privateKey = await (await generateKeyPair()).privateKey;
             const signedEvent = await signEvent(event, privateKey);
             expect(signedEvent.created_at).toBeDefined();
             expect(typeof signedEvent.created_at).toBe('number');

package/dist/__tests__/guards.test.js

@@ -1,3 +1,4 @@
+import { describe, it, expect } from 'vitest';
 import { isNostrEvent, isSignedNostrEvent } from '../types/guards';
 describe('Type Guards', () => {
     describe('isNostrEvent', () => {

package/dist/__tests__/integration.test.js

@@ -1,5 +1,6 @@
 import { formatEventForRelay, formatSubscriptionForRelay, formatCloseForRelay, formatAuthForRelay, parseNostrMessage, createMetadataEvent, createTextNoteEvent, createDirectMessageEvent, createChannelMessageEvent, extractReferencedEvents, extractMentionedPubkeys, createKindFilter, createAuthorFilter, createReplyFilter } from '../integration';
 import { NOSTR_KIND } from '../constants';
+import { describe, it, expect } from 'vitest';
 describe('Integration Utilities', () => {
     const mockSignedEvent = {
         id: '123',
@@ -36,20 +37,31 @@ describe('Integration Utilities', () => {
         it('should parse EVENT message', () => {
             const message = ['EVENT', mockSignedEvent];
             const parsed = parseNostrMessage(message);
-            expect(parsed.type).toBe('EVENT');
-            expect(parsed.payload).toEqual(mockSignedEvent);
+            expect(parsed).not.toBeNull();
+            if (parsed) {
+                expect(parsed.type).toBe('EVENT');
+                expect(parsed.payload).toEqual(mockSignedEvent);
+            }
         });
         it('should parse NOTICE message', () => {
             const message = ['NOTICE', 'test message'];
             const parsed = parseNostrMessage(message);
-            expect(parsed.type).toBe('NOTICE');
-            expect(parsed.payload).toBe('test message');
+            expect(parsed).not.toBeNull();
+            if (parsed) {
+                expect(parsed.type).toBe('NOTICE');
+                expect(parsed.payload).toBe('test message');
+            }
         });
         it('should parse OK message', () => {
             const message = ['OK', 'event1', true, 'success'];
             const parsed = parseNostrMessage(message);
-            expect(parsed.type).toBe('OK');
-            expect(parsed.payload).toEqual(['event1', true, 'success']);
+            expect(parsed).not.toBeNull();
+            if (parsed) {
+                expect(parsed.type).toBe('OK');
+                if (parsed.payload) {
+                    expect(parsed.payload).toEqual(['event1', true, 'success']);
+                }
+            }
         });
         it('should throw error for invalid message', () => {
             expect(() => parseNostrMessage('invalid')).toThrow('Invalid relay message: not an array');

package/dist/__tests__/nip_compliance.test.js

@@ -1,104 +1,105 @@
-import { generateKeyPair, signEvent, encrypt, decrypt, createEvent, validateEvent, validateSignedEvent, NostrEventKind, formatSubscriptionForRelay, formatEventForRelay, formatCloseForRelay } from '../index';
+import { describe, it, expect, beforeAll } from 'vitest';
+import { generateKeyPair, createEvent, signEvent, encrypt, decrypt, NostrEventKind, formatSubscriptionForRelay, formatEventForRelay, formatCloseForRelay } from '../index';
 describe('NIP-01: Basic Protocol Flow', () => {
     let keyPair;
     beforeAll(async () => {
         keyPair = await generateKeyPair();
     });
-    test('Event Creation and Signing Flow', async () => {
+    it('Event Creation and Signing Flow', async () => {
         // Create a text note (kind 1) as specified in NIP-01
         const event = createEvent({
             kind: NostrEventKind.TEXT_NOTE,
-            content: 'Hello Nostr!',
-            tags: [],
-            created_at: Math.floor(Date.now() / 1000)
+            content: 'Hello, Nostr!',
+            tags: []
         });
         // Sign the event
         const signedEvent = await signEvent(event, keyPair.privateKey);
-        // Verify event structure according to NIP-01
-        const validation = validateSignedEvent(signedEvent);
-        expect(validation.isValid).toBe(true);
+        // Verify the signed event structure
+        expect(signedEvent.id).toBeDefined();
+        expect(signedEvent.sig).toBeDefined();
         expect(signedEvent.pubkey).toBe(keyPair.publicKey);
-        expect(typeof signedEvent.created_at).toBe('number');
+        expect(signedEvent.kind).toBe(NostrEventKind.TEXT_NOTE);
+        expect(signedEvent.content).toBe('Hello, Nostr!');
+        expect(signedEvent.created_at).toBeDefined();
         expect(Array.isArray(signedEvent.tags)).toBe(true);
     });
-    test('Client-Relay Message Format', async () => {
+    it('Client-Relay Message Format', async () => {
         // Test REQ message format
-        const reqMessage = formatSubscriptionForRelay({ id: 'test_sub', filters: [{ kinds: [1], limit: 10 }] });
+        const reqMessage = formatSubscriptionForRelay({
+            id: 'test_sub',
+            filters: [{ kinds: [1], limit: 10 }]
+        });
         expect(reqMessage[0]).toBe('REQ');
-        expect(Array.isArray(reqMessage)).toBe(true);
-        expect(reqMessage.length).toBeGreaterThan(2);
+        expect(reqMessage[1]).toBe('test_sub');
+        expect(reqMessage[2]).toEqual({ kinds: [1], limit: 10 });
         // Test EVENT message format
-        const event2 = createEvent({
+        const keyPair = await generateKeyPair();
+        const event = createEvent({
             kind: NostrEventKind.TEXT_NOTE,
-            content: 'test message',
+            content: 'Test message',
             tags: []
         });
-        const signedEvent = await signEvent(event2, keyPair.privateKey);
+        const signedEvent = await signEvent(event, keyPair.privateKey);
         const eventMessage = formatEventForRelay(signedEvent);
         expect(eventMessage[0]).toBe('EVENT');
-        expect(eventMessage[1]).toMatchObject({
-            kind: NostrEventKind.TEXT_NOTE,
-            content: 'test message'
-        });
+        expect(eventMessage[1]).toEqual(signedEvent);
         // Test CLOSE message format
-        const closeMessage = JSON.stringify(formatCloseForRelay('subscription_id'));
-        const closeParsed = JSON.parse(closeMessage);
-        expect(closeParsed[0]).toBe('CLOSE');
-        expect(closeParsed[1]).toBe('subscription_id');
+        const closeMessage = formatCloseForRelay('test_sub');
+        expect(closeMessage[0]).toBe('CLOSE');
+        expect(closeMessage[1]).toBe('test_sub');
     });
 });
 describe('NIP-02: Contact List', () => {
-    test('Contact List Event Structure', async () => {
+    it('Contact List Event Structure', async () => {
         const keyPair = await generateKeyPair();
         const contacts = createEvent({
             kind: NostrEventKind.CONTACTS,
-            content: JSON.stringify([
-                {
-                    pubkey: '0123456789abcdef',
-                    relay: 'wss://relay.example.com',
-                    petname: 'friend'
-                }
-            ]),
-            tags: [],
+            content: JSON.stringify({
+                name: 'Alice',
+                about: 'I love Nostr!'
+            }),
             created_at: Math.floor(Date.now() / 1000)
         });
-        const validation = validateEvent(contacts);
-        expect(validation.isValid).toBe(true);
-        expect(contacts.kind).toBe(NostrEventKind.CONTACTS);
+        const signedContacts = await signEvent(contacts, keyPair.privateKey);
+        expect(signedContacts).toHaveProperty('id');
+        expect(signedContacts).toHaveProperty('sig');
+        // Verify the event structure
+        expect(signedContacts.kind).toBe(NostrEventKind.CONTACTS);
     });
 });
 describe('NIP-04: Encrypted Direct Messages', () => {
-    test('Message Encryption and Decryption', async () => {
+    let keyPair;
+    beforeAll(async () => {
+        keyPair = await generateKeyPair();
+    });
+    it('Message Encryption and Decryption', async () => {
         const alice = await generateKeyPair();
         const bob = await generateKeyPair();
         const message = 'Secret message for testing';
         // Encrypt message from Alice to Bob
         const encrypted = await encrypt(message, bob.publicKey, alice.privateKey);
         expect(encrypted).not.toBe(message);
-        // Bob decrypts message from Alice
+        // Decrypt message
         const decrypted = await decrypt(encrypted, alice.publicKey, bob.privateKey);
         expect(decrypted).toBe(message);
     });
-    test('Encrypted DM Event Structure', async () => {
-        const sender = await generateKeyPair();
+    it('Encrypted DM Event Structure', async () => {
         const recipient = await generateKeyPair();
-        const message = 'Secret message';
-        const encrypted = await encrypt(message, recipient.publicKey, sender.privateKey);
         const dmEvent = createEvent({
             kind: NostrEventKind.ENCRYPTED_DIRECT_MESSAGE,
-            content: encrypted,
-            tags: [['p', recipient.publicKey]],
-            created_at: Math.floor(Date.now() / 1000)
+            content: 'Encrypted message',
+            tags: [['p', recipient.publicKey]]
         });
-        const validation = validateEvent(dmEvent);
-        expect(validation.isValid).toBe(true);
-        expect(dmEvent.kind).toBe(NostrEventKind.ENCRYPTED_DIRECT_MESSAGE);
-        expect(dmEvent.tags[0][0]).toBe('p');
-        expect(dmEvent.tags[0][1]).toBe(recipient.publicKey);
+        const signedDM = await signEvent(dmEvent, keyPair.privateKey);
+        expect(signedDM).toHaveProperty('id');
+        expect(signedDM).toHaveProperty('sig');
+        expect(signedDM.kind).toBe(NostrEventKind.ENCRYPTED_DIRECT_MESSAGE);
+        expect(signedDM.tags[0][0]).toBe('p');
+        expect(signedDM.tags[0][1]).toBe(recipient.publicKey);
     });
 });
 describe('NIP-09: Event Deletion', () => {
-    test('Event Deletion Structure', async () => {
+    it('Event Deletion Structure', async () => {
         const keyPair = await generateKeyPair();
         const originalEvent = await signEvent(createEvent({
             kind: NostrEventKind.TEXT_NOTE,
@@ -112,8 +113,10 @@ describe('NIP-09: Event Deletion', () => {
             tags: [['e', originalEvent.id]],
             created_at: Math.floor(Date.now() / 1000)
         });
-        const validation = validateEvent(deleteEvent);
-        expect(validation.isValid).toBe(true);
+        const signedDeleteEvent = await signEvent(deleteEvent, keyPair.privateKey);
+        expect(signedDeleteEvent).toHaveProperty('id');
+        expect(signedDeleteEvent).toHaveProperty('sig');
+        // Verify the event structure
         expect(deleteEvent.kind).toBe(NostrEventKind.DELETE);
         expect(deleteEvent.tags[0][0]).toBe('e');
         expect(deleteEvent.tags[0][1]).toBe(originalEvent.id);

package/dist/__tests__/setup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/setup.js

@@ -0,0 +1,5 @@
+import { webcrypto } from 'node:crypto';
+// Configure crypto for test environment
+if (typeof globalThis.crypto === 'undefined') {
+    globalThis.crypto = webcrypto;
+}