@ubay182/sveltekit-hpke-wrapper 1.0.2 → 1.0.3

package/README.md

@@ -4,12 +4,12 @@ HPKE (Hybrid Public Key Encryption) wrapper for SvelteKit applications with end-
 
 ## 🚀 Features
 
-- ✅ **Complete HPKE Implementation** - RFC 9180 compliant
-- ✅ **End-to-End Encryption** - Client ↔ Server encryption
-- ✅ **SvelteKit Integration** - Ready-to-use API endpoint creators
-- ✅ **TypeScript Support** - Full type definitions
-- ✅ **X25519 Key Exchange** - Elliptic curve Diffie-Hellman
-- ✅ **AES-128-GCM & ChaCha20** - Authenticated encryption
+- ✅ **Complete HPKE Implementation** — RFC 9180 compliant
+- ✅ **End-to-End Encryption** — Client ↔ Server encryption
+- ✅ **SvelteKit Integration** — Ready-to-use API endpoint creators
+- ✅ **TypeScript Support** — Full type definitions
+- ✅ **X25519 Key Exchange** — Elliptic curve Diffie-Hellman
+- ✅ **AES-128-GCM & ChaCha20-Poly1305** — Authenticated encryption
 
 ## 📦 Installation
 
@@ -17,76 +17,128 @@ HPKE (Hybrid Public Key Encryption) wrapper for SvelteKit applications with end-
 npm install @ubay182/sveltekit-hpke-wrapper
 # or
 pnpm add @ubay182/sveltekit-hpke-wrapper
-# or
-yarn add @ubay182/sveltekit-hpke-wrapper
 ```
 
 ## 🎯 Quick Start
 
-### 1. Basic Usage (Client-Side)
+### 1. Client-Side (Svelte Component)
+
+```svelte
+<script lang="ts">
+	import {
+		generateKeyPair,
+		hpkeEncrypt,
+		hpkeDecrypt,
+		uint8ArrayToBase64,
+		base64ToUint8Array,
+		createHpkeSuite
+	} from '@ubay182/sveltekit-hpke-wrapper';
+
+	let serverPubKey = $state<any>(null);
+	let clientPrivKey = $state<any>(null);
+	let clientPubKeyB64 = $state('');
+	let decryptedText = $state('');
+
+	// Step 1: Fetch server public key
+	async function getServerKey() {
+		const res = await fetch('/api/hpke-keys');
+		const data = await res.json();
+
+		const keyBytes = base64ToUint8Array(data.publicKey);
+		const suite = createHpkeSuite();
+		serverPubKey = await suite.kem.importKey('raw', keyBytes.buffer as ArrayBuffer, true);
+	}
 
-```typescript
-import {
-	generateKeyPair,
-	hpkeEncrypt,
-	hpkeDecrypt,
-	exportKeyToBase64,
-	importKeyFromBase64
-} from '@ubay182/sveltekit-hpke-wrapper';
+	// Step 2: Generate client key pair
+	async function generateClientKeys() {
+		const keys = await generateKeyPair();
+		clientPrivKey = keys.privateKey;
+		clientPubKeyB64 = uint8ArrayToBase64(keys.publicKeyRaw);
+	}
 
-// Generate key pair
-const { publicKey, privateKey, publicKeyRaw } = await generateKeyPair();
+	// Step 3: Encrypt & send
+	async function encryptAndSend(payload: any) {
+		const message = JSON.stringify(payload);
+		const result = await hpkeEncrypt(message, serverPubKey);
 
-// Export public key for transmission
-const publicKeyBase64 = exportKeyToBase64(publicKey);
+		const ciphertext = uint8ArrayToBase64(new Uint8Array(result.ciphertext));
+		const enc = uint8ArrayToBase64(new Uint8Array(result.enc));
 
-// Import server's public key
-const serverPublicKey = await importKeyFromBase64(serverPublicKeyBase64);
+		const res = await fetch('/api/hpke-proxy', {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ ciphertext, enc, clientPublicKey: clientPubKeyB64 })
+		});
 
-// Encrypt message
-const { ciphertext, enc } = await hpkeEncrypt('Secret message', serverPublicKey);
+		const data = await res.json();
+		return data; // { ciphertext, enc }
+	}
 
-// Decrypt message
-const decrypted = await hpkeDecrypt(ciphertext, enc, privateKey);
-```
+	// Step 4: Decrypt server response
+	async function decryptResponse(encryptedData: { ciphertext: string; enc: string }) {
+		const ct = base64ToUint8Array(encryptedData.ciphertext);
+		const enc = base64ToUint8Array(encryptedData.enc);
 
-### 2. Server-Side with SvelteKit
+		decryptedText = await hpkeDecrypt(
+			ct.buffer as ArrayBuffer,
+			enc.buffer as ArrayBuffer,
+			clientPrivKey
+		);
+	}
+</script>
+```
 
-```typescript
-// src/routes/api/hpke/+server.ts
-import { createHpkeEndpoint } from '@ubay182/sveltekit-hpke-wrapper';
+### 2. Server-Side (SvelteKit Routes)
 
-const { GET, POST } = createHpkeEndpoint({
-	onRequest: async (decryptedData, request) => {
-		// Process the decrypted request
-		const response = await fetch('https://api.example.com/data', {
-			method: 'POST',
-			headers: { 'Content-Type': 'application/json' },
-			body: JSON.stringify(decryptedData)
-		});
+Create a shared HPKE server instance so all routes use the same key pair:
 
-		return await response.json();
-	}
-});
+```typescript
+// src/lib/hpke-server-instance.ts
+import { createHpkeServer, type HpkeServerInstance } from '@ubay182/sveltekit-hpke-wrapper';
 
-export { GET, POST };
+export const hpkeServer: HpkeServerInstance = createHpkeServer({ autoGenerateKeys: false });
 ```
 
-### 3. Manual Server Setup
+```typescript
+// src/routes/api/hpke-keys/+server.ts
+import { hpkeServer } from '$lib/hpke-server-instance';
+
+export async function GET() {
+	const publicKey = await hpkeServer.init();
+
+	return new Response(
+		JSON.stringify({
+			publicKey,
+			algorithm: 'X25519-HKDF-SHA256',
+			aead: 'AES-128-GCM'
+		}),
+		{
+			headers: { 'Content-Type': 'application/json' }
+		}
+	);
+}
+```
 
 ```typescript
-import { createHpkeServer } from '@ubay182/sveltekit-hpke-wrapper';
+// src/routes/api/hpke-proxy/+server.ts
+import { hpkeServer } from '$lib/hpke-server-instance';
+
+export async function POST({ request }: { request: Request }) {
+	const body = await request.json();
+	const { ciphertext, enc, clientPublicKey } = body;
 
-const server = createHpkeServer();
+	// Decrypt client message
+	const decrypted = await hpkeServer.decrypt(ciphertext, enc, clientPublicKey);
 
-// Get server public key
-const publicKey = server.getPublicKeyBase64();
+	// ... process decrypted data, call external APIs, etc. ...
 
-// Decrypt client message
-const decrypted = await server.decrypt(ciphertext, enc, clientPublicKey);
+	// Encrypt response
+	const encrypted = await hpkeServer.encrypt(responseData, clientPublicKey);
 
-// Encrypt response
-const encrypted = await server.encrypt(responseData, clientPublicKey);
+	return new Response(JSON.stringify(encrypted), {
+		headers: { 'Content-Type': 'application/json' }
+	});
+}
 ```
 
 ## 📚 API Reference
@@ -99,59 +151,76 @@ Generate a new HPKE key pair.
 
 ```typescript
 async function generateKeyPair(): Promise<{
-	publicKey: any; // XCryptoKey for HPKE operations
-	privateKey: any; // XCryptoKey for HPKE operations
+	publicKey: any; // XCryptoKey
+	privateKey: any; // XCryptoKey
 	publicKeyRaw: Uint8Array; // Raw bytes for transmission
 }>;
 ```
 
 #### `hpkeEncrypt(message, recipientPublicKey)`
 
-Encrypt a message.
+Encrypt a message. Returns `{ ciphertext: ArrayBuffer, enc: ArrayBuffer }`.
 
 ```typescript
-async function hpkeEncrypt(
-	message: string,
-	recipientPublicKey: any
-): Promise<{
-	ciphertext: ArrayBuffer;
-	enc: ArrayBuffer;
-}>;
+const { ciphertext, enc } = await hpkeEncrypt('Secret message', serverPublicKey);
 ```
 
 #### `hpkeDecrypt(ciphertext, enc, recipientPrivateKey)`
 
-Decrypt a message.
+Decrypt a message. Returns plaintext string.
 
 ```typescript
-async function hpkeDecrypt(
-	ciphertext: ArrayBuffer,
-	enc: Uint8Array | ArrayBuffer,
-	recipientPrivateKey: any
-): Promise<string>;
+const decrypted = await hpkeDecrypt(ciphertextBuffer, encBuffer, privateKey);
+```
+
+#### `createHpkeSuite()`
+
+Create an HPKE suite with AES-128-GCM.
+
+```typescript
+const suite = createHpkeSuite();
+const keyPair = await suite.kem.generateKeyPair();
+const importedKey = await suite.kem.importKey('raw', keyBytes.buffer, true);
+```
+
+#### `createHpkeSuiteChaCha20()`
+
+Create an HPKE suite with ChaCha20-Poly1305.
+
+```typescript
+const suite = createHpkeSuiteChaCha20();
 ```
 
 #### `exportKeyToBase64(publicKey)`
 
-Export public key to base64.
+Export public key to base64 string.
 
 ```typescript
-function exportKeyToBase64(publicKey: any): string;
+const b64 = exportKeyToBase64(publicKey);
 ```
 
 #### `importKeyFromBase64(base64)`
 
-Import public key from base64.
+Import public key from base64 string.
+
+```typescript
+const publicKey = await importKeyFromBase64(b64String);
+```
+
+#### `uint8ArrayToBase64(data)` / `base64ToUint8Array(base64)`
+
+Utility functions for encoding/decoding.
 
 ```typescript
-async function importKeyFromBase64(base64: string): Promise<any>;
+const b64 = uint8ArrayToBase64(bytes);
+const bytes = base64ToUint8Array(b64);
 ```
 
 ### Server Functions
 
 #### `createHpkeServer(config?)`
 
-Create HPKE server instance.
+Create an HPKE server instance with key management.
 
 ```typescript
 interface HpkeServerConfig {
@@ -159,15 +228,10 @@ interface HpkeServerConfig {
 }
 
 interface HpkeServerInstance {
+	init(): Promise<string>; // Generate keys, return public key as base64
 	getPublicKeyBase64(): string;
 	decrypt(ciphertext: string, enc: string, clientPublicKey: string): Promise<string>;
-	encrypt(
-		message: string,
-		clientPublicKey: string
-	): Promise<{
-		ciphertext: string;
-		enc: string;
-	}>;
+	encrypt(message: string, clientPublicKey: string): Promise<{ ciphertext: string; enc: string }>;
 }
 ```
 
@@ -175,93 +239,59 @@ interface HpkeServerInstance {
 
 #### `createHpkeEndpoint(config?)`
 
-Create complete API endpoints.
-
-```typescript
-interface HpkeEndpointConfig {
-	autoGenerateKeys?: boolean;
-	onRequest?: (decrypted: any, request: Request) => Promise<any>;
-	onError?: (error: Error, request: Request) => Promise<Response>;
-}
-```
-
-## 🔧 Advanced Usage
-
-### Custom Algorithm (ChaCha20-Poly1305)
-
-```typescript
-import { createHpkeSuiteChaCha20 } from '@ubay182/sveltekit-hpke-wrapper';
-
-const suite = createHpkeSuiteChaCha20();
-// Use suite for encryption/decryption
-```
-
-### Manual Key Management
-
-```typescript
-import { createHpkeServer } from '@ubay182/sveltekit-hpke-wrapper';
-
-// Disable auto-generation
-const server = createHpkeServer({ autoGenerateKeys: false });
-
-// Set keys manually later
-// (You'll need to extend the server instance with a setKeys method)
-```
-
-### Error Handling
+Create complete GET/POST handlers for a SvelteKit route.
 
 ```typescript
 const { GET, POST } = createHpkeEndpoint({
-	onError: async (error, request) => {
-		console.error('HPKE Error:', error);
-
-		return new Response(
-			JSON.stringify({
-				error: 'Encryption failed',
-				code: 'HPKE_ERROR'
-			}),
-			{ status: 500 }
-		);
+	onRequest: async (decryptedData, request) => {
+		// Process decrypted request
+		return await fetch('https://api.example.com/data', {
+			method: 'POST',
+			body: JSON.stringify(decryptedData)
+		}).then((r) => r.json());
 	}
 });
 ```
 
-## 🔐 Security Notes
-
-⚠️ **Important**: This is a wrapper library for convenience. For production:
-
-1. **Key Storage**: Use HSM, AWS KMS, or Azure Key Vault
-2. **HTTPS**: Always use HTTPS in production
-3. **Authentication**: Implement proper auth mechanisms
-4. **Rate Limiting**: Add rate limiting to prevent abuse
-5. **Key Rotation**: Implement regular key rotation
-6. **Audit**: Have security audits performed
-
-## 📖 How It Works
+## 🔐 How It Works
 
 ```
 Client                          Server
   │                               │
-  ├─── GET /api/hpke ───────────>│
+  ├─── GET /api/hpke-keys ──────>│
   │                               │
   │<──── Public Key (base64) ────│
   │                               │
-  ├─── Encrypt with Public Key ──│
+  ├─── generateKeyPair() ────────│  (client generates its own keys)
+  │                               │
+  ├─── hpkeEncrypt(payload) ────│
   │                               │
-  ├─── POST Encrypted Data ─────>│
+  ├─── POST { ciphertext, enc, ─>│
+  │       clientPublicKey }      │
   │                               │
-  │                               ├─── Decrypt ──┐
-  │                               │               │
-  │                               │<── Process ───┘
+  │                               ├─── decrypt() ──┐
+  │                               │                 │
+  │                               │<── Process ─────┘
+  │                               │                 │
+  │                               │<── encrypt() ───┘
   │                               │
-  │                               ├─── Encrypt ──┐
-  │                               │               │
-  │<──── Encrypted Response ─────│<──────────────┘
+  │<──── { ciphertext, enc } ────│
   │                               │
-  └─── Decrypt Response ─────────┘
+  └─── hpkeDecrypt(response) ────┘
 ```
 
-## 🧪 Testing
+## 🔐 Security Notes
+
+⚠️ **Important**: This is a convenience wrapper library. For production:
+
+1. **Key Storage** — Use HSM, AWS KMS, or Azure Key Vault
+2. **HTTPS** — Always use HTTPS in production
+3. **Authentication** — Implement proper auth mechanisms
+4. **Rate Limiting** — Add rate limiting to prevent abuse
+5. **Key Rotation** — Implement regular key rotation
+6. **Audit** — Have security audits performed
+
+## 🧪 Development
 
 ```bash
 # Build the package
@@ -270,7 +300,7 @@ npm run build
 # Type check
 npm run lint
 
-# Watch mode for development
+# Watch mode
 npm run dev
 ```
 
@@ -278,12 +308,8 @@ npm run dev
 
 MIT
 
-## 🤝 Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
 ## 📚 Resources
 
-- [RFC 9180 - HPKE Specification](https://www.rfc-editor.org/rfc/rfc9180.html)
+- [RFC 9180 — HPKE Specification](https://www.rfc-editor.org/rfc/rfc9180.html)
 - [hpke-js Library](https://github.com/dajiaji/hpke-js)
 - [SvelteKit Documentation](https://kit.svelte.dev/docs)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ubay182/sveltekit-hpke-wrapper",
-	"version": "1.0.2",
+	"version": "1.0.3",
 	"description": "HPKE (Hybrid Public Key Encryption) wrapper for SvelteKit applications with end-to-end encryption support",
 	"type": "module",
 	"main": "./dist/index.js",