@byearlybird/crypto 0.0.1

package/README.md

@@ -0,0 +1,218 @@
+# @byearlybird/crypto
+
+Lightweight E2EE toolkit for web applications. Zero dependencies, Web Crypto API only.
+
+## Installation
+
+```bash
+npm install @byearlybird/crypto
+```
+
+## Quick Start
+
+### Registration
+
+```typescript
+import { generateKeys, encryptData } from '@byearlybird/crypto';
+
+// Generate all keys at once
+const { vaultKey, masterKey, encryptedMasterKey } = await generateKeys();
+
+// Show vault key to user (they must save it!)
+console.log('Save this vault key:', vaultKey);
+
+// Encrypt user data
+const encrypted = await encryptData(JSON.stringify({ secret: 'data' }), masterKey);
+
+// Store on server: encryptedMasterKey + encrypted data
+await saveToServer({ encryptedMasterKey, data: encrypted });
+```
+
+### Login
+
+```typescript
+import { decryptMasterKey, decryptData } from '@byearlybird/crypto';
+
+// User provides their vault key
+const vaultKey = getUserInput();
+
+// Fetch from server
+const { encryptedMasterKey, data } = await fetchFromServer();
+
+// Decrypt master key, then decrypt data
+const masterKey = await decryptMasterKey(encryptedMasterKey, vaultKey);
+const decrypted = await decryptData(data, masterKey);
+```
+
+## API Reference
+
+### `generateKeys()`
+```typescript
+function generateKeys(): Promise<{
+  vaultKey: string;
+  masterKey: CryptoKey;
+  encryptedMasterKey: string;
+}>
+```
+
+Generates vault key, master key, and encrypted master key in one call. Convenience method for new users.
+
+---
+
+### `generateVaultKey()`
+```typescript
+function generateVaultKey(): string
+```
+
+Generates a random 256-bit vault key (64-char hex string). User must save this.
+
+---
+
+### `generateMasterKey()`
+```typescript
+function generateMasterKey(): Promise<CryptoKey>
+```
+
+Generates a random AES-256-GCM master key for encrypting data.
+
+---
+
+### `encryptMasterKey(masterKey, vaultKey)`
+```typescript
+function encryptMasterKey(
+  masterKey: CryptoKey,
+  vaultKey: string
+): Promise<string>
+```
+
+Encrypts master key with vault key using PBKDF2 (600k iterations). Returns base64 payload (salt + IV + ciphertext).
+
+---
+
+### `decryptMasterKey(encryptedMasterKey, vaultKey)`
+```typescript
+function decryptMasterKey(
+  encryptedMasterKey: string,
+  vaultKey: string
+): Promise<CryptoKey>
+```
+
+Decrypts encrypted master key. Throws if vault key is wrong or data is corrupted.
+
+---
+
+### `encryptData(data, masterKey)`
+```typescript
+function encryptData(
+  data: string,
+  masterKey: CryptoKey
+): Promise<string>
+```
+
+Encrypts data with master key. Returns base64 payload (IV + ciphertext). Fresh random IV per call.
+
+---
+
+### `decryptData(encryptedData, masterKey)`
+```typescript
+function decryptData(
+  encryptedData: string,
+  masterKey: CryptoKey
+): Promise<string>
+```
+
+Decrypts data. Throws if key is wrong or data is tampered with (GCM authentication).
+
+---
+
+### `deriveEncryptionKey(vaultKey, salt?)`
+```typescript
+function deriveEncryptionKey(
+  vaultKey: string,
+  salt?: Uint8Array
+): Promise<{ key: CryptoKey; salt: Uint8Array }>
+```
+
+Low-level PBKDF2 key derivation. Used internally by `encryptMasterKey`/`decryptMasterKey`.
+
+---
+
+### `hash(data)`
+```typescript
+function hash(data: string): Promise<string>
+```
+
+Computes SHA-256 hash of a string. Returns hex-encoded digest (64 chars).
+
+---
+
+### `hashObject(obj)`
+```typescript
+function hashObject(obj: unknown): Promise<string>
+```
+
+Computes SHA-256 hash of a JSON-serializable object. Returns hex-encoded digest (64 chars). Objects must be JSON serializable. Property order is normalized for consistent hashing.
+
+## Security
+
+**Cryptographic primitives:**
+- AES-256-GCM (authenticated encryption)
+- PBKDF2-SHA256 (600k iterations, OWASP 2023)
+- SHA-256 (content hashing)
+- 128-bit salts, 96-bit IVs
+- `crypto.getRandomValues()` for all randomness
+
+**E2EE model:**
+- All encryption happens client-side
+- Server only sees ciphertext
+- Vault key never leaves client
+- Fresh IV per encryption (no reuse)
+- Self-contained ciphertexts (IVs and salts embedded)
+
+**Important:**
+- Users must save vault keys securely (no recovery if lost)
+- Use HTTPS to prevent code injection
+- GCM authentication detects tampering
+- Vault keys are case-insensitive (normalized to lowercase)
+
+## Examples
+
+### Password Change
+
+```typescript
+// Re-encrypt master key with new vault key
+const masterKey = await decryptMasterKey(encrypted, oldVaultKey);
+const newEncrypted = await encryptMasterKey(masterKey, newVaultKey);
+// Update on server (user data doesn't need re-encryption)
+```
+
+### Multiple Items
+
+```typescript
+const masterKey = await generateMasterKey();
+const items = ['item1', 'item2', 'item3'];
+const encrypted = await Promise.all(
+  items.map(item => encryptData(item, masterKey))
+);
+// Each has different ciphertext (fresh IV)
+```
+
+### Hashing
+
+```typescript
+import { hash, hashObject } from '@byearlybird/crypto';
+
+// Hash a string
+const digest = await hash('hello world');
+
+// Hash an object (must be JSON serializable)
+const objHash = await hashObject({ user: 'alice', id: 123 });
+```
+
+## Browser Compatibility
+
+Requires Web Crypto API (Chrome 37+, Firefox 34+, Safari 11+, all modern mobile browsers).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,25 @@
+//#region src/encryption.d.ts
+declare function encryptData(data: string, masterKey: CryptoKey): Promise<string>;
+declare function decryptData(encryptedData: string, masterKey: CryptoKey): Promise<string>;
+//#endregion
+//#region src/hash.d.ts
+declare function hash(data: string): Promise<string>;
+declare function hashObject(obj: unknown): Promise<string>;
+//#endregion
+//#region src/keys.d.ts
+type DerivedKeyResult = {
+  key: CryptoKey;
+  salt: Uint8Array;
+};
+declare function generateVaultKey(): string;
+declare function generateMasterKey(): Promise<CryptoKey>;
+declare function deriveEncryptionKey(vaultKey: string, salt?: Uint8Array): Promise<DerivedKeyResult>;
+declare function encryptMasterKey(masterKey: CryptoKey, vaultKey: string): Promise<string>;
+declare function decryptMasterKey(encryptedMasterKey: string, vaultKey: string): Promise<CryptoKey>;
+declare function generateKeys(): Promise<{
+  vaultKey: string;
+  masterKey: CryptoKey;
+  encryptedMasterKey: string;
+}>;
+//#endregion
+export { decryptData, decryptMasterKey, deriveEncryptionKey, encryptData, encryptMasterKey, generateKeys, generateMasterKey, generateVaultKey, hash, hashObject };

package/dist/index.mjs

@@ -0,0 +1,140 @@
+//#region src/crypto-utils.ts
+function randomBytes(length) {
+	const bytes = new Uint8Array(length);
+	crypto.getRandomValues(bytes);
+	return bytes;
+}
+function concatBytes(...chunks) {
+	const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+	const result = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		result.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return result;
+}
+function toBase64(bytes) {
+	return btoa(String.fromCharCode(...bytes));
+}
+function fromBase64(value) {
+	return Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
+}
+
+//#endregion
+//#region src/encryption.ts
+const IV_LENGTH$1 = 12;
+async function encryptData(data, masterKey) {
+	const iv = randomBytes(IV_LENGTH$1);
+	const encrypted = await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv
+	}, masterKey, new TextEncoder().encode(data));
+	return toBase64(concatBytes(iv, new Uint8Array(encrypted)));
+}
+async function decryptData(encryptedData, masterKey) {
+	const combined = fromBase64(encryptedData);
+	if (combined.length <= IV_LENGTH$1) throw new Error("Invalid encrypted data payload");
+	const iv = combined.slice(0, IV_LENGTH$1);
+	const encrypted = combined.slice(IV_LENGTH$1);
+	const decrypted = await crypto.subtle.decrypt({
+		name: "AES-GCM",
+		iv
+	}, masterKey, encrypted);
+	return new TextDecoder().decode(decrypted);
+}
+
+//#endregion
+//#region src/hash.ts
+async function hash(data) {
+	const dataBytes = new TextEncoder().encode(data);
+	const hashBuffer = await crypto.subtle.digest("SHA-256", dataBytes);
+	return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function hashObject(obj) {
+	const canonical = JSON.stringify(normalize(obj));
+	if (canonical === void 0) throw new TypeError("hashObject only supports JSON-serializable values");
+	return hash(canonical);
+}
+function normalize(value) {
+	if (Array.isArray(value)) return value.map((item) => normalize(item));
+	if (value && typeof value === "object") {
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype === Object.prototype || prototype === null) {
+			const sortedKeys = Object.keys(value).sort();
+			const result = {};
+			for (const key of sortedKeys) result[key] = normalize(value[key]);
+			return result;
+		}
+	}
+	return value;
+}
+
+//#endregion
+//#region src/keys.ts
+const PBKDF2_ITERATIONS = 6e5;
+const PBKDF2_SALT_LENGTH = 16;
+const VAULT_KEY_LENGTH = 32;
+const IV_LENGTH = 12;
+function generateVaultKey() {
+	return [...randomBytes(VAULT_KEY_LENGTH)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function generateMasterKey() {
+	return crypto.subtle.generateKey({
+		name: "AES-GCM",
+		length: 256
+	}, true, ["encrypt", "decrypt"]);
+}
+async function deriveEncryptionKey(vaultKey, salt) {
+	const normalizedKey = vaultKey.toLowerCase();
+	const encoder = new TextEncoder();
+	const keyMaterial = await crypto.subtle.importKey("raw", encoder.encode(normalizedKey), { name: "PBKDF2" }, false, ["deriveKey"]);
+	const saltBytes = salt ? new Uint8Array(salt) : randomBytes(PBKDF2_SALT_LENGTH);
+	return {
+		key: await crypto.subtle.deriveKey({
+			name: "PBKDF2",
+			salt: saltBytes,
+			iterations: PBKDF2_ITERATIONS,
+			hash: "SHA-256"
+		}, keyMaterial, {
+			name: "AES-GCM",
+			length: 256
+		}, true, ["encrypt", "decrypt"]),
+		salt: saltBytes
+	};
+}
+async function encryptMasterKey(masterKey, vaultKey) {
+	const masterKeyBytes = await crypto.subtle.exportKey("raw", masterKey);
+	const { key: encryptionKey, salt } = await deriveEncryptionKey(vaultKey);
+	const iv = randomBytes(IV_LENGTH);
+	const encrypted = await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv
+	}, encryptionKey, masterKeyBytes);
+	return toBase64(concatBytes(salt, iv, new Uint8Array(encrypted)));
+}
+async function decryptMasterKey(encryptedMasterKey, vaultKey) {
+	const combined = fromBase64(encryptedMasterKey);
+	if (combined.length <= PBKDF2_SALT_LENGTH + IV_LENGTH) throw new Error("Invalid encrypted master key payload");
+	const salt = combined.slice(0, PBKDF2_SALT_LENGTH);
+	const iv = combined.slice(PBKDF2_SALT_LENGTH, PBKDF2_SALT_LENGTH + IV_LENGTH);
+	const encrypted = combined.slice(PBKDF2_SALT_LENGTH + IV_LENGTH);
+	const { key: encryptionKey } = await deriveEncryptionKey(vaultKey, salt);
+	const decrypted = await crypto.subtle.decrypt({
+		name: "AES-GCM",
+		iv
+	}, encryptionKey, encrypted);
+	return crypto.subtle.importKey("raw", decrypted, { name: "AES-GCM" }, true, ["encrypt", "decrypt"]);
+}
+async function generateKeys() {
+	const vaultKey = generateVaultKey();
+	const masterKey = await generateMasterKey();
+	return {
+		vaultKey,
+		masterKey,
+		encryptedMasterKey: await encryptMasterKey(masterKey, vaultKey)
+	};
+}
+
+//#endregion
+export { decryptData, decryptMasterKey, deriveEncryptionKey, encryptData, encryptMasterKey, generateKeys, generateMasterKey, generateVaultKey, hash, hashObject };

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@byearlybird/crypto",
+	"version": "0.0.1",
+	"description": "Lightweight E2EE toolkit for web apps - zero dependencies + vault key security",
+	"type": "module",
+	"license": "MIT",
+	"main": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs",
+			"default": "./dist/index.mjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "bun run build.ts",
+		"prepublishOnly": "bun run build.ts",
+		"patch": "bun pm patch",
+		"minor": "bun pm minor",
+		"publish": "bun pm publish"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.3.5",
+		"@types/bun": "latest",
+		"tsdown": "^0.16.1"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}