lockform 2.0.0 → 3.0.1

package/README.md

@@ -14,21 +14,21 @@ npm install lockform
 - **Signature verification**: Verify webhook authenticity using HMAC-SHA256 signatures
 - **Field mapping**: Automatically map field IDs to human-readable CSV names
 - **X25519 encryption**: Modern, fast elliptic curve cryptography
-- **BIP39 support**: Works with 15-word recovery phrases or base64 private keys
+- **BIP39 support**: Works with 15-word passphrases or base64 private keys
 - **TypeScript support**: Full type definitions included
 
 ## Quick Start
 
 ### Decrypting Webhook Data
 
-You can decrypt webhooks using either your 15-word recovery phrase or a base64-encoded private key:
+You can decrypt webhooks using either your 15-word passphrase or a base64-encoded private key:
 
-**Using recovery phrase:**
+**Using passphrase:**
 
 ```typescript
 import { decryptWebhookData } from 'lockform'
 
-const mnemonic = 'your fifteen word recovery phrase goes here and must be exactly fifteen words'
+const mnemonic = 'your fifteen word passphrase goes here and must be exactly fifteen words'
 
 app.post('/webhook', async (req, res) => {
   const payload = req.body
@@ -94,13 +94,38 @@ app.post('/webhook', async (req, res) => {
 
 ## API Reference
 
+### `derivePrivateKey(mnemonic)`
+
+Derives a base64-encoded X25519 private key from a 15-word BIP39 passphrase. Useful for generating keys to use in edge functions.
+
+**Parameters:**
+- `mnemonic` (string): Your 15-word BIP39 passphrase
+
+**Returns:** `string` - Base64-encoded X25519 private key
+
+**Example:**
+
+```typescript
+import { derivePrivateKey } from 'lockform'
+
+const mnemonic = 'your fifteen word passphrase goes here exactly fifteen words'
+const privateKeyBase64 = derivePrivateKey(mnemonic)
+
+console.log(privateKeyBase64)
+// Output: "a1b2c3d4e5f6..." (base64 string)
+
+// Store this in your edge function environment variable
+```
+
+**Use case:** Run this once locally to derive your private key, then store the base64 output as an environment variable for edge functions (to avoid PBKDF2 timeout).
+
 ### `decryptWebhookData(options)`
 
 Decrypts an encrypted webhook payload from Lockform using X25519 + AES-256-GCM.
 
 **Parameters:**
 - `options.payload` (WebhookPayload): The webhook payload received from Lockform
-- `options.passphrase` (string): Your 15-word BIP39 recovery phrase (or optionally, base64-encoded X25519 private key)
+- `options.passphrase` (string): Your 15-word BIP39 passphrase (or optionally, base64-encoded X25519 private key)
 
 **Returns:** `Promise<DecryptedSubmission>`
 
@@ -247,6 +272,8 @@ app.listen(3000, () => {
 
 ### Deno Edge Function
 
+**Important:** Edge functions have strict CPU time limits. Use a base64-encoded private key instead of the 15-word passphrase to avoid CPU timeout errors. See the performance note below.
+
 ```typescript
 import { decryptWebhookData, verifyWebhookSignature, type WebhookPayload } from 'lockform'
 
@@ -263,7 +290,7 @@ Deno.serve(async (req) => {
 
   if (!recoveryPhrase) {
     return new Response(
-      JSON.stringify({ error: 'Recovery phrase not configured' }),
+      JSON.stringify({ error: 'Passphrase not configured' }),
       { status: 500, headers: { 'Content-Type': 'application/json' } }
     )
   }
@@ -320,8 +347,8 @@ Lockform uses modern, audited cryptography for maximum security:
 ## Security Best Practices
 
 1. **Always verify signatures**: Use `verifyWebhookSignature` to ensure webhooks are genuinely from Lockform
-2. **Protect your recovery phrase**: Store your 15-word recovery phrase in environment variables, never commit it to version control
-3. **Never share your recovery phrase**: Anyone with your 15-word recovery phrase can decrypt all submissions
+2. **Protect your passphrase**: Store your 15-word passphrase in environment variables, never commit it to version control
+3. **Never share your passphrase**: Anyone with your 15-word passphrase can decrypt all submissions
 4. **Use HTTPS**: Always use HTTPS endpoints for webhooks in production
 5. **Validate data**: Always validate the decrypted data before processing it
 6. **Implement idempotency**: Use the `submission_id` to prevent duplicate processing
@@ -332,14 +359,60 @@ Lockform uses modern, audited cryptography for maximum security:
 If you're migrating from the RSA-based v1.x version:
 
 1. **Update your package**: `npm install lockform@latest`
-2. **Update your credentials**: Use your 15-word recovery phrase instead of PEM-formatted RSA keys
-3. **Update your code**: Pass your recovery phrase as the `passphrase` parameter (renamed from `privateKey`)
+2. **Update your credentials**: Use your 15-word passphrase instead of PEM-formatted RSA keys
+3. **Update your code**: Pass your passphrase as the `passphrase` parameter (renamed from `privateKey`)
 
 The webhook payload structure has changed:
 - `wrapped_key` → `ephemeral_public_key`
 - Added: `salt`, `encryption_timestamp`
 - `algorithm` changed from `RSA-OAEP-4096+AES-256-GCM` to `X25519+AES-256-GCM`
 
+## Performance Considerations
+
+### Edge Functions (Deno, Cloudflare Workers, etc.)
+
+Edge functions have strict CPU time limits (typically 50-100ms). The PBKDF2 key derivation with 600,000 iterations can take several seconds and will cause timeout errors.
+
+**Solution:** Use a base64-encoded private key instead of the passphrase.
+
+**Option 1: Use the CLI tool (easiest)**
+
+```bash
+npx lockform-derive-key
+# Or if installed: npm run derive-key
+```
+
+This will prompt you for your passphrase and output the base64 private key.
+
+**Option 2: Use the API programmatically**
+
+```javascript
+import { derivePrivateKey } from 'lockform'
+
+const mnemonic = 'your fifteen word passphrase here exactly fifteen words'
+const privateKeyBase64 = derivePrivateKey(mnemonic)
+console.log(privateKeyBase64) // Store this in your edge function environment
+```
+
+Then use the base64 key in your edge function:
+
+```typescript
+const recoveryPhrase = Deno.env.get('LOCKFORM_RECOVERY_PHRASE') // Now contains base64 key
+
+const result = await decryptWebhookData({
+  payload,
+  passphrase: recoveryPhrase, // Automatically detects base64 format (no PBKDF2)
+})
+```
+
+The library automatically detects the format:
+- Contains spaces → 15-word mnemonic (slow, runs PBKDF2)
+- No spaces → Base64 private key (fast, skips PBKDF2)
+
+### Node.js / Long-running servers
+
+You can use either format. The 15-word passphrase works fine in environments without strict CPU time limits.
+
 ## Requirements
 
 - Node.js 18.0.0 or higher

package/derive-key.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { derivePrivateKey } from './dist/index.js'
+import { createInterface } from 'readline'
+
+const rl = createInterface({
+  input: process.stdin,
+  output: process.stdout
+})
+
+console.log('='.repeat(70))
+console.log('Lockform Passphrase Key Derivation Tool')
+console.log('='.repeat(70))
+console.log()
+console.log('This tool derives a base64-encoded X25519 key from your')
+console.log('15-word BIP39 passphrase for use in edge functions.')
+console.log()
+
+rl.question('Enter your 15-word passphrase: ', (mnemonic) => {
+  try {
+    const words = mnemonic.trim().split(/\s+/)
+
+    if (words.length !== 15) {
+      console.error('\n❌ Error: Passphrase must be exactly 15 words')
+      console.error(`   You entered ${words.length} words`)
+      process.exit(1)
+    }
+
+    console.log('\n⏳ Deriving encryption key (this may take a few seconds)...\n')
+
+    const privateKeyBase64 = derivePrivateKey(mnemonic.trim())
+
+    console.log('✅ Success! Your base64-encoded encryption key:\n')
+    console.log('─'.repeat(70))
+    console.log(privateKeyBase64)
+    console.log('─'.repeat(70))
+    console.log()
+    console.log('Add this to your edge function environment variables:')
+    console.log()
+    console.log(`LOCKFORM_DERIVED_KEY="${privateKeyBase64}"`)
+    console.log()
+    console.log('⚠️  Keep this secret! Anyone with this key can decrypt all submissions.')
+    console.log()
+
+  } catch (error) {
+    console.error('\n❌ Error:', error.message)
+    process.exit(1)
+  } finally {
+    rl.close()
+  }
+})

package/dist/crypto.d.ts

@@ -2,6 +2,7 @@ export declare function base64ToArrayBuffer(base64: string): Promise<Uint8Array>
 export declare function arrayBufferToString(buffer: ArrayBuffer | Uint8Array): string;
 export declare function importPrivateKeyFromMnemonic(mnemonic: string): Uint8Array;
 export declare function importPrivateKeyFromBase64(base64: string): Uint8Array;
+export declare function derivePrivateKey(mnemonic: string): string;
 export declare function decryptSubmission(ciphertext: string, iv: string, salt: string, ephemeralPublicKey: string, privateKey: Uint8Array, metadata?: {
     formId?: string;
     encryptionTimestamp?: number;

package/dist/crypto.js

@@ -4,6 +4,7 @@ exports.base64ToArrayBuffer = base64ToArrayBuffer;
 exports.arrayBufferToString = arrayBufferToString;
 exports.importPrivateKeyFromMnemonic = importPrivateKeyFromMnemonic;
 exports.importPrivateKeyFromBase64 = importPrivateKeyFromBase64;
+exports.derivePrivateKey = derivePrivateKey;
 exports.decryptSubmission = decryptSubmission;
 exports.createHmacSignature = createHmacSignature;
 const node_crypto_1 = require("node:crypto");
@@ -36,6 +37,10 @@ function importPrivateKeyFromMnemonic(mnemonic) {
 function importPrivateKeyFromBase64(base64) {
     return Buffer.from(base64, 'base64');
 }
+function derivePrivateKey(mnemonic) {
+    const privateKeyBytes = importPrivateKeyFromMnemonic(mnemonic);
+    return Buffer.from(privateKeyBytes).toString('base64');
+}
 function deriveSharedSecret(privateKey, publicKey) {
     return ed25519_1.x25519.getSharedSecret(privateKey, publicKey);
 }

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { decryptWebhookData } from './decrypt';
 export { verifyWebhookSignature } from './verify';
+export { derivePrivateKey } from './crypto';
 export type { WebhookPayload, DecryptedSubmission, DecryptWebhookOptions, VerifySignatureOptions, } from './types';

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyWebhookSignature = exports.decryptWebhookData = void 0;
+exports.derivePrivateKey = exports.verifyWebhookSignature = exports.decryptWebhookData = void 0;
 var decrypt_1 = require("./decrypt");
 Object.defineProperty(exports, "decryptWebhookData", { enumerable: true, get: function () { return decrypt_1.decryptWebhookData; } });
 var verify_1 = require("./verify");
 Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return verify_1.verifyWebhookSignature; } });
+var crypto_1 = require("./crypto");
+Object.defineProperty(exports, "derivePrivateKey", { enumerable: true, get: function () { return crypto_1.derivePrivateKey; } });

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "lockform",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "Official SDK for processing Lockform webhook submissions with end-to-end encryption using X25519 + AES-256-GCM",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "derive-key.js"
   ],
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "derive-key": "node derive-key.js"
+  },
+  "bin": {
+    "lockform-derive-key": "./derive-key.js"
   },
   "keywords": [
     "lockform",