@byearlybird/crypto 0.1.0 → 0.2.0

package/README.md

@@ -10,208 +10,263 @@ npm install @byearlybird/crypto
 
 ## Quick Start
 
-### Registration
+### Encrypt & Decrypt Data
 
 ```typescript
-import { generateKeys, encryptData } from '@byearlybird/crypto';
+import { generateEncryptionKey, encrypt, decrypt } from '@byearlybird/crypto';
 
-// Generate all keys at once
-const { vaultKey, masterKey, encryptedMasterKey } = await generateKeys();
+const key = await generateEncryptionKey();
 
-// 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 });
+const ciphertext = await encrypt('secret data', key);
+const plaintext = await decrypt(ciphertext, key);
 ```
 
-### Login
+### Sign & Verify Messages
 
 ```typescript
-import { decryptMasterKey, decryptData } from '@byearlybird/crypto';
+import { generateSigningKeyPair, sign, verify, exportPublicKey } from '@byearlybird/crypto';
 
-// User provides their vault key
-const vaultKey = getUserInput();
+const { publicKey, privateKey } = await generateSigningKeyPair(true);
 
-// Fetch from server
-const { encryptedMasterKey, data } = await fetchFromServer();
+const signature = await sign('hello', privateKey);
+const valid = await verify('hello', signature, publicKey);
+```
 
-// Decrypt master key, then decrypt data
-const masterKey = await decryptMasterKey(encryptedMasterKey, vaultKey);
-const decrypted = await decryptData(data, masterKey);
+### Signature-Based Auth (eba1)
+
+```typescript
+import {
+  generateSigningKeyPair,
+  exportPublicKey,
+  deriveVaultId,
+  createAuthHeader,
+  verifyAuthHeader,
+} from '@byearlybird/crypto';
+
+const { publicKey, privateKey } = await generateSigningKeyPair(true);
+const pubB64 = await exportPublicKey(publicKey);
+const vaultId = await deriveVaultId(pubB64);
+
+// Client: create a signed auth header
+const header = await createAuthHeader({
+  vaultId,
+  method: 'POST',
+  pathWithQuery: '/api/data?page=1',
+  serializedBody: JSON.stringify({ hello: 'world' }),
+  privateKey,
+});
+// header: "eba1 vid=...;n=...;m=POST;p=/api/data?page=1;t=...;sig=...;bh=..."
+
+// Server: verify the header
+const valid = await verifyAuthHeader(header, publicKey);
 ```
 
 ## API Reference
 
-### `generateKeys()`
+### Encryption Keys
+
+#### `generateEncryptionKey(extractable?)`
 ```typescript
-function generateKeys(): Promise<{
-  vaultKey: string;
-  masterKey: CryptoKey;
-  encryptedMasterKey: string;
-}>
+function generateEncryptionKey(extractable?: boolean): Promise<CryptoKey>
 ```
+Generates a random AES-256-GCM encryption key. `extractable` defaults to `false`.
 
-Generates vault key, master key, and encrypted master key in one call. Convenience method for new users.
+---
+
+#### `exportEncryptionKey(key)`
+```typescript
+function exportEncryptionKey(key: CryptoKey): Promise<string>
+```
+Exports an encryption key to a base64 string (raw format).
 
 ---
 
-### `generateVaultKey()`
+#### `importEncryptionKey(base64, extractable?)`
 ```typescript
-function generateVaultKey(): string
+function importEncryptionKey(base64: string, extractable?: boolean): Promise<CryptoKey>
 ```
+Imports a base64-encoded encryption key. `extractable` defaults to `false`.
+
+---
 
-Generates a random 256-bit vault key (64-char hex string). User must save this.
+#### `encrypt(plaintext, key)`
+```typescript
+function encrypt(plaintext: string, key: CryptoKey): Promise<string>
+```
+Encrypts a string with AES-256-GCM. Returns base64 payload (12-byte IV + ciphertext). Fresh random IV per call.
 
 ---
 
-### `generateMasterKey()`
+#### `decrypt(encoded, key)`
 ```typescript
-function generateMasterKey(): Promise<CryptoKey>
+function decrypt(encoded: string, key: CryptoKey): Promise<string>
 ```
+Decrypts an AES-256-GCM encrypted payload. Throws if the key is wrong or data is tampered with.
+
+---
 
-Generates a random AES-256-GCM master key for encrypting data.
+### Signing Keys
+
+#### `generateSigningKeyPair(extractable?)`
+```typescript
+function generateSigningKeyPair(extractable?: boolean): Promise<CryptoKeyPair>
+```
+Generates an Ed25519 signing key pair. `extractable` defaults to `false`.
 
 ---
 
-### `encryptMasterKey(masterKey, vaultKey)`
+#### `exportPublicKey(key)`
 ```typescript
-function encryptMasterKey(
-  masterKey: CryptoKey,
-  vaultKey: string
-): Promise<string>
+function exportPublicKey(key: CryptoKey): Promise<string>
 ```
+Exports a public key to base64 (SPKI format).
+
+---
 
-Encrypts master key with vault key using PBKDF2 (600k iterations). Returns base64 payload (salt + IV + ciphertext).
+#### `importPublicKey(spkiB64, extractable?)`
+```typescript
+function importPublicKey(spkiB64: string, extractable?: boolean): Promise<CryptoKey>
+```
+Imports a base64-encoded SPKI public key. `extractable` defaults to `false`.
 
 ---
 
-### `decryptMasterKey(encryptedMasterKey, vaultKey)`
+#### `exportPrivateKey(key)`
 ```typescript
-function decryptMasterKey(
-  encryptedMasterKey: string,
-  vaultKey: string
-): Promise<CryptoKey>
+function exportPrivateKey(key: CryptoKey): Promise<string>
 ```
+Exports a private key to base64 (PKCS8 format).
+
+---
 
-Decrypts encrypted master key. Throws if vault key is wrong or data is corrupted.
+#### `importPrivateKey(pkcs8B64, extractable?)`
+```typescript
+function importPrivateKey(pkcs8B64: string, extractable?: boolean): Promise<CryptoKey>
+```
+Imports a base64-encoded PKCS8 private key. `extractable` defaults to `false`.
 
 ---
 
-### `encryptData(data, masterKey)`
+#### `sign(message, privateKey)`
 ```typescript
-function encryptData(
-  data: string,
-  masterKey: CryptoKey
-): Promise<string>
+function sign(message: string, privateKey: CryptoKey): Promise<string>
 ```
+Signs a message using Ed25519. Returns a base64-encoded signature.
+
+---
 
-Encrypts data with master key. Returns base64 payload (IV + ciphertext). Fresh random IV per call.
+#### `verify(message, signatureB64, publicKey)`
+```typescript
+function verify(message: string, signatureB64: string, publicKey: CryptoKey): Promise<boolean>
+```
+Verifies an Ed25519 signature. Returns `true` if valid, `false` otherwise.
 
 ---
 
-### `decryptData(encryptedData, masterKey)`
+### Authentication (eba1)
+
+#### `AuthPayload`
 ```typescript
-function decryptData(
-  encryptedData: string,
-  masterKey: CryptoKey
-): Promise<string>
+type AuthPayload = {
+  scheme: string;
+  nonce: string;
+  vaultId: string;
+  method: string;
+  pathWithQuery: string;
+  timestamp: number;
+  bodyHash?: string;
+}
 ```
 
-Decrypts data. Throws if key is wrong or data is tampered with (GCM authentication).
+---
+
+#### `deriveVaultId(publicKeyB64)`
+```typescript
+function deriveVaultId(publicKeyB64: string): Promise<string>
+```
+Derives a 32-character hex vault ID from a base64-encoded public key (SHA-256 of SPKI bytes, truncated).
 
 ---
 
-### `deriveEncryptionKey(vaultKey, salt?)`
+#### `parseAuthHeader(header)`
 ```typescript
-function deriveEncryptionKey(
-  vaultKey: string,
-  salt?: Uint8Array
-): Promise<{ key: CryptoKey; salt: Uint8Array }>
+function parseAuthHeader(header: string): AuthPayload & { signature: string }
 ```
+Parses an eba1 auth header string back into its components. Throws on malformed or unsupported headers.
 
-Low-level PBKDF2 key derivation. Used internally by `encryptMasterKey`/`decryptMasterKey`.
+---
+
+#### `createAuthHeader(args)`
+```typescript
+function createAuthHeader(args: {
+  vaultId: string;
+  method: 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE';
+  pathWithQuery: string;
+  serializedBody?: string;
+  privateKey: CryptoKey;
+}): Promise<string>
+```
+Creates a complete signed auth header. Generates a nonce/timestamp, hashes the body if provided, signs the canonical string, and returns the formatted header.
 
 ---
 
-### `hash(data)`
+#### `verifyAuthHeader(header, publicKey)`
 ```typescript
-function hash(data: string): Promise<string>
+function verifyAuthHeader(header: string, publicKey: CryptoKey): Promise<boolean>
 ```
+Verifies an eba1 auth header against a public key. Parses the header, reconstructs the canonical string, and verifies the signature. Returns `true` if valid.
 
-Computes SHA-256 hash of a string. Returns hex-encoded digest (64 chars).
+---
+
+### Utilities
+
+#### `bytesToBase64(bytes)`
+```typescript
+function bytesToBase64(bytes: Uint8Array): string
+```
+Converts a byte array to a base64 string.
 
 ---
 
-### `hashObject(obj)`
+#### `base64ToBytes(base64)`
 ```typescript
-function hashObject(obj: unknown): Promise<string>
+function base64ToBytes(base64: string): Uint8Array
 ```
+Converts a base64 string to a byte array.
 
-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.
+---
+
+#### `hashString(value)`
+```typescript
+function hashString(value: string): Promise<string>
+```
+Computes SHA-256 hash of a string. Returns hex-encoded digest (64 chars).
 
 ## Security
 
 **Cryptographic primitives:**
 - AES-256-GCM (authenticated encryption)
-- PBKDF2-SHA256 (600k iterations, OWASP 2023)
+- Ed25519 (digital signatures)
 - SHA-256 (content hashing)
-- 128-bit salts, 96-bit IVs
+- 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
+- Self-contained ciphertexts (IVs embedded)
 - 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 });
-```
+**Signature-based auth:**
+- Ed25519 key pairs for request signing
+- Nonce + timestamp prevent replay attacks
+- Optional body hash ensures payload integrity
+- Canonical string format for deterministic signing
 
 ## Browser Compatibility
 
-Requires Web Crypto API (Chrome 37+, Firefox 34+, Safari 11+, all modern mobile browsers).
+Requires Web Crypto API and Ed25519 support (Chrome 113+, Firefox 130+, Safari 17+).
 
 ## License
 

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as crypto0 from "crypto";
 
-//#region src/eb-auth.d.ts
+//#region src/auth.d.ts
 type AuthPayload = {
   scheme: string;
   nonce: string;
@@ -11,26 +11,26 @@ type AuthPayload = {
   bodyHash?: string;
 };
 declare function deriveVaultId(publicKeyB64: string): Promise<string>;
-declare function generateAuthPayload(args: {
+declare function createAuthHeader(args: {
   vaultId: string;
   method: "GET" | "PUT" | "POST" | "PATCH" | "DELETE";
   pathWithQuery: string;
   serializedBody?: string;
-}): Promise<AuthPayload>;
-declare function makeCanonicalString(payload: AuthPayload): string;
-declare function makeAuthHeader(payload: AuthPayload, signature: string): string;
+  privateKey: CryptoKey;
+}): Promise<string>;
 declare function parseAuthHeader(header: string): AuthPayload & {
   signature: string;
 };
+declare function verifyAuthHeader(header: string, publicKey: CryptoKey): Promise<boolean>;
 //#endregion
-//#region src/encryption-keys.d.ts
+//#region src/encryption.d.ts
 declare function generateEncryptionKey(extractable?: boolean): Promise<crypto0.webcrypto.CryptoKey>;
 declare function exportEncryptionKey(key: CryptoKey): Promise<string>;
 declare function importEncryptionKey(base64: string, extractable?: boolean): Promise<crypto0.webcrypto.CryptoKey>;
 declare function encrypt(plaintext: string, key: CryptoKey): Promise<string>;
 declare function decrypt(encoded: string, key: CryptoKey): Promise<string>;
 //#endregion
-//#region src/signing-keys.d.ts
+//#region src/signing.d.ts
 declare function generateSigningKeyPair(extractable?: boolean): Promise<CryptoKeyPair>;
 declare function exportPublicKey(key: CryptoKey): Promise<string>;
 declare function importPublicKey(spkiB64: string, extractable?: boolean): Promise<CryptoKey>;
@@ -44,4 +44,4 @@ declare function bytesToBase64(bytes: Uint8Array): string;
 declare function base64ToBytes(base64: string): Uint8Array;
 declare function hashString(value: string): Promise<string>;
 //#endregion
-export { AuthPayload, base64ToBytes, bytesToBase64, decrypt, deriveVaultId, encrypt, exportEncryptionKey, exportPrivateKey, exportPublicKey, generateAuthPayload, generateEncryptionKey, generateSigningKeyPair, hashString, importEncryptionKey, importPrivateKey, importPublicKey, makeAuthHeader, makeCanonicalString, parseAuthHeader, sign, verify };
+export { AuthPayload, base64ToBytes, bytesToBase64, createAuthHeader, decrypt, deriveVaultId, encrypt, exportEncryptionKey, exportPrivateKey, exportPublicKey, generateEncryptionKey, generateSigningKeyPair, hashString, importEncryptionKey, importPrivateKey, importPublicKey, parseAuthHeader, sign, verify, verifyAuthHeader };

package/dist/index.mjs

@@ -1,3 +1,34 @@
+//#region src/signing.ts
+async function generateSigningKeyPair(extractable = false) {
+	return crypto.subtle.generateKey("Ed25519", extractable, ["sign", "verify"]);
+}
+async function exportPublicKey(key) {
+	const spki = await crypto.subtle.exportKey("spki", key);
+	return Buffer.from(spki).toString("base64");
+}
+async function importPublicKey(spkiB64, extractable = false) {
+	const spkiDer = Buffer.from(spkiB64, "base64");
+	return await crypto.subtle.importKey("spki", spkiDer, "Ed25519", extractable, ["verify"]);
+}
+async function exportPrivateKey(key) {
+	const pkcs8 = await crypto.subtle.exportKey("pkcs8", key);
+	return Buffer.from(pkcs8).toString("base64");
+}
+async function importPrivateKey(pkcs8B64, extractable = false) {
+	return await crypto.subtle.importKey("pkcs8", Buffer.from(pkcs8B64, "base64"), "Ed25519", extractable, ["sign"]);
+}
+async function sign(message, privateKey) {
+	const data = new TextEncoder().encode(message);
+	const signature = await crypto.subtle.sign("Ed25519", privateKey, data);
+	return Buffer.from(signature).toString("base64");
+}
+async function verify(message, signatureB64, publicKey) {
+	const data = new TextEncoder().encode(message);
+	const signature = Buffer.from(signatureB64, "base64");
+	return crypto.subtle.verify("Ed25519", publicKey, signature, data);
+}
+
+//#endregion
 //#region src/utils.ts
 function bytesToBase64(bytes) {
 	return Buffer.from(bytes).toString("base64");
@@ -11,13 +42,56 @@ async function hashString(value) {
 }
 
 //#endregion
-//#region src/eb-auth.ts
-const CURRENT_SCHEME = "eb1";
+//#region src/auth.ts
+const CURRENT_SCHEME = "eba1";
 async function deriveVaultId(publicKeyB64) {
 	const spkiBytes = Buffer.from(publicKeyB64, "base64");
 	const hash = await crypto.subtle.digest("SHA-256", spkiBytes);
 	return Buffer.from(hash).toString("hex").slice(0, 32);
 }
+async function createAuthHeader(args) {
+	const { privateKey,...payloadArgs } = args;
+	const payload = await generateAuthPayload(payloadArgs);
+	return makeAuthHeader(payload, await sign(makeCanonicalString(payload), privateKey));
+}
+function parseAuthHeader(header) {
+	const spaceIdx = header.indexOf(" ");
+	if (spaceIdx === -1) throw new Error("Malformed auth header: missing scheme separator");
+	const scheme = header.slice(0, spaceIdx);
+	if (scheme !== CURRENT_SCHEME) throw new Error(`Unsupported auth scheme: ${scheme}`);
+	const paramStr = header.slice(spaceIdx + 1);
+	const params = /* @__PURE__ */ new Map();
+	for (const part of paramStr.split(";")) {
+		const eqIdx = part.indexOf("=");
+		if (eqIdx === -1) throw new Error(`Malformed auth header param: ${part}`);
+		params.set(part.slice(0, eqIdx), part.slice(eqIdx + 1));
+	}
+	const vid = params.get("vid");
+	const n = params.get("n");
+	const m = params.get("m");
+	const p = params.get("p");
+	const t = params.get("t");
+	const sig = params.get("sig");
+	if (!vid || !n || !m || !p || !t || !sig) throw new Error("Malformed auth header: missing required params");
+	const timestamp = Number(t);
+	if (Number.isNaN(timestamp)) throw new Error("Malformed auth header: timestamp is not a number");
+	const result = {
+		scheme,
+		vaultId: vid,
+		nonce: n,
+		method: m,
+		pathWithQuery: p,
+		timestamp,
+		signature: sig
+	};
+	const bh = params.get("bh");
+	if (bh) result.bodyHash = bh;
+	return result;
+}
+async function verifyAuthHeader(header, publicKey) {
+	const { signature,...payload } = parseAuthHeader(header);
+	return verify(makeCanonicalString(payload), signature, publicKey);
+}
 async function generateAuthPayload(args) {
 	const { serializedBody,...rest } = args;
 	const nonce = crypto.randomUUID();
@@ -55,43 +129,9 @@ function makeAuthHeader(payload, signature) {
 	if (payload.bodyHash) params.push(`bh=${payload.bodyHash}`);
 	return `${payload.scheme} ${params.join(";")}`;
 }
-function parseAuthHeader(header) {
-	const spaceIdx = header.indexOf(" ");
-	if (spaceIdx === -1) throw new Error("Malformed auth header: missing scheme separator");
-	const scheme = header.slice(0, spaceIdx);
-	if (scheme !== CURRENT_SCHEME) throw new Error(`Unsupported auth scheme: ${scheme}`);
-	const paramStr = header.slice(spaceIdx + 1);
-	const params = /* @__PURE__ */ new Map();
-	for (const part of paramStr.split(";")) {
-		const eqIdx = part.indexOf("=");
-		if (eqIdx === -1) throw new Error(`Malformed auth header param: ${part}`);
-		params.set(part.slice(0, eqIdx), part.slice(eqIdx + 1));
-	}
-	const vid = params.get("vid");
-	const n = params.get("n");
-	const m = params.get("m");
-	const p = params.get("p");
-	const t = params.get("t");
-	const sig = params.get("sig");
-	if (!vid || !n || !m || !p || !t || !sig) throw new Error("Malformed auth header: missing required params");
-	const timestamp = Number(t);
-	if (Number.isNaN(timestamp)) throw new Error("Malformed auth header: timestamp is not a number");
-	const result = {
-		scheme,
-		vaultId: vid,
-		nonce: n,
-		method: m,
-		pathWithQuery: p,
-		timestamp,
-		signature: sig
-	};
-	const bh = params.get("bh");
-	if (bh) result.bodyHash = bh;
-	return result;
-}
 
 //#endregion
-//#region src/encryption-keys.ts
+//#region src/encryption.ts
 async function generateEncryptionKey(extractable = false) {
 	return crypto.subtle.generateKey({
 		name: "AES-GCM",
@@ -128,35 +168,4 @@ async function decrypt(encoded, key) {
 }
 
 //#endregion
-//#region src/signing-keys.ts
-async function generateSigningKeyPair(extractable = false) {
-	return crypto.subtle.generateKey("Ed25519", extractable, ["sign", "verify"]);
-}
-async function exportPublicKey(key) {
-	const spki = await crypto.subtle.exportKey("spki", key);
-	return Buffer.from(spki).toString("base64");
-}
-async function importPublicKey(spkiB64, extractable = false) {
-	const spkiDer = Buffer.from(spkiB64, "base64");
-	return await crypto.subtle.importKey("spki", spkiDer, "Ed25519", extractable, ["verify"]);
-}
-async function exportPrivateKey(key) {
-	const pkcs8 = await crypto.subtle.exportKey("pkcs8", key);
-	return Buffer.from(pkcs8).toString("base64");
-}
-async function importPrivateKey(pkcs8B64, extractable = false) {
-	return await crypto.subtle.importKey("pkcs8", Buffer.from(pkcs8B64, "base64"), "Ed25519", extractable, ["sign"]);
-}
-async function sign(message, privateKey) {
-	const data = new TextEncoder().encode(message);
-	const signature = await crypto.subtle.sign("Ed25519", privateKey, data);
-	return Buffer.from(signature).toString("base64");
-}
-async function verify(message, signatureB64, publicKey) {
-	const data = new TextEncoder().encode(message);
-	const signature = Buffer.from(signatureB64, "base64");
-	return crypto.subtle.verify("Ed25519", publicKey, signature, data);
-}
-
-//#endregion
-export { base64ToBytes, bytesToBase64, decrypt, deriveVaultId, encrypt, exportEncryptionKey, exportPrivateKey, exportPublicKey, generateAuthPayload, generateEncryptionKey, generateSigningKeyPair, hashString, importEncryptionKey, importPrivateKey, importPublicKey, makeAuthHeader, makeCanonicalString, parseAuthHeader, sign, verify };
+export { base64ToBytes, bytesToBase64, createAuthHeader, decrypt, deriveVaultId, encrypt, exportEncryptionKey, exportPrivateKey, exportPublicKey, generateEncryptionKey, generateSigningKeyPair, hashString, importEncryptionKey, importPrivateKey, importPublicKey, parseAuthHeader, sign, verify, verifyAuthHeader };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@byearlybird/crypto",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Lightweight E2EE toolkit for web apps - zero dependencies + vault key security",
 	"type": "module",
 	"license": "MIT",