formdecrypt 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# formdecrypt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Creates keys for [formcrypt](https://github.com/camilodelvasto/formcrypt/tree/main/formcrypt) and decrypts CSV exports of form submissions, locally. Node 20 or later, no dependencies.
+
+```sh
+npx formdecrypt keygen               # writes ./formcrypt.key, prints the public key for your form
+npx formdecrypt export.csv           # writes ./export.decrypted.csv
+npx formdecrypt export.csv out.csv
+```
+
+The private key is read from `./formcrypt.key`, or from the `FORMCRYPT_KEY` environment variable. Keep a copy somewhere safe: without it, submissions can't be read.
+
+**Getting the CSV from Netlify:** Site → Forms → your form → Download as CSV.
+
+Every cell that holds a `fc1-` envelope is decrypted in place under its column name. Columns, order and plain cells are untouched, so submissions from before you added encryption come through as they are. A cell that can't be decrypted (wrong key, or moved to another column) is left as it is, and the exit code is 1. Existing files are never overwritten.
+
+**The output is plaintext.** Store it as carefully as the data deserves. Submissions come from strangers, so a value starting with `=`, `+`, `-` or `@` can run as a formula in a spreadsheet program. Import as text if in doubt.
+
+## Format v1
+
+So readers can be written in any language:
+
+- **Envelope:** `fc1-` + lowercase hex of `ephemeral P-256 public key (65 B, uncompressed) ‖ IV (12 B) ‖ AES-256-GCM ciphertext + 16 B tag`
+- **AES key:** HKDF-SHA256 over ECDH(ephemeral, recipient), with salt = the 65-byte ephemeral public key and info = `formcrypt/v1`, giving 32 bytes
+- **Plaintext:** the field's value, UTF-8. **Additional authenticated data:** the field's name, UTF-8
+- **Keys:** `fc1pk.` + base64url(raw public key) and `fc1sk.` + base64url(PKCS#8 private key)
+
+MIT

package/formdecrypt.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// formdecrypt 0.3.0 · MIT · Keys and CSV decryption for formcrypt (format v1)
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+
+const { subtle } = globalThis.crypto
+const P256 = { name: 'ECDH', namedCurve: 'P-256' }
+const KEYFILE = 'formcrypt.key'
+const ENVELOPE = /^fc1-[0-9a-f]{186,}$/
+const fail = (msg) => { console.error(`formdecrypt: ${msg}`); process.exit(1) }
+
+async function keygen() {
+  if (existsSync(KEYFILE)) fail(`${KEYFILE} already exists; not overwriting it`)
+  const kp = await subtle.generateKey(P256, true, ['deriveBits'])
+  const pub = Buffer.from(await subtle.exportKey('raw', kp.publicKey)).toString('base64url')
+  const priv = Buffer.from(await subtle.exportKey('pkcs8', kp.privateKey)).toString('base64url')
+  writeFileSync(KEYFILE, `fc1sk.${priv}\n`, { flag: 'wx', mode: 0o600 })
+  console.log(`fc1pk.${pub}`)
+  console.error(`Private key written to ${KEYFILE}. Keep it safe: without it, submissions can't be read.`)
+}
+
+async function loadKey() {
+  const s = (process.env.FORMCRYPT_KEY ?? (existsSync(KEYFILE) ? readFileSync(KEYFILE, 'utf8') : '')).trim()
+  if (!s.startsWith('fc1sk.')) fail(`no private key: put it in ./${KEYFILE} or in FORMCRYPT_KEY`)
+  return subtle.importKey('pkcs8', Buffer.from(s.slice(6), 'base64url'), P256, false, ['deriveBits'])
+}
+
+// Opens one envelope sealed under this field name. Throws if the key or the name is wrong.
+async function open(envelope, privateKey, name) {
+  const raw = Buffer.from(envelope.slice(4), 'hex')
+  const ephRaw = raw.subarray(0, 65)
+  const eph = await subtle.importKey('raw', ephRaw, P256, false, [])
+  const bits = await subtle.deriveBits({ name: 'ECDH', public: eph }, privateKey, 256)
+  const hkdf = await subtle.importKey('raw', bits, 'HKDF', false, ['deriveKey'])
+  const key = await subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: ephRaw, info: Buffer.from('formcrypt/v1') },
+    hkdf, { name: 'AES-GCM', length: 256 }, false, ['decrypt'])
+  const pt = await subtle.decrypt({ name: 'AES-GCM', iv: raw.subarray(65, 77), additionalData: Buffer.from(name) }, key, raw.subarray(77))
+  return Buffer.from(pt).toString('utf8')
+}
+
+// RFC 4180: quoted fields, "" escapes, line breaks inside quotes.
+function parseCSV(text) {
+  const rows = []
+  let row = [], field = '', quoted = false
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]
+    if (quoted) {
+      if (c !== '"') field += c
+      else if (text[i + 1] === '"') { field += '"'; i++ }
+      else quoted = false
+    } else if (c === '"') quoted = true
+    else if (c === ',') { row.push(field); field = '' }
+    else if (c === '\n' || c === '\r') {
+      if (c === '\r' && text[i + 1] === '\n') i++
+      row.push(field); rows.push(row); row = []; field = ''
+    } else field += c
+  }
+  if (field || row.length) { row.push(field); rows.push(row) }
+  return rows
+}
+const cell = (v) => (/[",\r\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v)
+const toCSV = (rows) => rows.map((r) => r.map(cell).join(',')).join('\n') + '\n'
+
+// Every cell that looks like an envelope is decrypted in place under its column name. Nothing else changes.
+async function decrypt(input, output = input.replace(/\.csv$/i, '') + '.decrypted.csv') {
+  if (existsSync(output)) fail(`${output} already exists; not overwriting it`)
+  const [head, ...body] = parseCSV(readFileSync(input, 'utf8').replace(/^/, ''))
+  const key = await loadKey()
+  let found = 0, failed = 0
+  for (const row of body) {
+    for (let i = 0; i < row.length; i++) {
+      const v = row[i].trim()
+      if (!ENVELOPE.test(v)) continue
+      found++
+      try { row[i] = await open(v, key, head[i] ?? '') } catch { failed++ }
+    }
+  }
+  writeFileSync(output, toCSV([head, ...body]), { flag: 'wx' })
+  console.error(`Wrote ${output}: ${body.length} rows, ${found} encrypted cells${failed ? `, ${failed} cells could not be decrypted` : ''}. It contains plaintext.`)
+  if (failed) process.exitCode = 1
+}
+
+const [a, b] = process.argv.slice(2)
+if (a === 'keygen') await keygen()
+else if (a && !a.startsWith('-')) await decrypt(a, b)
+else console.error('usage: formdecrypt keygen | formdecrypt <export.csv> [out.csv]')

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "formdecrypt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Create formcrypt keys and decrypt the encrypted cells of a CSV export in place, locally.",
+  "type": "module",
+  "bin": {
+    "formdecrypt": "formdecrypt.js"
+  },
+  "files": [
+    "formdecrypt.js"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "form",
+    "encryption",
+    "decrypt",
+    "csv",
+    "netlify",
+    "formcrypt"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/camilodelvasto/formcrypt.git",
+    "directory": "formdecrypt"
+  },
+  "homepage": "https://github.com/camilodelvasto/formcrypt/tree/main/formdecrypt#readme",
+  "bugs": "https://github.com/camilodelvasto/formcrypt/issues"
+}