lockform 1.0.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +205 -17
- package/derive-key.js +50 -0
- package/dist/crypto.d.ts +9 -5
- package/dist/crypto.js +54 -36
- package/dist/decrypt.js +12 -3
- package/dist/index.d.ts +1 -0
- package/dist/index.js +3 -1
- package/dist/types.d.ts +4 -2
- package/package.json +18 -6
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Lockform
|
|
2
2
|
|
|
3
|
-
Official SDK for processing Lockform webhook submissions with end-to-end encryption.
|
|
3
|
+
Official SDK for processing Lockform webhook submissions with end-to-end encryption using X25519 + AES-256-GCM.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
@@ -13,29 +13,52 @@ npm install lockform
|
|
|
13
13
|
- **Decrypt webhook data**: Easily decrypt encrypted form submissions received via webhooks
|
|
14
14
|
- **Signature verification**: Verify webhook authenticity using HMAC-SHA256 signatures
|
|
15
15
|
- **Field mapping**: Automatically map field IDs to human-readable CSV names
|
|
16
|
+
- **X25519 encryption**: Modern, fast elliptic curve cryptography
|
|
17
|
+
- **BIP39 support**: Works with 15-word recovery phrases or base64 private keys
|
|
16
18
|
- **TypeScript support**: Full type definitions included
|
|
17
19
|
|
|
18
20
|
## Quick Start
|
|
19
21
|
|
|
20
22
|
### Decrypting Webhook Data
|
|
21
23
|
|
|
24
|
+
You can decrypt webhooks using either your 15-word recovery phrase or a base64-encoded private key:
|
|
25
|
+
|
|
26
|
+
**Using recovery phrase:**
|
|
27
|
+
|
|
22
28
|
```typescript
|
|
23
29
|
import { decryptWebhookData } from 'lockform'
|
|
24
30
|
|
|
25
|
-
const
|
|
26
|
-
YOUR_PRIVATE_KEY_HERE
|
|
27
|
-
-----END PRIVATE KEY-----`
|
|
31
|
+
const mnemonic = 'your fifteen word recovery phrase goes here and must be exactly fifteen words'
|
|
28
32
|
|
|
29
33
|
app.post('/webhook', async (req, res) => {
|
|
30
34
|
const payload = req.body
|
|
31
35
|
|
|
32
36
|
const result = await decryptWebhookData({
|
|
33
37
|
payload,
|
|
34
|
-
|
|
38
|
+
passphrase: mnemonic,
|
|
35
39
|
})
|
|
36
40
|
|
|
37
41
|
console.log('Mapped data:', result.mappedData)
|
|
42
|
+
res.json({ success: true })
|
|
43
|
+
})
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**Using base64 private key:**
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
import { decryptWebhookData } from 'lockform'
|
|
50
|
+
|
|
51
|
+
const privateKeyBase64 = 'your-base64-encoded-x25519-private-key'
|
|
52
|
+
|
|
53
|
+
app.post('/webhook', async (req, res) => {
|
|
54
|
+
const payload = req.body
|
|
55
|
+
|
|
56
|
+
const result = await decryptWebhookData({
|
|
57
|
+
payload,
|
|
58
|
+
passphrase: privateKeyBase64,
|
|
59
|
+
})
|
|
38
60
|
|
|
61
|
+
console.log('Mapped data:', result.mappedData)
|
|
39
62
|
res.json({ success: true })
|
|
40
63
|
})
|
|
41
64
|
```
|
|
@@ -61,24 +84,48 @@ app.post('/webhook', async (req, res) => {
|
|
|
61
84
|
|
|
62
85
|
const result = await decryptWebhookData({
|
|
63
86
|
payload: req.body,
|
|
64
|
-
|
|
87
|
+
passphrase: process.env.LOCKFORM_RECOVERY_PHRASE,
|
|
65
88
|
})
|
|
66
89
|
|
|
67
90
|
console.log('Decrypted data:', result.mappedData)
|
|
68
|
-
|
|
69
91
|
res.json({ success: true })
|
|
70
92
|
})
|
|
71
93
|
```
|
|
72
94
|
|
|
73
95
|
## API Reference
|
|
74
96
|
|
|
97
|
+
### `derivePrivateKey(mnemonic)`
|
|
98
|
+
|
|
99
|
+
Derives a base64-encoded X25519 private key from a 15-word BIP39 recovery phrase. Useful for generating keys to use in edge functions.
|
|
100
|
+
|
|
101
|
+
**Parameters:**
|
|
102
|
+
- `mnemonic` (string): Your 15-word BIP39 recovery phrase
|
|
103
|
+
|
|
104
|
+
**Returns:** `string` - Base64-encoded X25519 private key
|
|
105
|
+
|
|
106
|
+
**Example:**
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
import { derivePrivateKey } from 'lockform'
|
|
110
|
+
|
|
111
|
+
const mnemonic = 'your fifteen word recovery phrase goes here exactly fifteen words'
|
|
112
|
+
const privateKeyBase64 = derivePrivateKey(mnemonic)
|
|
113
|
+
|
|
114
|
+
console.log(privateKeyBase64)
|
|
115
|
+
// Output: "a1b2c3d4e5f6..." (base64 string)
|
|
116
|
+
|
|
117
|
+
// Store this in your edge function environment variable
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
**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).
|
|
121
|
+
|
|
75
122
|
### `decryptWebhookData(options)`
|
|
76
123
|
|
|
77
|
-
Decrypts an encrypted webhook payload from Lockform.
|
|
124
|
+
Decrypts an encrypted webhook payload from Lockform using X25519 + AES-256-GCM.
|
|
78
125
|
|
|
79
126
|
**Parameters:**
|
|
80
127
|
- `options.payload` (WebhookPayload): The webhook payload received from Lockform
|
|
81
|
-
- `options.
|
|
128
|
+
- `options.passphrase` (string): Your 15-word BIP39 recovery phrase (or optionally, base64-encoded X25519 private key)
|
|
82
129
|
|
|
83
130
|
**Returns:** `Promise<DecryptedSubmission>`
|
|
84
131
|
|
|
@@ -101,10 +148,11 @@ Decrypts an encrypted webhook payload from Lockform.
|
|
|
101
148
|
```typescript
|
|
102
149
|
const result = await decryptWebhookData({
|
|
103
150
|
payload: webhookPayload,
|
|
104
|
-
|
|
151
|
+
passphrase: myRecoveryPhrase,
|
|
105
152
|
})
|
|
106
153
|
|
|
107
|
-
console.log(result.mappedData)
|
|
154
|
+
console.log(result.mappedData) // { name: "John Doe", email: "john@example.com" }
|
|
155
|
+
console.log(result.rawData) // { "field-id-1": "John Doe", "field-id-2": "john@example.com" }
|
|
108
156
|
```
|
|
109
157
|
|
|
110
158
|
### `verifyWebhookSignature(options)`
|
|
@@ -143,10 +191,12 @@ interface WebhookPayload {
|
|
|
143
191
|
form_id: string
|
|
144
192
|
ciphertext: string
|
|
145
193
|
iv: string
|
|
146
|
-
|
|
194
|
+
salt: string
|
|
195
|
+
ephemeral_public_key: string
|
|
147
196
|
auth_tag: string
|
|
148
197
|
algorithm: string
|
|
149
198
|
nonce: string
|
|
199
|
+
encryption_timestamp: number
|
|
150
200
|
timestamp: string
|
|
151
201
|
field_mapping: Record<string, string>
|
|
152
202
|
}
|
|
@@ -170,6 +220,8 @@ interface DecryptedSubmission {
|
|
|
170
220
|
|
|
171
221
|
## Complete Example
|
|
172
222
|
|
|
223
|
+
### Node.js / Express
|
|
224
|
+
|
|
173
225
|
```typescript
|
|
174
226
|
import express from 'express'
|
|
175
227
|
import { decryptWebhookData, verifyWebhookSignature } from 'lockform'
|
|
@@ -177,7 +229,7 @@ import { decryptWebhookData, verifyWebhookSignature } from 'lockform'
|
|
|
177
229
|
const app = express()
|
|
178
230
|
app.use(express.json())
|
|
179
231
|
|
|
180
|
-
const
|
|
232
|
+
const RECOVERY_PHRASE = process.env.LOCKFORM_RECOVERY_PHRASE
|
|
181
233
|
const WEBHOOK_SECRET = process.env.LOCKFORM_WEBHOOK_SECRET
|
|
182
234
|
|
|
183
235
|
app.post('/lockform-webhook', async (req, res) => {
|
|
@@ -199,7 +251,7 @@ app.post('/lockform-webhook', async (req, res) => {
|
|
|
199
251
|
|
|
200
252
|
const result = await decryptWebhookData({
|
|
201
253
|
payload,
|
|
202
|
-
|
|
254
|
+
passphrase: RECOVERY_PHRASE,
|
|
203
255
|
})
|
|
204
256
|
|
|
205
257
|
console.log('Form ID:', result.metadata.form_id)
|
|
@@ -218,12 +270,148 @@ app.listen(3000, () => {
|
|
|
218
270
|
})
|
|
219
271
|
```
|
|
220
272
|
|
|
273
|
+
### Deno Edge Function
|
|
274
|
+
|
|
275
|
+
**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.
|
|
276
|
+
|
|
277
|
+
```typescript
|
|
278
|
+
import { decryptWebhookData, verifyWebhookSignature, type WebhookPayload } from 'lockform'
|
|
279
|
+
|
|
280
|
+
Deno.serve(async (req) => {
|
|
281
|
+
if (req.method !== 'POST') {
|
|
282
|
+
return new Response(
|
|
283
|
+
JSON.stringify({ error: 'Method not allowed' }),
|
|
284
|
+
{ status: 405, headers: { 'Content-Type': 'application/json' } }
|
|
285
|
+
)
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
const recoveryPhrase = Deno.env.get('LOCKFORM_RECOVERY_PHRASE')
|
|
289
|
+
const webhookSecret = Deno.env.get('WEBHOOK_SECRET')
|
|
290
|
+
|
|
291
|
+
if (!recoveryPhrase) {
|
|
292
|
+
return new Response(
|
|
293
|
+
JSON.stringify({ error: 'Recovery phrase not configured' }),
|
|
294
|
+
{ status: 500, headers: { 'Content-Type': 'application/json' } }
|
|
295
|
+
)
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
const signature = req.headers.get('x-signature-sha256')
|
|
299
|
+
const rawBody = await req.text()
|
|
300
|
+
const payload: WebhookPayload = JSON.parse(rawBody)
|
|
301
|
+
|
|
302
|
+
if (webhookSecret && signature) {
|
|
303
|
+
const isValid = await verifyWebhookSignature({
|
|
304
|
+
payload: rawBody,
|
|
305
|
+
signature,
|
|
306
|
+
secret: webhookSecret,
|
|
307
|
+
})
|
|
308
|
+
if (!isValid) {
|
|
309
|
+
return new Response(
|
|
310
|
+
JSON.stringify({ error: 'Invalid signature' }),
|
|
311
|
+
{ status: 401, headers: { 'Content-Type': 'application/json' } }
|
|
312
|
+
)
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
const result = await decryptWebhookData({
|
|
317
|
+
payload,
|
|
318
|
+
passphrase: recoveryPhrase,
|
|
319
|
+
})
|
|
320
|
+
|
|
321
|
+
console.log('New submission:', result.mappedData)
|
|
322
|
+
|
|
323
|
+
return new Response(
|
|
324
|
+
JSON.stringify({ success: true }),
|
|
325
|
+
{ status: 200, headers: { 'Content-Type': 'application/json' } }
|
|
326
|
+
)
|
|
327
|
+
})
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
## Cryptographic Details
|
|
331
|
+
|
|
332
|
+
Lockform uses modern, audited cryptography for maximum security:
|
|
333
|
+
|
|
334
|
+
- **Key Exchange**: X25519 (Curve25519 Diffie-Hellman)
|
|
335
|
+
- **Symmetric Encryption**: AES-256-GCM (Galois/Counter Mode)
|
|
336
|
+
- **Key Derivation**: HKDF-SHA256 with separate salt
|
|
337
|
+
- **Mnemonic-to-Key**: PBKDF2-SHA512 (600,000 iterations)
|
|
338
|
+
- **Mnemonic**: BIP39 (15 words, 160 bits entropy)
|
|
339
|
+
|
|
340
|
+
**Why X25519 instead of RSA?**
|
|
341
|
+
- Smaller keys (32 bytes vs 4096 bits)
|
|
342
|
+
- Faster operations
|
|
343
|
+
- Better security per bit
|
|
344
|
+
- Modern, constant-time implementation
|
|
345
|
+
- Forward secrecy with ephemeral keys
|
|
346
|
+
|
|
221
347
|
## Security Best Practices
|
|
222
348
|
|
|
223
349
|
1. **Always verify signatures**: Use `verifyWebhookSignature` to ensure webhooks are genuinely from Lockform
|
|
224
|
-
2. **
|
|
225
|
-
3. **
|
|
226
|
-
4. **
|
|
350
|
+
2. **Protect your recovery phrase**: Store your 15-word recovery phrase in environment variables, never commit it to version control
|
|
351
|
+
3. **Never share your recovery phrase**: Anyone with your 15-word recovery phrase can decrypt all submissions
|
|
352
|
+
4. **Use HTTPS**: Always use HTTPS endpoints for webhooks in production
|
|
353
|
+
5. **Validate data**: Always validate the decrypted data before processing it
|
|
354
|
+
6. **Implement idempotency**: Use the `submission_id` to prevent duplicate processing
|
|
355
|
+
7. **Rate limiting**: Implement rate limiting on your webhook endpoint
|
|
356
|
+
|
|
357
|
+
## Migration from v1.x (RSA) to v2.x (X25519)
|
|
358
|
+
|
|
359
|
+
If you're migrating from the RSA-based v1.x version:
|
|
360
|
+
|
|
361
|
+
1. **Update your package**: `npm install lockform@latest`
|
|
362
|
+
2. **Update your credentials**: Use your 15-word recovery phrase instead of PEM-formatted RSA keys
|
|
363
|
+
3. **Update your code**: Pass your recovery phrase as the `passphrase` parameter (renamed from `privateKey`)
|
|
364
|
+
|
|
365
|
+
The webhook payload structure has changed:
|
|
366
|
+
- `wrapped_key` → `ephemeral_public_key`
|
|
367
|
+
- Added: `salt`, `encryption_timestamp`
|
|
368
|
+
- `algorithm` changed from `RSA-OAEP-4096+AES-256-GCM` to `X25519+AES-256-GCM`
|
|
369
|
+
|
|
370
|
+
## Performance Considerations
|
|
371
|
+
|
|
372
|
+
### Edge Functions (Deno, Cloudflare Workers, etc.)
|
|
373
|
+
|
|
374
|
+
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.
|
|
375
|
+
|
|
376
|
+
**Solution:** Use a base64-encoded private key instead of the recovery phrase.
|
|
377
|
+
|
|
378
|
+
**Option 1: Use the CLI tool (easiest)**
|
|
379
|
+
|
|
380
|
+
```bash
|
|
381
|
+
npx lockform-derive-key
|
|
382
|
+
# Or if installed: npm run derive-key
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
This will prompt you for your recovery phrase and output the base64 private key.
|
|
386
|
+
|
|
387
|
+
**Option 2: Use the API programmatically**
|
|
388
|
+
|
|
389
|
+
```javascript
|
|
390
|
+
import { derivePrivateKey } from 'lockform'
|
|
391
|
+
|
|
392
|
+
const mnemonic = 'your fifteen word recovery phrase here exactly fifteen words'
|
|
393
|
+
const privateKeyBase64 = derivePrivateKey(mnemonic)
|
|
394
|
+
console.log(privateKeyBase64) // Store this in your edge function environment
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
Then use the base64 key in your edge function:
|
|
398
|
+
|
|
399
|
+
```typescript
|
|
400
|
+
const recoveryPhrase = Deno.env.get('LOCKFORM_RECOVERY_PHRASE') // Now contains base64 key
|
|
401
|
+
|
|
402
|
+
const result = await decryptWebhookData({
|
|
403
|
+
payload,
|
|
404
|
+
passphrase: recoveryPhrase, // Automatically detects base64 format (no PBKDF2)
|
|
405
|
+
})
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
The library automatically detects the format:
|
|
409
|
+
- Contains spaces → 15-word mnemonic (slow, runs PBKDF2)
|
|
410
|
+
- No spaces → Base64 private key (fast, skips PBKDF2)
|
|
411
|
+
|
|
412
|
+
### Node.js / Long-running servers
|
|
413
|
+
|
|
414
|
+
You can use either format. The 15-word recovery phrase works fine in environments without strict CPU time limits.
|
|
227
415
|
|
|
228
416
|
## Requirements
|
|
229
417
|
|
package/derive-key.js
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { derivePrivateKey } from './dist/index.js'
|
|
3
|
+
import { createInterface } from 'readline'
|
|
4
|
+
|
|
5
|
+
const rl = createInterface({
|
|
6
|
+
input: process.stdin,
|
|
7
|
+
output: process.stdout
|
|
8
|
+
})
|
|
9
|
+
|
|
10
|
+
console.log('='.repeat(70))
|
|
11
|
+
console.log('Lockform Private Key Derivation Tool')
|
|
12
|
+
console.log('='.repeat(70))
|
|
13
|
+
console.log()
|
|
14
|
+
console.log('This tool derives a base64-encoded X25519 private key from your')
|
|
15
|
+
console.log('15-word BIP39 recovery phrase for use in edge functions.')
|
|
16
|
+
console.log()
|
|
17
|
+
|
|
18
|
+
rl.question('Enter your 15-word recovery phrase: ', (mnemonic) => {
|
|
19
|
+
try {
|
|
20
|
+
const words = mnemonic.trim().split(/\s+/)
|
|
21
|
+
|
|
22
|
+
if (words.length !== 15) {
|
|
23
|
+
console.error('\n❌ Error: Recovery phrase must be exactly 15 words')
|
|
24
|
+
console.error(` You entered ${words.length} words`)
|
|
25
|
+
process.exit(1)
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
console.log('\n⏳ Deriving private key (this may take a few seconds)...\n')
|
|
29
|
+
|
|
30
|
+
const privateKeyBase64 = derivePrivateKey(mnemonic.trim())
|
|
31
|
+
|
|
32
|
+
console.log('✅ Success! Your base64-encoded private key:\n')
|
|
33
|
+
console.log('─'.repeat(70))
|
|
34
|
+
console.log(privateKeyBase64)
|
|
35
|
+
console.log('─'.repeat(70))
|
|
36
|
+
console.log()
|
|
37
|
+
console.log('Add this to your edge function environment variables:')
|
|
38
|
+
console.log()
|
|
39
|
+
console.log(`LOCKFORM_RECOVERY_PHRASE="${privateKeyBase64}"`)
|
|
40
|
+
console.log()
|
|
41
|
+
console.log('⚠️ Keep this secret! Anyone with this key can decrypt all submissions.')
|
|
42
|
+
console.log()
|
|
43
|
+
|
|
44
|
+
} catch (error) {
|
|
45
|
+
console.error('\n❌ Error:', error.message)
|
|
46
|
+
process.exit(1)
|
|
47
|
+
} finally {
|
|
48
|
+
rl.close()
|
|
49
|
+
}
|
|
50
|
+
})
|
package/dist/crypto.d.ts
CHANGED
|
@@ -1,6 +1,10 @@
|
|
|
1
|
-
|
|
2
|
-
export declare function
|
|
3
|
-
export declare function
|
|
4
|
-
export declare function
|
|
5
|
-
export declare function
|
|
1
|
+
export declare function base64ToArrayBuffer(base64: string): Promise<Uint8Array>;
|
|
2
|
+
export declare function arrayBufferToString(buffer: ArrayBuffer | Uint8Array): string;
|
|
3
|
+
export declare function importPrivateKeyFromMnemonic(mnemonic: string): Uint8Array;
|
|
4
|
+
export declare function importPrivateKeyFromBase64(base64: string): Uint8Array;
|
|
5
|
+
export declare function derivePrivateKey(mnemonic: string): string;
|
|
6
|
+
export declare function decryptSubmission(ciphertext: string, iv: string, salt: string, ephemeralPublicKey: string, privateKey: Uint8Array, metadata?: {
|
|
7
|
+
formId?: string;
|
|
8
|
+
encryptionTimestamp?: number;
|
|
9
|
+
}): Promise<string>;
|
|
6
10
|
export declare function createHmacSignature(payload: string, secret: string): Promise<string>;
|
package/dist/crypto.js
CHANGED
|
@@ -2,55 +2,73 @@
|
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.base64ToArrayBuffer = base64ToArrayBuffer;
|
|
4
4
|
exports.arrayBufferToString = arrayBufferToString;
|
|
5
|
-
exports.
|
|
5
|
+
exports.importPrivateKeyFromMnemonic = importPrivateKeyFromMnemonic;
|
|
6
|
+
exports.importPrivateKeyFromBase64 = importPrivateKeyFromBase64;
|
|
7
|
+
exports.derivePrivateKey = derivePrivateKey;
|
|
6
8
|
exports.decryptSubmission = decryptSubmission;
|
|
7
9
|
exports.createHmacSignature = createHmacSignature;
|
|
8
10
|
const node_crypto_1 = require("node:crypto");
|
|
11
|
+
const ed25519_1 = require("@noble/curves/ed25519");
|
|
12
|
+
const hkdf_1 = require("@noble/hashes/hkdf");
|
|
13
|
+
const sha2_1 = require("@noble/hashes/sha2");
|
|
14
|
+
const pbkdf2_1 = require("@noble/hashes/pbkdf2");
|
|
15
|
+
const sha2_2 = require("@noble/hashes/sha2");
|
|
16
|
+
const bip39_1 = require("bip39");
|
|
9
17
|
const crypto = node_crypto_1.webcrypto;
|
|
10
18
|
async function base64ToArrayBuffer(base64) {
|
|
11
|
-
const
|
|
12
|
-
const bytes = new Uint8Array(
|
|
13
|
-
for (let i = 0; i <
|
|
14
|
-
bytes[i] =
|
|
19
|
+
const binary = Buffer.from(base64, 'base64').toString('binary');
|
|
20
|
+
const bytes = new Uint8Array(binary.length);
|
|
21
|
+
for (let i = 0; i < binary.length; i++) {
|
|
22
|
+
bytes[i] = binary.charCodeAt(i);
|
|
15
23
|
}
|
|
16
|
-
return bytes
|
|
24
|
+
return bytes;
|
|
17
25
|
}
|
|
18
26
|
function arrayBufferToString(buffer) {
|
|
19
27
|
return new TextDecoder().decode(buffer);
|
|
20
28
|
}
|
|
21
|
-
|
|
22
|
-
const
|
|
23
|
-
const
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
const binaryDer = await base64ToArrayBuffer(pemContents);
|
|
29
|
-
return await crypto.subtle.importKey('pkcs8', binaryDer, {
|
|
30
|
-
name: 'RSA-OAEP',
|
|
31
|
-
hash: 'SHA-256',
|
|
32
|
-
}, false, ['unwrapKey']);
|
|
29
|
+
function importPrivateKeyFromMnemonic(mnemonic) {
|
|
30
|
+
const seed = (0, bip39_1.mnemonicToSeedSync)(mnemonic);
|
|
31
|
+
const privateKey = (0, pbkdf2_1.pbkdf2)(sha2_2.sha512, seed, 'lockform-x25519-v1', {
|
|
32
|
+
c: 600_000,
|
|
33
|
+
dkLen: 32,
|
|
34
|
+
});
|
|
35
|
+
return privateKey;
|
|
33
36
|
}
|
|
34
|
-
|
|
37
|
+
function importPrivateKeyFromBase64(base64) {
|
|
38
|
+
return Buffer.from(base64, 'base64');
|
|
39
|
+
}
|
|
40
|
+
function derivePrivateKey(mnemonic) {
|
|
41
|
+
const privateKeyBytes = importPrivateKeyFromMnemonic(mnemonic);
|
|
42
|
+
return Buffer.from(privateKeyBytes).toString('base64');
|
|
43
|
+
}
|
|
44
|
+
function deriveSharedSecret(privateKey, publicKey) {
|
|
45
|
+
return ed25519_1.x25519.getSharedSecret(privateKey, publicKey);
|
|
46
|
+
}
|
|
47
|
+
function deriveAESKey(sharedSecret, salt) {
|
|
48
|
+
const info = new TextEncoder().encode('lockform-encryption-v1');
|
|
49
|
+
return (0, hkdf_1.hkdf)(sha2_1.sha256, sharedSecret, salt, info, 32);
|
|
50
|
+
}
|
|
51
|
+
async function decryptWithAES(ciphertext, key, iv, additionalData) {
|
|
52
|
+
const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['decrypt']);
|
|
53
|
+
const decrypted = await crypto.subtle.decrypt({
|
|
54
|
+
name: 'AES-GCM',
|
|
55
|
+
iv: iv,
|
|
56
|
+
...(additionalData && { additionalData }),
|
|
57
|
+
}, cryptoKey, ciphertext);
|
|
58
|
+
const decoder = new TextDecoder();
|
|
59
|
+
return decoder.decode(decrypted);
|
|
60
|
+
}
|
|
61
|
+
async function decryptSubmission(ciphertext, iv, salt, ephemeralPublicKey, privateKey, metadata) {
|
|
35
62
|
const ciphertextBuffer = await base64ToArrayBuffer(ciphertext);
|
|
36
63
|
const ivBuffer = await base64ToArrayBuffer(iv);
|
|
37
|
-
const
|
|
38
|
-
const
|
|
39
|
-
const
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
}, {
|
|
46
|
-
name: 'AES-GCM',
|
|
47
|
-
length: 256,
|
|
48
|
-
}, false, ['decrypt']);
|
|
49
|
-
const decryptedBuffer = await crypto.subtle.decrypt({
|
|
50
|
-
name: 'AES-GCM',
|
|
51
|
-
iv: ivBuffer,
|
|
52
|
-
}, unwrappedKey, combinedCiphertext);
|
|
53
|
-
return arrayBufferToString(decryptedBuffer);
|
|
64
|
+
const saltBuffer = await base64ToArrayBuffer(salt);
|
|
65
|
+
const ephemeralPublicKeyBuffer = await base64ToArrayBuffer(ephemeralPublicKey);
|
|
66
|
+
const sharedSecret = deriveSharedSecret(privateKey, ephemeralPublicKeyBuffer);
|
|
67
|
+
const aesKey = deriveAESKey(sharedSecret, saltBuffer);
|
|
68
|
+
const aad = metadata
|
|
69
|
+
? new TextEncoder().encode(`${metadata.formId ?? ''}:${metadata.encryptionTimestamp ?? 0}`)
|
|
70
|
+
: undefined;
|
|
71
|
+
return await decryptWithAES(ciphertextBuffer, aesKey, ivBuffer, aad);
|
|
54
72
|
}
|
|
55
73
|
async function createHmacSignature(payload, secret) {
|
|
56
74
|
const encoder = new TextEncoder();
|
package/dist/decrypt.js
CHANGED
|
@@ -3,9 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
3
3
|
exports.decryptWebhookData = decryptWebhookData;
|
|
4
4
|
const crypto_1 = require("./crypto");
|
|
5
5
|
async function decryptWebhookData(options) {
|
|
6
|
-
const { payload,
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
const { payload, passphrase } = options;
|
|
7
|
+
let privateKeyBytes;
|
|
8
|
+
if (passphrase.includes(' ')) {
|
|
9
|
+
privateKeyBytes = (0, crypto_1.importPrivateKeyFromMnemonic)(passphrase);
|
|
10
|
+
}
|
|
11
|
+
else {
|
|
12
|
+
privateKeyBytes = (0, crypto_1.importPrivateKeyFromBase64)(passphrase);
|
|
13
|
+
}
|
|
14
|
+
const decryptedData = await (0, crypto_1.decryptSubmission)(payload.ciphertext, payload.iv, payload.salt, payload.ephemeral_public_key, privateKeyBytes, {
|
|
15
|
+
formId: payload.form_id,
|
|
16
|
+
encryptionTimestamp: payload.encryption_timestamp,
|
|
17
|
+
});
|
|
9
18
|
const rawData = JSON.parse(decryptedData);
|
|
10
19
|
const mappedData = {};
|
|
11
20
|
for (const [fieldId, value] of Object.entries(rawData)) {
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.verifyWebhookSignature = exports.decryptWebhookData = void 0;
|
|
3
|
+
exports.derivePrivateKey = exports.verifyWebhookSignature = exports.decryptWebhookData = void 0;
|
|
4
4
|
var decrypt_1 = require("./decrypt");
|
|
5
5
|
Object.defineProperty(exports, "decryptWebhookData", { enumerable: true, get: function () { return decrypt_1.decryptWebhookData; } });
|
|
6
6
|
var verify_1 = require("./verify");
|
|
7
7
|
Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return verify_1.verifyWebhookSignature; } });
|
|
8
|
+
var crypto_1 = require("./crypto");
|
|
9
|
+
Object.defineProperty(exports, "derivePrivateKey", { enumerable: true, get: function () { return crypto_1.derivePrivateKey; } });
|
package/dist/types.d.ts
CHANGED
|
@@ -4,10 +4,12 @@ export interface WebhookPayload {
|
|
|
4
4
|
form_id: string;
|
|
5
5
|
ciphertext: string;
|
|
6
6
|
iv: string;
|
|
7
|
-
|
|
7
|
+
salt: string;
|
|
8
|
+
ephemeral_public_key: string;
|
|
8
9
|
auth_tag: string;
|
|
9
10
|
algorithm: string;
|
|
10
11
|
nonce: string;
|
|
12
|
+
encryption_timestamp: number;
|
|
11
13
|
timestamp: string;
|
|
12
14
|
field_mapping: Record<string, string>;
|
|
13
15
|
}
|
|
@@ -24,7 +26,7 @@ export interface DecryptedSubmission {
|
|
|
24
26
|
}
|
|
25
27
|
export interface DecryptWebhookOptions {
|
|
26
28
|
payload: WebhookPayload;
|
|
27
|
-
|
|
29
|
+
passphrase: string;
|
|
28
30
|
}
|
|
29
31
|
export interface VerifySignatureOptions {
|
|
30
32
|
payload: string;
|
package/package.json
CHANGED
|
@@ -1,15 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "lockform",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "Official SDK for processing Lockform webhook submissions with end-to-end encryption",
|
|
3
|
+
"version": "3.0.0",
|
|
4
|
+
"description": "Official SDK for processing Lockform webhook submissions with end-to-end encryption using X25519 + AES-256-GCM",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
7
7
|
"files": [
|
|
8
|
-
"dist"
|
|
8
|
+
"dist",
|
|
9
|
+
"derive-key.js"
|
|
9
10
|
],
|
|
10
11
|
"scripts": {
|
|
11
12
|
"build": "tsc",
|
|
12
|
-
"prepublishOnly": "npm run build"
|
|
13
|
+
"prepublishOnly": "npm run build",
|
|
14
|
+
"derive-key": "node derive-key.js"
|
|
15
|
+
},
|
|
16
|
+
"bin": {
|
|
17
|
+
"lockform-derive-key": "./derive-key.js"
|
|
13
18
|
},
|
|
14
19
|
"keywords": [
|
|
15
20
|
"lockform",
|
|
@@ -17,11 +22,18 @@
|
|
|
17
22
|
"webhook",
|
|
18
23
|
"e2e",
|
|
19
24
|
"forms",
|
|
20
|
-
"
|
|
21
|
-
"
|
|
25
|
+
"x25519",
|
|
26
|
+
"curve25519",
|
|
27
|
+
"aes-gcm",
|
|
28
|
+
"bip39"
|
|
22
29
|
],
|
|
23
30
|
"author": "",
|
|
24
31
|
"license": "MIT",
|
|
32
|
+
"dependencies": {
|
|
33
|
+
"@noble/curves": "^1.6.0",
|
|
34
|
+
"@noble/hashes": "^1.5.0",
|
|
35
|
+
"bip39": "^3.1.0"
|
|
36
|
+
},
|
|
25
37
|
"devDependencies": {
|
|
26
38
|
"@types/node": "^20.0.0",
|
|
27
39
|
"typescript": "^5.0.0"
|