lockform 2.0.0 → 3.0.0

package/README.md

@@ -94,6 +94,31 @@ app.post('/webhook', async (req, res) => {
 
 ## API Reference
 
+### `derivePrivateKey(mnemonic)`
+
+Derives a base64-encoded X25519 private key from a 15-word BIP39 recovery phrase. Useful for generating keys to use in edge functions.
+
+**Parameters:**
+- `mnemonic` (string): Your 15-word BIP39 recovery phrase
+
+**Returns:** `string` - Base64-encoded X25519 private key
+
+**Example:**
+
+```typescript
+import { derivePrivateKey } from 'lockform'
+
+const mnemonic = 'your fifteen word recovery phrase 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.
@@ -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 recovery phrase to avoid CPU timeout errors. See the performance note below.
+
 ```typescript
 import { decryptWebhookData, verifyWebhookSignature, type WebhookPayload } from 'lockform'
 
@@ -340,6 +367,52 @@ The webhook payload structure has changed:
 - 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 recovery phrase.
+
+**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 recovery phrase and output the base64 private key.
+
+**Option 2: Use the API programmatically**
+
+```javascript
+import { derivePrivateKey } from 'lockform'
+
+const mnemonic = 'your fifteen word recovery phrase 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 recovery phrase 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 Private Key Derivation Tool')
+console.log('='.repeat(70))
+console.log()
+console.log('This tool derives a base64-encoded X25519 private key from your')
+console.log('15-word BIP39 recovery phrase for use in edge functions.')
+console.log()
+
+rl.question('Enter your 15-word recovery phrase: ', (mnemonic) => {
+  try {
+    const words = mnemonic.trim().split(/\s+/)
+
+    if (words.length !== 15) {
+      console.error('\n❌ Error: Recovery phrase must be exactly 15 words')
+      console.error(`   You entered ${words.length} words`)
+      process.exit(1)
+    }
+
+    console.log('\n⏳ Deriving private key (this may take a few seconds)...\n')
+
+    const privateKeyBase64 = derivePrivateKey(mnemonic.trim())
+
+    console.log('✅ Success! Your base64-encoded private 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_RECOVERY_PHRASE="${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.0",
   "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",