nostr-crypto-utils 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Human Java Enterprises
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# @humanjavaenterprises/nostr-crypto-utils
+
+A comprehensive cryptographic utilities package for NOSTR applications, designed to work seamlessly with [@humanjavaenterprises/nostr-nsec-seedphrase](https://github.com/humanjavaenterprises/nostr-nsec-seedphrase).
+
+⚠️ **Important Security Notice**
+
+This library handles cryptographic keys and seed phrases that are critical for securing your Nostr identity and data. Just like Bitcoin, any seed phrase or private key (`nsec`) generated by this library must be stored with the utmost security and care.
+
+Developers using this library must inform their users about the critical nature of managing seed phrases, `nsec`, and hex keys. It is the user's responsibility to securely store and manage these keys. The library and its authors disclaim any responsibility or liability for lost keys, seed phrases, or data resulting from mismanagement.
+
+## Features
+
+- 🔑 Complete key pair management (generation, validation, public key derivation)
+- 📝 Event signing and verification
+- 🔒 NIP-04 encryption and decryption
+- 🌱 Seed phrase support via integration with nostr-nsec-seedphrase
+- 📦 Modern ESM package with full TypeScript support
+- ⚡️ Built on established crypto libraries (noble-curves, noble-hashes)
+- 🤝 Compatible with nostr-tools as a peer dependency
+
+## Installation
+
+```bash
+npm install @humanjavaenterprises/nostr-crypto-utils @humanjavaenterprises/nostr-nsec-seedphrase nostr-tools
+```
+
+## Architecture Overview
+
+This library serves as a crucial middleware layer in NOSTR applications:
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  Your NOSTR App                     │
+└───────────────────────┬─────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────┐
+│           @humanjavaenterprises/nostr-crypto-utils  │
+│                                                     │
+│  ┌─────────────────┐        ┌──────────────────┐    │
+│  │   Key Manager   │        │  Event Handler   │    │
+│  └────────┬────────┘        └────────┬─────────┘    │
+│           │                          │              │
+│  ┌────────▼────────┐        ┌───────▼─────────┐    │
+│  │ nostr-nsec-     │        │   nostr-tools   │    │
+│  │ seedphrase      │        │                 │    │
+│  └─────────────────┘        └─────────────────┘    │
+└─────────────────────────────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────┐
+│               NOSTR Protocol / Relays               │
+└─────────────────────────────────────────────────────┘
+```
+
+## Usage Examples
+
+### Key Management
+
+```typescript
+import { generateKeyPair, derivePublicKey, validateKeyPair } from '@humanjavaenterprises/nostr-crypto-utils';
+
+// Generate a new key pair
+const keyPair = await generateKeyPair();
+console.log(keyPair);
+// { privateKey: '...', publicKey: '...' }
+
+// Generate from seed phrase
+const seedPhrase = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+const keyPairFromSeed = await generateKeyPair(seedPhrase);
+
+// Derive public key from private key
+const publicKey = await derivePublicKey(keyPair.privateKey);
+
+// Validate a key pair
+const validation = await validateKeyPair(keyPair.publicKey, keyPair.privateKey);
+console.log(validation);
+// { isValid: true, error: undefined }
+```
+
+### Event Operations
+
+```typescript
+import { signEvent, verifySignature } from '@humanjavaenterprises/nostr-crypto-utils';
+
+// Create and sign a NOSTR event
+const event = {
+  kind: 1,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [],
+  content: 'Hello NOSTR!'
+};
+
+const signedEvent = await signEvent(event, keyPair.privateKey);
+console.log(signedEvent);
+// { id: '...', pubkey: '...', sig: '...', ...event }
+
+// Verify an event signature
+const isValid = await verifySignature(signedEvent);
+console.log(isValid); // true
+```
+
+### Encryption (NIP-04)
+
+```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
+);
+```
+
+## Integration Examples
+
+### Authentication Flow
+
+```typescript
+import { generateKeyPair, signEvent } from '@humanjavaenterprises/nostr-crypto-utils';
+
+async function authenticateUser(seedPhrase?: string) {
+  // Generate or recover keys
+  const keyPair = await generateKeyPair(seedPhrase);
+  
+  // Create auth event
+  const authEvent = {
+    kind: 22242,
+    created_at: Math.floor(Date.now() / 1000),
+    tags: [['challenge', 'authentication-challenge']],
+    content: 'Authenticating...'
+  };
+  
+  // Sign the event
+  const signedAuthEvent = await signEvent(authEvent, keyPair.privateKey);
+  
+  return signedAuthEvent;
+}
+```
+
+### Secure Messaging
+
+```typescript
+import { generateKeyPair, encrypt, decrypt } from '@humanjavaenterprises/nostr-crypto-utils';
+
+async function secureMessaging() {
+  // Generate keys for both parties
+  const alice = await generateKeyPair();
+  const bob = await generateKeyPair();
+  
+  // Alice encrypts a message for Bob
+  const encrypted = await encrypt(
+    'Hey Bob!',
+    bob.publicKey,
+    alice.privateKey
+  );
+  
+  // Bob decrypts Alice's message
+  const decrypted = await decrypt(
+    encrypted,
+    alice.publicKey,
+    bob.privateKey
+  );
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT
+
+## Related Projects
+
+- [@humanjavaenterprises/nostr-nsec-seedphrase](https://github.com/humanjavaenterprises/nostr-nsec-seedphrase) - Seed phrase management for NOSTR
+- [nostr-tools](https://github.com/nbd-wtf/nostr-tools) - Core NOSTR functionality

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import type { KeyPair, NostrEvent, SignedNostrEvent, ValidationResult } from './types';
+/**
+ * Generate a private key for use with NOSTR
+ */
+export declare function generatePrivateKey(): string;
+/**
+ * Get a public key from a private key
+ */
+export declare function getPublicKey(privateKey: string): string;
+/**
+ * Generate a new key pair
+ */
+export declare function generateKeyPair(): KeyPair;
+/**
+ * Get the hash of a NOSTR event
+ */
+export declare function getEventHash(event: NostrEvent): string;
+/**
+ * Sign a NOSTR event
+ */
+export declare function signEvent(event: NostrEvent, privateKey: string): Promise<SignedNostrEvent>;
+/**
+ * Verify a signature
+ */
+export declare function verifySignature(event: SignedNostrEvent): boolean;
+/**
+ * Validate a key pair
+ */
+export declare function validateKeyPair(publicKey: string, privateKey: string): ValidationResult;
+/**
+ * Encrypt a message using NIP-04
+ */
+export declare function encrypt(message: string, recipientPubKey: string, senderPrivKey: string): Promise<string>;
+/**
+ * Decrypt a message using NIP-04
+ */
+export declare function decrypt(encryptedMessage: string, senderPubKey: string, recipientPrivKey: string): Promise<string>;

package/dist/index.js

@@ -0,0 +1,104 @@
+import { schnorr } from '@noble/curves/secp256k1';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { sha256 } from '@noble/hashes/sha256';
+import { randomBytes } from '@noble/hashes/utils';
+import * as secp256k1 from '@noble/secp256k1';
+import { generateSecretKey, getPublicKey as getNostrPublicKey } from 'nostr-tools';
+/**
+ * Generate a private key for use with NOSTR
+ */
+export function generatePrivateKey() {
+    return bytesToHex(generateSecretKey());
+}
+/**
+ * Get a public key from a private key
+ */
+export function getPublicKey(privateKey) {
+    return getNostrPublicKey(hexToBytes(privateKey));
+}
+/**
+ * Generate a new key pair
+ */
+export function generateKeyPair() {
+    const privateKey = generatePrivateKey();
+    const publicKey = getPublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+/**
+ * Get the hash of a NOSTR event
+ */
+export function getEventHash(event) {
+    const serialized = JSON.stringify([
+        0,
+        event.pubkey,
+        event.created_at,
+        event.kind,
+        event.tags,
+        event.content,
+    ]);
+    const hash = sha256(new TextEncoder().encode(serialized));
+    return bytesToHex(hash);
+}
+/**
+ * Sign a NOSTR event
+ */
+export async function signEvent(event, privateKey) {
+    const hash = getEventHash(event);
+    const signature = bytesToHex(await schnorr.sign(hexToBytes(hash), hexToBytes(privateKey)));
+    return {
+        ...event,
+        id: hash,
+        sig: signature,
+        pubkey: getPublicKey(privateKey)
+    };
+}
+/**
+ * Verify a signature
+ */
+export function verifySignature(event) {
+    const hash = getEventHash(event);
+    return schnorr.verify(hexToBytes(event.sig), hexToBytes(hash), hexToBytes(event.pubkey));
+}
+/**
+ * Validate a key pair
+ */
+export function validateKeyPair(publicKey, privateKey) {
+    try {
+        const derivedPubKey = getPublicKey(privateKey);
+        return {
+            isValid: derivedPubKey === publicKey,
+            error: derivedPubKey !== publicKey ? 'Public key does not match derived key' : undefined
+        };
+    }
+    catch (error) {
+        return {
+            isValid: false,
+            error: error instanceof Error ? error.message : 'Unknown error occurred'
+        };
+    }
+}
+/**
+ * Encrypt a message using NIP-04
+ */
+export async function encrypt(message, recipientPubKey, senderPrivKey) {
+    const sharedSecret = secp256k1.getSharedSecret(senderPrivKey, '02' + recipientPubKey);
+    const iv = randomBytes(16);
+    const key = sha256(sharedSecret);
+    const textEncoder = new TextEncoder();
+    const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'AES-CBC' }, false, ['encrypt']);
+    const encrypted = await crypto.subtle.encrypt({ name: 'AES-CBC', iv }, cryptoKey, textEncoder.encode(message));
+    return bytesToHex(iv) + bytesToHex(new Uint8Array(encrypted));
+}
+/**
+ * Decrypt a message using NIP-04
+ */
+export async function decrypt(encryptedMessage, senderPubKey, recipientPrivKey) {
+    const sharedSecret = secp256k1.getSharedSecret(recipientPrivKey, '02' + senderPubKey);
+    const key = sha256(sharedSecret);
+    const iv = hexToBytes(encryptedMessage.slice(0, 32));
+    const ciphertext = hexToBytes(encryptedMessage.slice(32));
+    const textDecoder = new TextDecoder();
+    const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'AES-CBC' }, false, ['decrypt']);
+    const decrypted = await crypto.subtle.decrypt({ name: 'AES-CBC', iv }, cryptoKey, ciphertext);
+    return textDecoder.decode(new Uint8Array(decrypted));
+}

package/dist/types/index.d.ts

@@ -0,0 +1,24 @@
+export interface KeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+export interface NostrEvent {
+    kind: number;
+    created_at: number;
+    content: string;
+    tags: string[][];
+    pubkey?: string;
+}
+export interface SignedNostrEvent extends NostrEvent {
+    id: string;
+    sig: string;
+    pubkey: string;
+}
+export interface EncryptionResult {
+    ciphertext: string;
+    iv: string;
+}
+export interface ValidationResult {
+    isValid: boolean;
+    error?: string;
+}

package/dist/types/index.js

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

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "nostr-crypto-utils",
+  "version": "0.1.4",
+  "description": "Cryptographic utilities for NOSTR",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "nostr",
+    "crypto",
+    "utilities"
+  ],
+  "author": "Human Java Enterprises",
+  "license": "MIT",
+  "dependencies": {
+    "@noble/curves": "^1.2.0",
+    "@noble/hashes": "^1.3.2",
+    "@noble/secp256k1": "^2.0.0",
+    "@humanjavaenterprises/nostr-nsec-seedphrase": "^0.1.0",
+    "nostr-tools": "^2.1.4"
+  },
+  "peerDependencies": {
+    "nostr-tools": "^2.1.4"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.5",
+    "@types/node": "^20.8.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.2.2"
+  }
+}