salamailer 1.0.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "salamailer",
+  "version": "1.0.0",
+  "mcpName": "fi.salamailer/salamailer",
+  "description": "Zero-knowledge secure email CLI + MCP server — encrypt messages and attachments on your own machine, gate delivery with an SMS code or passphrase",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "encryption",
+    "end-to-end-encryption",
+    "email",
+    "secure-file-transfer",
+    "zero-knowledge",
+    "gdpr"
+  ],
+  "homepage": "https://salamailer.fi",
+  "license": "MIT",
+  "author": "Maffen Oy",
+  "type": "module",
+  "bin": {
+    "salamailer": "cli/salamailer.mjs"
+  },
+  "files": [
+    "cli/salamailer.mjs",
+    "public/js/crypto.js",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js",
+    "test": "node test/e2e.mjs",
+    "hashes": "node scripts/hashes.mjs",
+    "claims": "node scripts/claims-lint.mjs",
+    "build:hashes": "node scripts/hashes.mjs --out public/SERVED-HASHES.txt",
+    "security-report": "node test/adversarial.mjs",
+    "build:cli": "node scripts/build-cli.mjs",
+    "prestart": "node scripts/build-cli.mjs",
+    "pretest": "node scripts/build-cli.mjs",
+    "prebuild:hashes": "node scripts/build-cli.mjs",
+    "deploy": "bash scripts/deploy.sh"
+  }
+}

package/public/js/crypto.js

@@ -0,0 +1,319 @@
+// Salamailer client-side crypto — the heart of the product (PLAN.md §5).
+//
+// Everything here runs in the browser. Plaintext, content keys (CK), the KEK, the
+// VK, and the URL fragment NEVER leave this file's memory to the network.
+//
+// PROTOCOL CONSTANTS ARE FROZEN: the HKDF salt/info strings ('salamailer-reply-v1',
+// 'salamailer-paranoid-v1', 'salamailer-recovery-v1') are domain-separation labels
+// baked into every ciphertext, printed recovery key, and reply keypair. Renaming
+// them (even for branding) makes existing data undecryptable. They were switched
+// once from the old product name's spelling, pre-launch on 2026-07-13, while no
+// real user data existed; never again.
+//
+// Primitives (PLAN.md §5.2): browser-native Web Crypto only, no third-party crypto.
+//   - Content encryption: AES-256-GCM, random 96-bit IV per encryption.
+//   - Key wrapping: AES-256-GCM key-wrap.
+//   - Password -> KEK / auth verifier: PBKDF2-SHA256.
+//
+// MVP DEVIATION from PLAN.md §5.2 (documented in DECISIONS.md): the plan specifies
+// Argon2id for password stretching. Web Crypto has no Argon2, and bundling an
+// argon2 wasm would force `wasm-unsafe-eval` into the CSP — weakening the very
+// control (§7.1) that protects the whole zero-knowledge claim. For the MVP we use
+// PBKDF2-SHA256 at a high iteration count. The key hierarchy (§5.3) is identical,
+// so swapping the KDF later is a localized change.
+
+const PBKDF2_ITERS = 600_000;
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+// --- base64 helpers ---------------------------------------------------------
+export function b64(buf) {
+  const bytes = new Uint8Array(buf);
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+export function unb64(str) {
+  const bin = atob(str);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+export function b64url(buf) {
+  return b64(buf).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+export function unb64url(str) {
+  return unb64(str.replace(/-/g, '+').replace(/_/g, '/'));
+}
+export const utf8 = (s) => enc.encode(s);
+export const fromUtf8 = (buf) => dec.decode(buf);
+
+// --- packed AES-GCM blobs ("iv.ciphertext" as base64) -----------------------
+function pack(iv, ct) { return b64(iv) + '.' + b64(ct); }
+function unpack(str) {
+  const [iv, ct] = str.split('.');
+  return { iv: unb64(iv), ct: unb64(ct) };
+}
+
+// --- password -> KEK and auth verifier --------------------------------------
+async function pbkdf2Material(password) {
+  return crypto.subtle.importKey('raw', utf8(password), 'PBKDF2', false, ['deriveBits', 'deriveKey']);
+}
+
+// KEK: wraps/unwraps the VK. Never stored, never leaves the browser (§5.3).
+export async function deriveKEK(password, saltBytes) {
+  const material = await pbkdf2Material(password);
+  return crypto.subtle.deriveKey(
+    { name: 'PBKDF2', salt: saltBytes, iterations: PBKDF2_ITERS, hash: 'SHA-256' },
+    material,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['wrapKey', 'unwrapKey']
+  );
+}
+
+// Auth verifier: a value the server can check without ever seeing the password.
+export async function deriveAuthVerifier(password, saltBytes) {
+  const material = await pbkdf2Material(password);
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', salt: saltBytes, iterations: PBKDF2_ITERS, hash: 'SHA-256' },
+    material,
+    256
+  );
+  return b64(bits);
+}
+
+// --- vault key (VK) ---------------------------------------------------------
+export function generateVK() {
+  return crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['wrapKey', 'unwrapKey']);
+}
+export async function wrapVK(vk, kek) {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = await crypto.subtle.wrapKey('raw', vk, kek, { name: 'AES-GCM', iv });
+  return pack(iv, ct);
+}
+export async function unwrapVK(packed, kek) {
+  const { iv, ct } = unpack(packed);
+  return crypto.subtle.unwrapKey('raw', ct, kek, { name: 'AES-GCM', iv },
+    { name: 'AES-GCM', length: 256 }, true, ['wrapKey', 'unwrapKey']);
+}
+
+// Persist the VK on the sender's own device so compose and resend/recovery work
+// across page loads — as a NON-EXTRACTABLE CryptoKey in IndexedDB. Even code
+// running in this origin (the XSS worst case) can only *use* the key while the
+// page is open; it can never read the key bytes out. TTL-bound; cleared on logout.
+const VK_TTL_MS = 12 * 60 * 60 * 1000;
+
+function idb() {
+  return new Promise((resolve, reject) => {
+    const r = indexedDB.open('salamailer', 1);
+    r.onupgradeneeded = () => r.result.createObjectStore('kv');
+    r.onsuccess = () => resolve(r.result);
+    r.onerror = () => reject(r.error);
+  });
+}
+function idbOp(mode, fn) {
+  return idb().then((db) => new Promise((resolve, reject) => {
+    const tx = db.transaction('kv', mode);
+    const req = fn(tx.objectStore('kv'));
+    tx.oncomplete = () => { db.close(); resolve(req.result); };
+    tx.onerror = () => { db.close(); reject(tx.error); };
+  }));
+}
+
+export async function stashVK(vk) {
+  // Re-import as non-extractable: the stored handle can wrap/unwrap but never export.
+  const raw = await crypto.subtle.exportKey('raw', vk);
+  const nonExtractable = await crypto.subtle.importKey(
+    'raw', raw, { name: 'AES-GCM', length: 256 }, false, ['wrapKey', 'unwrapKey']);
+  await idbOp('readwrite', (s) => s.put({ key: nonExtractable, expiresAt: Date.now() + VK_TTL_MS }, 'vk'));
+}
+export async function loadVK() {
+  try {
+    const rec = await idbOp('readonly', (s) => s.get('vk'));
+    if (!rec || rec.expiresAt < Date.now()) { if (rec) clearVK(); return null; }
+    return rec.key;
+  } catch { return null; }
+}
+export function clearVK() {
+  idbOp('readwrite', (s) => s.delete('vk')).catch(() => { /* best effort */ });
+}
+
+// --- content key (CK) -------------------------------------------------------
+export function generateCK() {
+  return crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+}
+// Sender copy: CK wrapped under VK, stored server-side (enables resend, §5.5).
+export async function wrapCK(ck, vk) {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = await crypto.subtle.wrapKey('raw', ck, vk, { name: 'AES-GCM', iv });
+  return pack(iv, ct);
+}
+export async function unwrapCK(packed, vk) {
+  const { iv, ct } = unpack(packed);
+  return crypto.subtle.unwrapKey('raw', ct, vk, { name: 'AES-GCM', iv },
+    { name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+}
+// Recipient copy: the raw CK, carried ONLY in the URL fragment (§5.3).
+export async function exportCKFragment(ck) {
+  return b64url(await crypto.subtle.exportKey('raw', ck));
+}
+export async function importCKFragment(fragment) {
+  return crypto.subtle.importKey('raw', unb64url(fragment), { name: 'AES-GCM', length: 256 },
+    true, ['encrypt', 'decrypt']);
+}
+
+// --- saved-passphrase wrapping (per-recipient standing gate secret) ----------
+// A saved gate passphrase is stored server-side encrypted under the VK, so the
+// server can't read it. Composes the same primitives as a message: a random data
+// key encrypts the passphrase; that key is wrapped under the VK. Returns the
+// three fields to persist; unwrap needs the VK (password-derived, sender-only).
+export async function wrapPassphrase(passphrase, vk) {
+  const dk = await generateCK();
+  const { iv, ct } = await encryptBytes(dk, utf8(passphrase));
+  return { keyWrapped: await wrapCK(dk, vk), iv, ct: b64(ct) };
+}
+export async function unwrapPassphrase({ keyWrapped, iv, ct }, vk) {
+  const dk = await unwrapCK(keyWrapped, vk);
+  return fromUtf8(await decryptBytes(dk, iv, unb64(ct)));
+}
+
+// --- secure reply (asymmetric, ECIES over ECDH P-256) ------------------------
+// Each user has one reply keypair. The private key is wrapped under the VK and
+// stored server-side (useless without the password); the PUBLIC key is never
+// stored server-side at all — it travels to the recipient INSIDE the encrypted
+// message envelope, so a malicious server cannot swap it. The recipient encrypts
+// their reply under an ephemeral ECDH key against that public key; only the
+// sender's unwrapped private key can derive the reply key.
+export function generateReplyKeypair() {
+  return crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
+}
+export async function wrapReplySK(sk, vk) {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = await crypto.subtle.wrapKey('jwk', sk, vk, { name: 'AES-GCM', iv });
+  return pack(iv, ct);
+}
+export async function unwrapReplySK(packed, vk) {
+  const { iv, ct } = unpack(packed);
+  return crypto.subtle.unwrapKey('jwk', ct, vk, { name: 'AES-GCM', iv },
+    { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
+}
+// The EC private JWK contains the public point (x, y) — derive the public key
+// locally from the unwrapped private key; never trust a server-supplied copy.
+export async function replyPubJwk(sk) {
+  const j = await crypto.subtle.exportKey('jwk', sk);
+  return { x: j.x, y: j.y };
+}
+function importReplyPub({ x, y }) {
+  return crypto.subtle.importKey('jwk', { kty: 'EC', crv: 'P-256', x, y },
+    { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+}
+async function ecdhToAes(privKey, pubKey, saltBytes) {
+  const bits = await crypto.subtle.deriveBits({ name: 'ECDH', public: pubKey }, privKey, 256);
+  const hk = await crypto.subtle.importKey('raw', bits, 'HKDF', false, ['deriveKey']);
+  return crypto.subtle.deriveKey(
+    { name: 'HKDF', hash: 'SHA-256', salt: saltBytes, info: utf8('salamailer-reply-v1') },
+    hk, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+// Recipient side: fresh ephemeral keypair per reply against the sender's public key.
+export async function deriveReplyKeyForSend(senderPubJwk) {
+  const eph = await crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const key = await ecdhToAes(eph.privateKey, await importReplyPub(senderPubJwk), salt);
+  const ephJwk = await crypto.subtle.exportKey('jwk', eph.publicKey);
+  return { key, ephPub: { x: ephJwk.x, y: ephJwk.y }, hkdfSalt: b64(salt) };
+}
+// Sender side: unwrapped reply SK + the reply's stored ephemeral pub + salt.
+export async function deriveReplyKeyForRead(replySk, ephPubJwk, hkdfSaltB64) {
+  return ecdhToAes(replySk, await importReplyPub(ephPubJwk), unb64(hkdfSaltB64));
+}
+
+// --- message body envelope ----------------------------------------------------
+// The body blob's plaintext is a JSON envelope so the sender's reply public key
+// rides INSIDE the end-to-end encryption. Legacy bodies (plain text) still parse.
+export function packEnvelope(text, replyPub) {
+  return JSON.stringify(replyPub ? { sala: 2, text, replyPub } : { sala: 2, text });
+}
+export function parseEnvelope(str) {
+  try {
+    const o = JSON.parse(str);
+    if (o && o.sala === 2 && typeof o.text === 'string')
+      return { text: o.text, replyPub: o.replyPub && o.replyPub.x && o.replyPub.y ? o.replyPub : null };
+  } catch { /* legacy plain-text body */ }
+  return { text: str, replyPub: null };
+}
+
+// --- paranoid mode (PLAN.md §5.4 roadmap decision, opt-in) --------------------
+// Mixes the second-channel secret into key derivation via HKDF, so a combined
+// server-breach + email-interception attacker (who holds ciphertext + the URL
+// fragment) still cannot decrypt without the gate secret. The fragment and the
+// sender's wrapped CK stay the RAW CK — resend/recovery flows are unchanged;
+// only the content-encryption key is derived. Passphrase gates only: SMS codes
+// rotate on resend, which would orphan the ciphertext.
+export async function deriveParanoidKey(ck, gateSecret) {
+  const raw = await crypto.subtle.exportKey('raw', ck);
+  const hk = await crypto.subtle.importKey('raw', raw, 'HKDF', false, ['deriveKey']);
+  return crypto.subtle.deriveKey(
+    { name: 'HKDF', hash: 'SHA-256', salt: utf8('salamailer-paranoid-v1'), info: utf8(gateSecret) },
+    hk, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+
+// --- printable recovery key (PLAN.md §5.5 roadmap decision) -------------------
+// A 256-bit random code the user prints and stores offline. It separately wraps
+// the VK, so a forgotten password no longer orphans the sender's vault. Two
+// independent values are derived from it with HKDF domain separation:
+//   wrapKey  — wraps/unwraps the VK (client-side only, like the KEK)
+//   verifier — proves possession to the server (stored scrypt-hashed, like the
+//              auth verifier; it cannot unwrap anything)
+// Crockford base32, no lookalikes (O→0, I/L→1 accepted on input).
+const B32 = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+function b32encode(bytes) {
+  let bits = 0, acc = 0, out = '';
+  for (const b of bytes) {
+    acc = (acc << 8) | b; bits += 8;
+    while (bits >= 5) { bits -= 5; out += B32[(acc >> bits) & 31]; }
+  }
+  if (bits) out += B32[(acc << (5 - bits)) & 31];
+  return out;
+}
+function b32decode(str) {
+  const norm = str.toUpperCase().replace(/O/g, '0').replace(/[IL]/g, '1').replace(/[^0-9A-Z]/g, '');
+  if (norm.length !== 52) throw new Error('recovery code must be 52 characters');
+  let bits = 0, acc = 0;
+  const out = [];
+  for (const c of norm) {
+    const v = B32.indexOf(c);
+    if (v < 0) throw new Error('invalid character in recovery code');
+    acc = (acc << 5) | v; bits += 5;
+    if (bits >= 8) { bits -= 8; out.push((acc >> bits) & 255); }
+  }
+  return new Uint8Array(out.slice(0, 32));
+}
+export function generateRecoveryCode() {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return b32encode(bytes).match(/.{1,4}/g).join('-');
+}
+export async function deriveRecoveryKeys(code) {
+  const bytes = b32decode(code);
+  const hk = await crypto.subtle.importKey('raw', bytes, 'HKDF', false, ['deriveKey', 'deriveBits']);
+  const params = (info) => ({ name: 'HKDF', hash: 'SHA-256', salt: utf8('salamailer-recovery-v1'), info: utf8(info) });
+  const wrapKey = await crypto.subtle.deriveKey(params('wrap'), hk,
+    { name: 'AES-GCM', length: 256 }, false, ['wrapKey', 'unwrapKey']);
+  const verifier = b64(await crypto.subtle.deriveBits(params('verify'), hk, 256));
+  return { wrapKey, verifier };
+}
+
+// --- content encryption -----------------------------------------------------
+export async function encryptBytes(ck, bytes) {
+  const iv = crypto.getRandomValues(new Uint8Array(12)); // unique per encryption (§5.6)
+  const ct = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, ck, bytes);
+  return { iv: b64(iv), ct: new Uint8Array(ct) };
+}
+export async function decryptBytes(ck, ivB64, ctBytes) {
+  const pt = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: unb64(ivB64) }, ck, ctBytes);
+  return new Uint8Array(pt);
+}
+
+export function randomSalt() {
+  return b64(crypto.getRandomValues(new Uint8Array(16)));
+}