lockform 1.0.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Lockform
 
-Official SDK for processing Lockform webhook submissions with end-to-end encryption.
+Official SDK for processing Lockform webhook submissions with end-to-end encryption using X25519 + AES-256-GCM.
 
 ## Installation
 
@@ -13,29 +13,52 @@ npm install lockform
 - **Decrypt webhook data**: Easily decrypt encrypted form submissions received via webhooks
 - **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
 - **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:
+
+**Using recovery phrase:**
+
 ```typescript
 import { decryptWebhookData } from 'lockform'
 
-const privateKey = `-----BEGIN PRIVATE KEY-----
-YOUR_PRIVATE_KEY_HERE
------END PRIVATE KEY-----`
+const mnemonic = 'your fifteen word recovery phrase goes here and must be exactly fifteen words'
 
 app.post('/webhook', async (req, res) => {
   const payload = req.body
 
   const result = await decryptWebhookData({
     payload,
-    privateKey,
+    passphrase: mnemonic,
   })
 
   console.log('Mapped data:', result.mappedData)
+  res.json({ success: true })
+})
+```
+
+**Using base64 private key:**
+
+```typescript
+import { decryptWebhookData } from 'lockform'
+
+const privateKeyBase64 = 'your-base64-encoded-x25519-private-key'
+
+app.post('/webhook', async (req, res) => {
+  const payload = req.body
+
+  const result = await decryptWebhookData({
+    payload,
+    passphrase: privateKeyBase64,
+  })
 
+  console.log('Mapped data:', result.mappedData)
   res.json({ success: true })
 })
 ```
@@ -61,11 +84,10 @@ app.post('/webhook', async (req, res) => {
 
   const result = await decryptWebhookData({
     payload: req.body,
-    privateKey: process.env.PRIVATE_KEY,
+    passphrase: process.env.LOCKFORM_RECOVERY_PHRASE,
   })
 
   console.log('Decrypted data:', result.mappedData)
-
   res.json({ success: true })
 })
 ```
@@ -74,11 +96,11 @@ app.post('/webhook', async (req, res) => {
 
 ### `decryptWebhookData(options)`
 
-Decrypts an encrypted webhook payload from Lockform.
+Decrypts an encrypted webhook payload from Lockform using X25519 + AES-256-GCM.
 
 **Parameters:**
 - `options.payload` (WebhookPayload): The webhook payload received from Lockform
-- `options.privateKey` (string): Your RSA private key in PEM format
+- `options.passphrase` (string): Your 15-word BIP39 recovery phrase (or optionally, base64-encoded X25519 private key)
 
 **Returns:** `Promise<DecryptedSubmission>`
 
@@ -101,10 +123,11 @@ Decrypts an encrypted webhook payload from Lockform.
 ```typescript
 const result = await decryptWebhookData({
   payload: webhookPayload,
-  privateKey: myPrivateKey,
+  passphrase: myRecoveryPhrase,
 })
 
-console.log(result.mappedData)
+console.log(result.mappedData) // { name: "John Doe", email: "john@example.com" }
+console.log(result.rawData) // { "field-id-1": "John Doe", "field-id-2": "john@example.com" }
 ```
 
 ### `verifyWebhookSignature(options)`
@@ -143,10 +166,12 @@ interface WebhookPayload {
   form_id: string
   ciphertext: string
   iv: string
-  wrapped_key: string
+  salt: string
+  ephemeral_public_key: string
   auth_tag: string
   algorithm: string
   nonce: string
+  encryption_timestamp: number
   timestamp: string
   field_mapping: Record<string, string>
 }
@@ -170,6 +195,8 @@ interface DecryptedSubmission {
 
 ## Complete Example
 
+### Node.js / Express
+
 ```typescript
 import express from 'express'
 import { decryptWebhookData, verifyWebhookSignature } from 'lockform'
@@ -177,7 +204,7 @@ import { decryptWebhookData, verifyWebhookSignature } from 'lockform'
 const app = express()
 app.use(express.json())
 
-const PRIVATE_KEY = process.env.LOCKFORM_PRIVATE_KEY
+const RECOVERY_PHRASE = process.env.LOCKFORM_RECOVERY_PHRASE
 const WEBHOOK_SECRET = process.env.LOCKFORM_WEBHOOK_SECRET
 
 app.post('/lockform-webhook', async (req, res) => {
@@ -199,7 +226,7 @@ app.post('/lockform-webhook', async (req, res) => {
 
     const result = await decryptWebhookData({
       payload,
-      privateKey: PRIVATE_KEY,
+      passphrase: RECOVERY_PHRASE,
     })
 
     console.log('Form ID:', result.metadata.form_id)
@@ -218,12 +245,100 @@ app.listen(3000, () => {
 })
 ```
 
+### Deno Edge Function
+
+```typescript
+import { decryptWebhookData, verifyWebhookSignature, type WebhookPayload } from 'lockform'
+
+Deno.serve(async (req) => {
+  if (req.method !== 'POST') {
+    return new Response(
+      JSON.stringify({ error: 'Method not allowed' }),
+      { status: 405, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+
+  const recoveryPhrase = Deno.env.get('LOCKFORM_RECOVERY_PHRASE')
+  const webhookSecret = Deno.env.get('WEBHOOK_SECRET')
+
+  if (!recoveryPhrase) {
+    return new Response(
+      JSON.stringify({ error: 'Recovery phrase not configured' }),
+      { status: 500, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+
+  const signature = req.headers.get('x-signature-sha256')
+  const rawBody = await req.text()
+  const payload: WebhookPayload = JSON.parse(rawBody)
+
+  if (webhookSecret && signature) {
+    const isValid = await verifyWebhookSignature({
+      payload: rawBody,
+      signature,
+      secret: webhookSecret,
+    })
+    if (!isValid) {
+      return new Response(
+        JSON.stringify({ error: 'Invalid signature' }),
+        { status: 401, headers: { 'Content-Type': 'application/json' } }
+      )
+    }
+  }
+
+  const result = await decryptWebhookData({
+    payload,
+    passphrase: recoveryPhrase,
+  })
+
+  console.log('New submission:', result.mappedData)
+
+  return new Response(
+    JSON.stringify({ success: true }),
+    { status: 200, headers: { 'Content-Type': 'application/json' } }
+  )
+})
+```
+
+## Cryptographic Details
+
+Lockform uses modern, audited cryptography for maximum security:
+
+- **Key Exchange**: X25519 (Curve25519 Diffie-Hellman)
+- **Symmetric Encryption**: AES-256-GCM (Galois/Counter Mode)
+- **Key Derivation**: HKDF-SHA256 with separate salt
+- **Mnemonic-to-Key**: PBKDF2-SHA512 (600,000 iterations)
+- **Mnemonic**: BIP39 (15 words, 160 bits entropy)
+
+**Why X25519 instead of RSA?**
+- Smaller keys (32 bytes vs 4096 bits)
+- Faster operations
+- Better security per bit
+- Modern, constant-time implementation
+- Forward secrecy with ephemeral keys
+
 ## Security Best Practices
 
 1. **Always verify signatures**: Use `verifyWebhookSignature` to ensure webhooks are genuinely from Lockform
-2. **Keep private keys secure**: Store your private key in environment variables, never commit it to version control
-3. **Use HTTPS**: Always use HTTPS endpoints for webhooks in production
-4. **Validate data**: Always validate the decrypted data before processing it
+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
+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
+7. **Rate limiting**: Implement rate limiting on your webhook endpoint
+
+## Migration from v1.x (RSA) to v2.x (X25519)
+
+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`)
+
+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`
 
 ## Requirements
 

package/dist/crypto.d.ts

@@ -1,6 +1,9 @@
-import { webcrypto } from 'node:crypto';
-export declare function base64ToArrayBuffer(base64: string): Promise<ArrayBuffer>;
-export declare function arrayBufferToString(buffer: ArrayBuffer): string;
-export declare function importPrivateKey(pemKey: string): Promise<webcrypto.CryptoKey>;
-export declare function decryptSubmission(ciphertext: string, iv: string, wrappedKey: string, authTag: string, privateKey: webcrypto.CryptoKey): Promise<string>;
+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 decryptSubmission(ciphertext: string, iv: string, salt: string, ephemeralPublicKey: string, privateKey: Uint8Array, metadata?: {
+    formId?: string;
+    encryptionTimestamp?: number;
+}): Promise<string>;
 export declare function createHmacSignature(payload: string, secret: string): Promise<string>;

package/dist/crypto.js

@@ -2,55 +2,68 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.base64ToArrayBuffer = base64ToArrayBuffer;
 exports.arrayBufferToString = arrayBufferToString;
-exports.importPrivateKey = importPrivateKey;
+exports.importPrivateKeyFromMnemonic = importPrivateKeyFromMnemonic;
+exports.importPrivateKeyFromBase64 = importPrivateKeyFromBase64;
 exports.decryptSubmission = decryptSubmission;
 exports.createHmacSignature = createHmacSignature;
 const node_crypto_1 = require("node:crypto");
+const ed25519_1 = require("@noble/curves/ed25519");
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha2_1 = require("@noble/hashes/sha2");
+const pbkdf2_1 = require("@noble/hashes/pbkdf2");
+const sha2_2 = require("@noble/hashes/sha2");
+const bip39_1 = require("bip39");
 const crypto = node_crypto_1.webcrypto;
 async function base64ToArrayBuffer(base64) {
-    const binaryString = Buffer.from(base64, 'base64').toString('binary');
-    const bytes = new Uint8Array(binaryString.length);
-    for (let i = 0; i < binaryString.length; i++) {
-        bytes[i] = binaryString.charCodeAt(i);
+    const binary = Buffer.from(base64, 'base64').toString('binary');
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
     }
-    return bytes.buffer;
+    return bytes;
 }
 function arrayBufferToString(buffer) {
     return new TextDecoder().decode(buffer);
 }
-async function importPrivateKey(pemKey) {
-    const pemHeader = '-----BEGIN PRIVATE KEY-----';
-    const pemFooter = '-----END PRIVATE KEY-----';
-    const pemContents = pemKey
-        .replace(pemHeader, '')
-        .replace(pemFooter, '')
-        .replace(/\s/g, '');
-    const binaryDer = await base64ToArrayBuffer(pemContents);
-    return await crypto.subtle.importKey('pkcs8', binaryDer, {
-        name: 'RSA-OAEP',
-        hash: 'SHA-256',
-    }, false, ['unwrapKey']);
+function importPrivateKeyFromMnemonic(mnemonic) {
+    const seed = (0, bip39_1.mnemonicToSeedSync)(mnemonic);
+    const privateKey = (0, pbkdf2_1.pbkdf2)(sha2_2.sha512, seed, 'lockform-x25519-v1', {
+        c: 600_000,
+        dkLen: 32,
+    });
+    return privateKey;
 }
-async function decryptSubmission(ciphertext, iv, wrappedKey, authTag, privateKey) {
+function importPrivateKeyFromBase64(base64) {
+    return Buffer.from(base64, 'base64');
+}
+function deriveSharedSecret(privateKey, publicKey) {
+    return ed25519_1.x25519.getSharedSecret(privateKey, publicKey);
+}
+function deriveAESKey(sharedSecret, salt) {
+    const info = new TextEncoder().encode('lockform-encryption-v1');
+    return (0, hkdf_1.hkdf)(sha2_1.sha256, sharedSecret, salt, info, 32);
+}
+async function decryptWithAES(ciphertext, key, iv, additionalData) {
+    const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['decrypt']);
+    const decrypted = await crypto.subtle.decrypt({
+        name: 'AES-GCM',
+        iv: iv,
+        ...(additionalData && { additionalData }),
+    }, cryptoKey, ciphertext);
+    const decoder = new TextDecoder();
+    return decoder.decode(decrypted);
+}
+async function decryptSubmission(ciphertext, iv, salt, ephemeralPublicKey, privateKey, metadata) {
     const ciphertextBuffer = await base64ToArrayBuffer(ciphertext);
     const ivBuffer = await base64ToArrayBuffer(iv);
-    const wrappedKeyBuffer = await base64ToArrayBuffer(wrappedKey);
-    const authTagBuffer = await base64ToArrayBuffer(authTag);
-    const combinedCiphertext = new Uint8Array(ciphertextBuffer.byteLength + authTagBuffer.byteLength);
-    combinedCiphertext.set(new Uint8Array(ciphertextBuffer), 0);
-    combinedCiphertext.set(new Uint8Array(authTagBuffer), ciphertextBuffer.byteLength);
-    const unwrappedKey = await crypto.subtle.unwrapKey('raw', wrappedKeyBuffer, privateKey, {
-        name: 'RSA-OAEP',
-        hash: { name: 'SHA-256' },
-    }, {
-        name: 'AES-GCM',
-        length: 256,
-    }, false, ['decrypt']);
-    const decryptedBuffer = await crypto.subtle.decrypt({
-        name: 'AES-GCM',
-        iv: ivBuffer,
-    }, unwrappedKey, combinedCiphertext);
-    return arrayBufferToString(decryptedBuffer);
+    const saltBuffer = await base64ToArrayBuffer(salt);
+    const ephemeralPublicKeyBuffer = await base64ToArrayBuffer(ephemeralPublicKey);
+    const sharedSecret = deriveSharedSecret(privateKey, ephemeralPublicKeyBuffer);
+    const aesKey = deriveAESKey(sharedSecret, saltBuffer);
+    const aad = metadata
+        ? new TextEncoder().encode(`${metadata.formId ?? ''}:${metadata.encryptionTimestamp ?? 0}`)
+        : undefined;
+    return await decryptWithAES(ciphertextBuffer, aesKey, ivBuffer, aad);
 }
 async function createHmacSignature(payload, secret) {
     const encoder = new TextEncoder();

package/dist/decrypt.js

@@ -3,9 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.decryptWebhookData = decryptWebhookData;
 const crypto_1 = require("./crypto");
 async function decryptWebhookData(options) {
-    const { payload, privateKey } = options;
-    const cryptoKey = await (0, crypto_1.importPrivateKey)(privateKey);
-    const decryptedData = await (0, crypto_1.decryptSubmission)(payload.ciphertext, payload.iv, payload.wrapped_key, payload.auth_tag, cryptoKey);
+    const { payload, passphrase } = options;
+    let privateKeyBytes;
+    if (passphrase.includes(' ')) {
+        privateKeyBytes = (0, crypto_1.importPrivateKeyFromMnemonic)(passphrase);
+    }
+    else {
+        privateKeyBytes = (0, crypto_1.importPrivateKeyFromBase64)(passphrase);
+    }
+    const decryptedData = await (0, crypto_1.decryptSubmission)(payload.ciphertext, payload.iv, payload.salt, payload.ephemeral_public_key, privateKeyBytes, {
+        formId: payload.form_id,
+        encryptionTimestamp: payload.encryption_timestamp,
+    });
     const rawData = JSON.parse(decryptedData);
     const mappedData = {};
     for (const [fieldId, value] of Object.entries(rawData)) {

package/dist/types.d.ts

@@ -4,10 +4,12 @@ export interface WebhookPayload {
     form_id: string;
     ciphertext: string;
     iv: string;
-    wrapped_key: string;
+    salt: string;
+    ephemeral_public_key: string;
     auth_tag: string;
     algorithm: string;
     nonce: string;
+    encryption_timestamp: number;
     timestamp: string;
     field_mapping: Record<string, string>;
 }
@@ -24,7 +26,7 @@ export interface DecryptedSubmission {
 }
 export interface DecryptWebhookOptions {
     payload: WebhookPayload;
-    privateKey: string;
+    passphrase: string;
 }
 export interface VerifySignatureOptions {
     payload: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lockform",
-  "version": "1.0.0",
-  "description": "Official SDK for processing Lockform webhook submissions with end-to-end encryption",
+  "version": "2.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": [
@@ -17,11 +17,18 @@
     "webhook",
     "e2e",
     "forms",
-    "rsa",
-    "aes"
+    "x25519",
+    "curve25519",
+    "aes-gcm",
+    "bip39"
   ],
   "author": "",
   "license": "MIT",
+  "dependencies": {
+    "@noble/curves": "^1.6.0",
+    "@noble/hashes": "^1.5.0",
+    "bip39": "^3.1.0"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"