voidlogue-crypto 1.0.0

package/LICENSE

@@ -0,0 +1,57 @@
+MIT License
+
+Copyright (c) 2026 Voidlogue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+## License rationale
+
+This package is published under the MIT license for the following reasons:
+
+1. **Auditability over restriction.** The purpose of open-sourcing this package
+   is to allow independent verification of Voidlogue's privacy claims. A
+   permissive license removes barriers to inspection and review.
+
+2. **Cryptographic primitives benefit from wide scrutiny.** Security research
+   is best served by making cryptographic code as accessible as possible.
+   Restrictive licenses discourage security researchers.
+
+3. **The word list is already public.** The EFF long wordlist included in this
+   package is published by the Electronic Frontier Foundation under an open
+   license. There is no proprietary component to protect here.
+
+4. **This package alone cannot replicate Voidlogue.** The client-side crypto
+   layer requires a server (Phoenix/Elixir backend, PostgreSQL, Oban jobs,
+   push infrastructure) which is not included here. Permissive licensing of
+   this package does not expose the platform's competitive differentiators.
+
+## What the MIT license means for you
+
+- You can read, inspect, fork, and use this code for any purpose
+- You can use it in commercial products
+- You must include the copyright notice in any copy or substantial portion
+- There is no warranty — use at your own risk
+
+## What this license does NOT cover
+
+The Voidlogue platform server code, the Revelation product, the admin
+infrastructure, and the marketing pages are proprietary and are NOT covered
+by this license. This license applies only to the files in this repository.

package/README.md

@@ -0,0 +1,215 @@
+# voidlogue-crypto
+
+**Open-source cryptographic layer for Voidlogue — published for independent audit and verification.**
+
+[![npm version](https://img.shields.io/npm/v/voidlogue-crypto.svg)](https://www.npmjs.com/package/voidlogue-crypto)
+[![License: MIT](https://img.shields.io/badge/License-MIT-teal.svg)](./LICENSE)
+
+This package contains exactly the code running in the browser at [voidlogue.com](https://voidlogue.com).
+It is published so that Voidlogue's privacy claims can be independently verified.
+
+---
+
+## What this proves
+
+| Claim | Code |
+|---|---|
+| "We cannot read your messages" | `VoidShield.roomId()`, `VoidShield.deriveKey()`, `VoidShield.encrypt()` |
+| "We cannot read your Revelations" | `VoidShield.deriveRevelationKey()`, `VoidShield.encryptMedia()` |
+| "Your saved shortcuts are encrypted locally" | `Vault.save()`, `Vault.load()` |
+
+See [SECURITY.md](./SECURITY.md) for a full technical explanation of each claim.
+
+---
+
+## Installation
+
+```bash
+npm install voidlogue-crypto
+```
+
+---
+
+## Usage
+
+```javascript
+import { VoidShield, generateCodename } from "voidlogue-crypto";
+
+// Derive a room hash (server never sees emails or codename)
+const roomHash = await VoidShield.roomId(
+  "alice@example.com",
+  "bob@example.com",
+  "iron-falcon-sky"
+);
+
+// Derive encryption key
+const key = await VoidShield.deriveKey("iron-falcon-sky", roomHash);
+
+// Encrypt a message
+const { ciphertextB64, ivB64 } = await VoidShield.encrypt("hello", key);
+
+// Decrypt (throws if key is wrong — AES-GCM authentication)
+const plaintext = await VoidShield.decrypt(ciphertextB64, ivB64, key);
+
+// Generate a random codename from the EFF wordlist
+const codename = generateCodename(4); // e.g. "correct-horse-battery-staple"
+```
+
+---
+
+## API Reference
+
+### `VoidShield`
+
+#### Conversation
+
+| Method | Description |
+|---|---|
+| `hex(input)` | SHA-256 of input string → 64-char hex |
+| `roomId(emailA, emailB, codename)` | Derives opaque room hash. Commutative. |
+| `validateCodename(codename)` | Returns `{ valid, reason? }` |
+| `deriveKey(codename, roomHash)` | PBKDF2 → AES-256-GCM key (non-extractable) |
+| `encrypt(plaintext, key)` | AES-256-GCM → `{ ciphertextB64, ivB64 }` |
+| `decrypt(ciphertextB64, ivB64, key)` | AES-256-GCM → plaintext string |
+| `senderHash(uuid, roomHash)` | Room-scoped sender identifier |
+
+#### Revelation
+
+| Method | Description |
+|---|---|
+| `deriveRevelationKey(senderEmail, recipientEmail, fieldValues[])` | Key from emails + security fields |
+| `deriveRevelationKeyFromHashes(senderHash, recipientHash, fieldValues[])` | Key from pre-computed hashes |
+| `hashFieldValue(value)` | Normalise + SHA-256 for server storage |
+| `encryptMedia(file, key)` | Chunked file encryption → chunk array |
+| `decryptMediaStream(chunks, key)` | Async generator → ArrayBuffer per chunk |
+
+#### Utilities
+
+| Method | Description |
+|---|---|
+| `secureRandom(max)` | Uniform random int in `[0, max)` — rejection sampling |
+
+### `generateCodename(wordCount?)`
+
+Generates a hyphen-separated passphrase from the EFF long wordlist.
+
+- Default: 3 words (~38 bits of entropy)
+- Range: 2–8 words, clamped
+- 4 words ≈ 51 bits, 5 words ≈ 64 bits, 6 words ≈ 77 bits
+
+```javascript
+generateCodename()  // "iron-falcon-sky"
+generateCodename(5) // "correct-horse-battery-staple-moon"
+```
+
+### `Vault`
+
+PIN-based local encryption for saved conversation credentials.
+
+```javascript
+import { Vault } from "voidlogue-crypto";
+
+// Save email + codename encrypted with PIN
+await Vault.save(roomHash, email, codename, "123456", "Alice — work");
+
+// Load (returns {email, codename} or {error: "wrong_pin"|"locked"|"not_found"})
+const result = await Vault.load(roomHash, "123456");
+
+// List saved conversations (no sensitive data)
+const list = Vault.list(); // [{roomHash, hint (encrypted), savedAt}]
+
+// Wipe all (panic clear)
+Vault.wipeAll();
+```
+
+### `EFF_WORDLIST`
+
+The complete EFF long wordlist — 7776 words, frozen array.
+
+```javascript
+import { EFF_WORDLIST } from "voidlogue-crypto";
+console.log(EFF_WORDLIST.length); // 7776
+```
+
+---
+
+## Cryptographic algorithm summary
+
+```
+Room hash:
+  hA, hB   = SHA-256(email.toLowerCase().trim())
+  roomHash = SHA-256(sort([hA,hB]).join(":") + ":" + codename + ":" + APP_SALT)
+
+Conversation key:
+  key = PBKDF2(codename, salt=roomHash, iters=100_000, hash=SHA-256) → AES-256-GCM
+
+Revelation key:
+  hS, hR = SHA-256(email.toLowerCase().trim())
+  fh[]   = SHA-256(normalise(fieldValue))
+  input  = sort([hS,hR]).join(":") + ":" + fh.join(":")
+  key    = PBKDF2(input, salt="voidlogue-revelation-v1", iters=100_000) → AES-256-GCM
+
+Vault PIN key:
+  key = PBKDF2(PIN, random_16B_salt, iters=100_000, hash=SHA-256) → AES-256-GCM
+
+All encryption: AES-256-GCM with random 96-bit IV per operation
+All randomness: crypto.getRandomValues() with rejection sampling
+```
+
+No third-party cryptographic libraries. All operations use the Web Crypto API.
+
+---
+
+## Running the tests
+
+```bash
+npm install
+npm test
+```
+
+Tests cover:
+- SHA-256 against known vectors
+- `roomId` commutativity, determinism, isolation
+- Encrypt/decrypt round-trip and tamper detection
+- Revelation key derivation cross-compatibility
+- `secureRandom` uniformity and bounds
+- Media chunk encryption and decryption
+- `generateCodename` wordlist coverage
+- `EFF_WORDLIST` integrity (7776 entries, no duplicates, frozen)
+- Security invariants (ciphertext contains no plaintext, hashes contain no inputs)
+
+---
+
+## Verifying the deployed code
+
+The code at [voidlogue.com](https://voidlogue.com) uses this package directly.
+To verify:
+
+1. Open voidlogue.com in your browser
+2. DevTools → Sources → search for `VoidShield` or `roomId`
+3. Compare the implementation against this repository
+
+---
+
+## What is NOT in this package
+
+- Server code (Phoenix/Elixir backend)
+- Database schema or queries
+- The Revelation product server logic
+- Payment or subscription code
+- Admin infrastructure
+- Anything that runs outside the browser
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details and rationale.
+
+## Security disclosure
+
+See [SECURITY.md](./SECURITY.md) — email security@voidlogue.com for vulnerabilities.
+
+---
+
+*Part of [Voidlogue](https://voidlogue.com) — Said once. Gone forever.*

package/SECURITY.md

@@ -0,0 +1,154 @@
+# Security Policy
+
+## What this package proves
+
+This package is the open-source cryptographic layer for Voidlogue. It is
+published so that the following privacy claims can be independently verified
+against the actual code running in the browser.
+
+---
+
+### Claim 1: "We cannot read your Conversation messages"
+
+**Code that proves it:** `src/voidshield.js` — `roomId()`, `deriveKey()`, `encrypt()`
+
+Room hashes are derived entirely client-side from the pair of email addresses
+and the shared codename. The algorithm:
+
+```
+hA       = SHA-256(emailA.toLowerCase().trim())
+hB       = SHA-256(emailB.toLowerCase().trim())
+roomHash = SHA-256(sort([hA, hB]).join(":") + ":" + codename + ":" + APP_SALT)
+```
+
+The server receives only `roomHash` — an opaque 64-character hex string. It
+cannot reverse this to learn the email addresses or the codename.
+
+The encryption key is derived from the codename:
+
+```
+key = PBKDF2(codename, salt=roomHash, iterations=100_000, hash=SHA-256)
+     → AES-256-GCM key (non-extractable)
+```
+
+The codename is never sent to the server. The server stores only
+`AES-256-GCM(plaintext, key, random_IV)` — ciphertext it cannot decrypt
+because it never held the key material.
+
+---
+
+### Claim 2: "We cannot read your Revelations"
+
+**Code that proves it:** `src/voidshield.js` — `deriveRevelationKey()`,
+`deriveRevelationKeyFromHashes()`, `encryptMedia()`
+
+Revelation content is encrypted before upload. The key is derived from:
+
+```
+hS    = SHA-256(senderEmail.toLowerCase().trim())
+hR    = SHA-256(recipientEmail.toLowerCase().trim())
+fh[]  = SHA-256(normalise(fieldValue)) for each security field
+
+input = sort([hS, hR]).join(":") + ":" + fh.join(":")
+key   = PBKDF2(input, salt="voidlogue-revelation-v1", iterations=100_000)
+      → AES-256-GCM key
+```
+
+The security field values (e.g. the recipient's date of birth, first name)
+are never sent to the server. The server stores only the hashes of field
+values for access control purposes — and never the values themselves. The
+decryption key cannot be derived without the raw field values which only the
+recipient holds.
+
+Delivery does not require decryption. The server relays encrypted bytes it
+cannot read.
+
+---
+
+### Claim 3: "Your saved conversation shortcuts are encrypted locally"
+
+**Code that proves it:** `src/vault.js`
+
+The Vault encrypts the user's email and codename on-device before storing
+them in `localStorage`:
+
+```
+key  = PBKDF2(PIN, random_salt, iterations=100_000) → AES-256-GCM key
+blob = AES-256-GCM(JSON({email, codename}), key, random_IV)
+```
+
+The PIN is never stored anywhere. The server is never involved. Even if
+someone extracts the device's `localStorage` they receive AES-256-GCM
+ciphertext that cannot be decrypted without the PIN.
+
+---
+
+## Cryptographic primitive choices
+
+| Primitive | Algorithm | Rationale |
+|---|---|---|
+| Symmetric encryption | AES-256-GCM | NIST-approved; provides authenticated encryption (tamper detection) |
+| Key derivation | PBKDF2, SHA-256, 100k iterations | Standardised; makes brute-force computationally expensive |
+| Hashing | SHA-256 | Collision-resistant; output is 256 bits |
+| Randomness | `crypto.getRandomValues` with rejection sampling | Cryptographically secure; rejection sampling eliminates modular bias |
+
+No third-party cryptographic libraries are used. All operations use the
+Web Crypto API built into the browser.
+
+---
+
+## What this package does NOT prove
+
+- That the server does not log data it should not log (requires server audit)
+- That the server deletes messages as described (requires server audit)
+- That the N=1 constraint is enforced server-side (requires server audit)
+- That the server does not store session data beyond what is stated
+
+These claims require auditing the server code, which is not included here.
+We will answer specific questions about the server implementation directly.
+
+---
+
+## Threat model
+
+### Protects against
+
+- Platform reading message content (server never holds keys)
+- Server breach exposing message content (only ciphertext stored)
+- Legal compulsion to produce message content (server has nothing to produce)
+- Person with physical device access seeing conversation content
+
+### Does NOT protect against
+
+- Government subpoena for metadata (who talked to whom, when)
+- Nation-state network surveillance
+- The counterparty sharing decrypted content
+- Screen photography
+- A PIN brute-force attack on a stolen device (mitigated by lockout)
+- Compromise of the user's Google account (authentication layer)
+
+---
+
+## Reporting vulnerabilities
+
+**Please do not open a public issue for security vulnerabilities.**
+
+Email: security@voidlogue.com
+
+We will acknowledge within 48 hours and aim to resolve critical issues within
+7 days. We will credit researchers in release notes unless anonymity is
+requested.
+
+## Scope
+
+In scope:
+- Cryptographic implementation errors in this package
+- Key derivation weaknesses
+- Randomness or bias issues in `secureRandom()`
+- Any input that allows recovery of plaintext without the correct key
+
+Out of scope:
+- Social engineering attacks
+- Physical device access attacks
+- Issues in the server-side code (not in this repo)
+- Theoretical weaknesses in AES-256-GCM or PBKDF2 as standardised algorithms

package/index.js

@@ -0,0 +1,13 @@
+/**
+ * voidlogue-crypto — Voidlogue Client-Side Cryptography
+ *
+ * Open-source cryptographic layer for independent audit and verification.
+ * Published so that the privacy claims made at voidlogue.com can be verified
+ * against the actual code running in the browser.
+ *
+ * @module voidlogue-crypto
+ */
+
+export { VoidShield, generateCodename } from "./src/voidshield.js";
+export { Vault, LabelCipher } from "./src/vault.js";
+export { EFF_WORDLIST } from "./src/eff_wordlist.js";

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "voidlogue-crypto",
+  "version": "1.0.0",
+  "description": "Open-source client-side cryptographic primitives for Voidlogue — published for independent audit and verification of privacy claims.",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./voidshield": "./src/voidshield.js",
+    "./vault": "./src/vault.js",
+    "./eff_wordlist": "./src/eff_wordlist.js"
+  },
+  "files": [
+    "src/",
+    "index.js",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "encryption",
+    "privacy",
+    "ephemeral",
+    "messaging",
+    "aes-gcm",
+    "pbkdf2",
+    "web-crypto",
+    "voidlogue",
+    "e2e",
+    "zero-knowledge"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voidlogue/voidlogue-crypto.git"
+  },
+  "homepage": "https://voidlogue.com",
+  "bugs": {
+    "url": "https://github.com/voidlogue/voidlogue-crypto/issues",
+    "email": "security@voidlogue.com"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^1.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}