@ubay182/sveltekit-hpke-wrapper 1.0.1 → 1.0.3

package/README.md

@@ -1,92 +1,144 @@
-# @hpke/sveltekit-wrapper
+# @ubay182/sveltekit-hpke-wrapper
 
 HPKE (Hybrid Public Key Encryption) wrapper for SvelteKit applications with end-to-end encryption support.
 
 ## 🚀 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
 
 ```bash
-npm install @hpke/sveltekit-wrapper
+npm install @ubay182/sveltekit-hpke-wrapper
 # or
-pnpm add @hpke/sveltekit-wrapper
-# or
-yarn add @hpke/sveltekit-wrapper
+pnpm add @ubay182/sveltekit-hpke-wrapper
 ```
 
 ## 🎯 Quick Start
 
-### 1. Basic Usage (Client-Side)
-
-```typescript
-import { 
-  generateKeyPair, 
-  hpkeEncrypt, 
-  hpkeDecrypt,
-  exportKeyToBase64,
-  importKeyFromBase64 
-} from '@hpke/sveltekit-wrapper';
-
-// Generate key pair
-const { publicKey, privateKey, publicKeyRaw } = await generateKeyPair();
+### 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);
+	}
+
+	// Step 2: Generate client key pair
+	async function generateClientKeys() {
+		const keys = await generateKeyPair();
+		clientPrivKey = keys.privateKey;
+		clientPubKeyB64 = uint8ArrayToBase64(keys.publicKeyRaw);
+	}
+
+	// Step 3: Encrypt & send
+	async function encryptAndSend(payload: any) {
+		const message = JSON.stringify(payload);
+		const result = await hpkeEncrypt(message, serverPubKey);
+
+		const ciphertext = uint8ArrayToBase64(new Uint8Array(result.ciphertext));
+		const enc = uint8ArrayToBase64(new Uint8Array(result.enc));
+
+		const res = await fetch('/api/hpke-proxy', {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ ciphertext, enc, clientPublicKey: clientPubKeyB64 })
+		});
+
+		const data = await res.json();
+		return data; // { ciphertext, enc }
+	}
+
+	// Step 4: Decrypt server response
+	async function decryptResponse(encryptedData: { ciphertext: string; enc: string }) {
+		const ct = base64ToUint8Array(encryptedData.ciphertext);
+		const enc = base64ToUint8Array(encryptedData.enc);
+
+		decryptedText = await hpkeDecrypt(
+			ct.buffer as ArrayBuffer,
+			enc.buffer as ArrayBuffer,
+			clientPrivKey
+		);
+	}
+</script>
+```
 
-// Export public key for transmission
-const publicKeyBase64 = exportKeyToBase64(publicKey);
+### 2. Server-Side (SvelteKit Routes)
 
-// Import server's public key
-const serverPublicKey = await importKeyFromBase64(serverPublicKeyBase64);
+Create a shared HPKE server instance so all routes use the same key pair:
 
-// Encrypt message
-const { ciphertext, enc } = await hpkeEncrypt('Secret message', serverPublicKey);
+```typescript
+// src/lib/hpke-server-instance.ts
+import { createHpkeServer, type HpkeServerInstance } from '@ubay182/sveltekit-hpke-wrapper';
 
-// Decrypt message
-const decrypted = await hpkeDecrypt(ciphertext, enc, privateKey);
+export const hpkeServer: HpkeServerInstance = createHpkeServer({ autoGenerateKeys: false });
 ```
 
-### 2. Server-Side with SvelteKit
-
 ```typescript
-// src/routes/api/hpke/+server.ts
-import { createHpkeEndpoint } from '@hpke/sveltekit-wrapper';
-
-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)
-    });
-    
-    return await response.json();
-  }
-});
-
-export { GET, POST };
+// 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' }
+		}
+	);
+}
 ```
 
-### 3. Manual Server Setup
-
 ```typescript
-import { createHpkeServer } from '@hpke/sveltekit-wrapper';
+// src/routes/api/hpke-proxy/+server.ts
+import { hpkeServer } from '$lib/hpke-server-instance';
 
-const server = createHpkeServer();
+export async function POST({ request }: { request: Request }) {
+	const body = await request.json();
+	const { ciphertext, enc, clientPublicKey } = body;
 
-// Get server public key
-const publicKey = server.getPublicKeyBase64();
+	// Decrypt client message
+	const decrypted = await hpkeServer.decrypt(ciphertext, enc, clientPublicKey);
 
-// Decrypt client message
-const decrypted = await server.decrypt(ciphertext, enc, clientPublicKey);
+	// ... process decrypted data, call external APIs, etc. ...
 
-// Encrypt response
-const encrypted = await server.encrypt(responseData, clientPublicKey);
+	// Encrypt response
+	const encrypted = await hpkeServer.encrypt(responseData, clientPublicKey);
+
+	return new Response(JSON.stringify(encrypted), {
+		headers: { 'Content-Type': 'application/json' }
+	});
+}
 ```
 
 ## 📚 API Reference
@@ -94,164 +146,152 @@ const encrypted = await server.encrypt(responseData, clientPublicKey);
 ### Core Functions
 
 #### `generateKeyPair()`
+
 Generate a new HPKE key pair.
 
 ```typescript
 async function generateKeyPair(): Promise<{
-  publicKey: any;           // XCryptoKey for HPKE operations
-  privateKey: any;          // XCryptoKey for HPKE operations
-  publicKeyRaw: Uint8Array; // Raw bytes for transmission
-}>
+	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);
 ```
 
-#### `exportKeyToBase64(publicKey)`
-Export public key to base64.
+#### `createHpkeSuite()`
+
+Create an HPKE suite with AES-128-GCM.
 
 ```typescript
-function exportKeyToBase64(publicKey: any): string
+const suite = createHpkeSuite();
+const keyPair = await suite.kem.generateKeyPair();
+const importedKey = await suite.kem.importKey('raw', keyBytes.buffer, true);
 ```
 
-#### `importKeyFromBase64(base64)`
-Import public key from base64.
+#### `createHpkeSuiteChaCha20()`
+
+Create an HPKE suite with ChaCha20-Poly1305.
 
 ```typescript
-async function importKeyFromBase64(base64: string): Promise<any>
+const suite = createHpkeSuiteChaCha20();
 ```
 
-### Server Functions
+#### `exportKeyToBase64(publicKey)`
 
-#### `createHpkeServer(config?)`
-Create HPKE server instance.
+Export public key to base64 string.
 
 ```typescript
-interface HpkeServerConfig {
-  autoGenerateKeys?: boolean; // Default: true
-}
-
-interface HpkeServerInstance {
-  getPublicKeyBase64(): string;
-  decrypt(ciphertext: string, enc: string, clientPublicKey: string): Promise<string>;
-  encrypt(message: string, clientPublicKey: string): Promise<{
-    ciphertext: string;
-    enc: string;
-  }>;
-}
+const b64 = exportKeyToBase64(publicKey);
 ```
 
-### SvelteKit Integration
+#### `importKeyFromBase64(base64)`
 
-#### `createHpkeEndpoint(config?)`
-Create complete API endpoints.
+Import public key from base64 string.
 
 ```typescript
-interface HpkeEndpointConfig {
-  autoGenerateKeys?: boolean;
-  onRequest?: (decrypted: any, request: Request) => Promise<any>;
-  onError?: (error: Error, request: Request) => Promise<Response>;
-}
+const publicKey = await importKeyFromBase64(b64String);
 ```
 
-## 🔧 Advanced Usage
+#### `uint8ArrayToBase64(data)` / `base64ToUint8Array(base64)`
 
-### Custom Algorithm (ChaCha20-Poly1305)
+Utility functions for encoding/decoding.
 
 ```typescript
-import { createHpkeSuiteChaCha20 } from '@hpke/sveltekit-wrapper';
-
-const suite = createHpkeSuiteChaCha20();
-// Use suite for encryption/decryption
+const b64 = uint8ArrayToBase64(bytes);
+const bytes = base64ToUint8Array(b64);
 ```
 
-### Manual Key Management
+### Server Functions
+
+#### `createHpkeServer(config?)`
+
+Create an HPKE server instance with key management.
 
 ```typescript
-import { createHpkeServer } from '@hpke/sveltekit-wrapper';
-
-// Disable auto-generation
-const server = createHpkeServer({ autoGenerateKeys: false });
+interface HpkeServerConfig {
+	autoGenerateKeys?: boolean; // Default: true
+}
 
-// Set keys manually later
-// (You'll need to extend the server instance with a setKeys method)
+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 }>;
+}
 ```
 
-### Error Handling
+### SvelteKit Integration
+
+#### `createHpkeEndpoint(config?)`
+
+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)
   │                               │
-  ├─── POST Encrypted Data ─────>│
+  ├─── hpkeEncrypt(payload) ────│
   │                               │
-  │                               ├─── Decrypt ──┐
-  │                               │               │
-  │                               │<── Process ───┘
+  ├─── POST { ciphertext, enc, ─>│
+  │       clientPublicKey }      │
   │                               │
-  │                               ├─── Encrypt ──┐
-  │                               │               │
-  │<──── Encrypted Response ─────│<──────────────┘
+  │                               ├─── decrypt() ──┐
+  │                               │                 │
+  │                               │<── Process ─────┘
+  │                               │                 │
+  │                               │<── encrypt() ───┘
   │                               │
-  └─── Decrypt Response ─────────┘
+  │<──── { ciphertext, enc } ────│
+  │                               │
+  └─── 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
@@ -260,7 +300,7 @@ npm run build
 # Type check
 npm run lint
 
-# Watch mode for development
+# Watch mode
 npm run dev
 ```
 
@@ -268,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.1",
+	"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",