lockform 1.0.0

package/README.md

@@ -0,0 +1,235 @@
+# Lockform
+
+Official SDK for processing Lockform webhook submissions with end-to-end encryption.
+
+## Installation
+
+```bash
+npm install lockform
+```
+
+## Features
+
+- **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
+- **TypeScript support**: Full type definitions included
+
+## Quick Start
+
+### Decrypting Webhook Data
+
+```typescript
+import { decryptWebhookData } from 'lockform'
+
+const privateKey = `-----BEGIN PRIVATE KEY-----
+YOUR_PRIVATE_KEY_HERE
+-----END PRIVATE KEY-----`
+
+app.post('/webhook', async (req, res) => {
+  const payload = req.body
+
+  const result = await decryptWebhookData({
+    payload,
+    privateKey,
+  })
+
+  console.log('Mapped data:', result.mappedData)
+
+  res.json({ success: true })
+})
+```
+
+### Verifying Webhook Signatures
+
+```typescript
+import { verifyWebhookSignature, decryptWebhookData } from 'lockform'
+
+app.post('/webhook', async (req, res) => {
+  const signature = req.headers['x-signature-sha256']
+  const webhookSecret = process.env.WEBHOOK_SECRET
+
+  const isValid = await verifyWebhookSignature({
+    payload: JSON.stringify(req.body),
+    signature,
+    secret: webhookSecret,
+  })
+
+  if (!isValid) {
+    return res.status(401).json({ error: 'Invalid signature' })
+  }
+
+  const result = await decryptWebhookData({
+    payload: req.body,
+    privateKey: process.env.PRIVATE_KEY,
+  })
+
+  console.log('Decrypted data:', result.mappedData)
+
+  res.json({ success: true })
+})
+```
+
+## API Reference
+
+### `decryptWebhookData(options)`
+
+Decrypts an encrypted webhook payload from Lockform.
+
+**Parameters:**
+- `options.payload` (WebhookPayload): The webhook payload received from Lockform
+- `options.privateKey` (string): Your RSA private key in PEM format
+
+**Returns:** `Promise<DecryptedSubmission>`
+
+```typescript
+{
+  rawData: Record<string, unknown>,      // Decrypted data with field IDs as keys
+  mappedData: Record<string, unknown>,   // Decrypted data with CSV names as keys
+  metadata: {
+    event_type: string,
+    submission_id: string,
+    form_id: string,
+    timestamp: string,
+    nonce: string,
+  }
+}
+```
+
+**Example:**
+
+```typescript
+const result = await decryptWebhookData({
+  payload: webhookPayload,
+  privateKey: myPrivateKey,
+})
+
+console.log(result.mappedData)
+```
+
+### `verifyWebhookSignature(options)`
+
+Verifies the HMAC-SHA256 signature of a webhook payload.
+
+**Parameters:**
+- `options.payload` (string): The raw JSON string of the webhook payload
+- `options.signature` (string): The signature from the `X-Signature-SHA256` header
+- `options.secret` (string): Your webhook secret
+
+**Returns:** `Promise<boolean>` - `true` if the signature is valid, `false` otherwise
+
+**Example:**
+
+```typescript
+const isValid = await verifyWebhookSignature({
+  payload: JSON.stringify(req.body),
+  signature: req.headers['x-signature-sha256'],
+  secret: process.env.WEBHOOK_SECRET,
+})
+
+if (!isValid) {
+  throw new Error('Invalid webhook signature')
+}
+```
+
+## Types
+
+### WebhookPayload
+
+```typescript
+interface WebhookPayload {
+  event_type: string
+  submission_id: string
+  form_id: string
+  ciphertext: string
+  iv: string
+  wrapped_key: string
+  auth_tag: string
+  algorithm: string
+  nonce: string
+  timestamp: string
+  field_mapping: Record<string, string>
+}
+```
+
+### DecryptedSubmission
+
+```typescript
+interface DecryptedSubmission {
+  rawData: Record<string, unknown>
+  mappedData: Record<string, unknown>
+  metadata: {
+    event_type: string
+    submission_id: string
+    form_id: string
+    timestamp: string
+    nonce: string
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import express from 'express'
+import { decryptWebhookData, verifyWebhookSignature } from 'lockform'
+
+const app = express()
+app.use(express.json())
+
+const PRIVATE_KEY = process.env.LOCKFORM_PRIVATE_KEY
+const WEBHOOK_SECRET = process.env.LOCKFORM_WEBHOOK_SECRET
+
+app.post('/lockform-webhook', async (req, res) => {
+  try {
+    const signature = req.headers['x-signature-sha256'] as string
+    const payload = req.body
+
+    if (WEBHOOK_SECRET && signature) {
+      const isValid = await verifyWebhookSignature({
+        payload: JSON.stringify(payload),
+        signature,
+        secret: WEBHOOK_SECRET,
+      })
+
+      if (!isValid) {
+        return res.status(401).json({ error: 'Invalid signature' })
+      }
+    }
+
+    const result = await decryptWebhookData({
+      payload,
+      privateKey: PRIVATE_KEY,
+    })
+
+    console.log('Form ID:', result.metadata.form_id)
+    console.log('Submission ID:', result.metadata.submission_id)
+    console.log('Data:', result.mappedData)
+
+    res.json({ success: true })
+  } catch (error) {
+    console.error('Error processing webhook:', error)
+    res.status(500).json({ error: 'Failed to process webhook' })
+  }
+})
+
+app.listen(3000, () => {
+  console.log('Webhook server listening on port 3000')
+})
+```
+
+## 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
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- TypeScript 5.0.0 or higher (for TypeScript projects)
+
+## License
+
+MIT

package/dist/crypto.d.ts

@@ -0,0 +1,6 @@
+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 createHmacSignature(payload: string, secret: string): Promise<string>;

package/dist/crypto.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.base64ToArrayBuffer = base64ToArrayBuffer;
+exports.arrayBufferToString = arrayBufferToString;
+exports.importPrivateKey = importPrivateKey;
+exports.decryptSubmission = decryptSubmission;
+exports.createHmacSignature = createHmacSignature;
+const node_crypto_1 = require("node:crypto");
+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);
+    }
+    return bytes.buffer;
+}
+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']);
+}
+async function decryptSubmission(ciphertext, iv, wrappedKey, authTag, privateKey) {
+    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);
+}
+async function createHmacSignature(payload, secret) {
+    const encoder = new TextEncoder();
+    const keyData = encoder.encode(secret);
+    const messageData = encoder.encode(payload);
+    const cryptoKey = await crypto.subtle.importKey('raw', keyData, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', cryptoKey, messageData);
+    return Array.from(new Uint8Array(signature))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}

package/dist/decrypt.d.ts

@@ -0,0 +1,2 @@
+import { DecryptedSubmission, DecryptWebhookOptions } from './types';
+export declare function decryptWebhookData(options: DecryptWebhookOptions): Promise<DecryptedSubmission>;

package/dist/decrypt.js

@@ -0,0 +1,31 @@
+"use strict";
+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 rawData = JSON.parse(decryptedData);
+    const mappedData = {};
+    for (const [fieldId, value] of Object.entries(rawData)) {
+        const csvName = payload.field_mapping[fieldId];
+        if (csvName) {
+            mappedData[csvName] = value;
+        }
+        else {
+            mappedData[fieldId] = value;
+        }
+    }
+    return {
+        rawData,
+        mappedData,
+        metadata: {
+            event_type: payload.event_type,
+            submission_id: payload.submission_id,
+            form_id: payload.form_id,
+            timestamp: payload.timestamp,
+            nonce: payload.nonce,
+        },
+    };
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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; } });

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+export interface WebhookPayload {
+    event_type: string;
+    submission_id: string;
+    form_id: string;
+    ciphertext: string;
+    iv: string;
+    wrapped_key: string;
+    auth_tag: string;
+    algorithm: string;
+    nonce: string;
+    timestamp: string;
+    field_mapping: Record<string, string>;
+}
+export interface DecryptedSubmission {
+    rawData: Record<string, unknown>;
+    mappedData: Record<string, unknown>;
+    metadata: {
+        event_type: string;
+        submission_id: string;
+        form_id: string;
+        timestamp: string;
+        nonce: string;
+    };
+}
+export interface DecryptWebhookOptions {
+    payload: WebhookPayload;
+    privateKey: string;
+}
+export interface VerifySignatureOptions {
+    payload: string;
+    signature: string;
+    secret: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/verify.d.ts

@@ -0,0 +1,2 @@
+import { VerifySignatureOptions } from './types';
+export declare function verifyWebhookSignature(options: VerifySignatureOptions): Promise<boolean>;

package/dist/verify.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = verifyWebhookSignature;
+const crypto_1 = require("./crypto");
+async function verifyWebhookSignature(options) {
+    const { payload, signature, secret } = options;
+    const expectedSignature = await (0, crypto_1.createHmacSignature)(payload, secret);
+    return expectedSignature === signature;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "lockform",
+  "version": "1.0.0",
+  "description": "Official SDK for processing Lockform webhook submissions with end-to-end encryption",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "lockform",
+    "encryption",
+    "webhook",
+    "e2e",
+    "forms",
+    "rsa",
+    "aes"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}