@codesense/conseal 0.1.6

package/README.md

@@ -0,0 +1,144 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+    <img src="docs/assets/logo-light.svg" width="64" height="64" alt="Conseal logo">
+  </picture>
+</p>
+
+<h1 align="center">Conseal</h1>
+
+<p align="center">
+  Browser-side zero-knowledge cryptography library.<br>
+  All crypto runs in the browser via <a href="https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto">SubtleCrypto</a> — the server never sees plaintext or key material.
+</p>
+
+---
+
+## Install
+
+```bash
+npm install conseal
+```
+
+## Quick start
+
+```ts
+import { seal, unseal, generateAesKey } from 'conseal'
+
+// Generate a key and encrypt
+const key = await generateAesKey()
+const plaintext = await file.arrayBuffer()
+const { ciphertext, iv } = await seal(key, plaintext)
+
+// Decrypt
+const result = await unseal(key, ciphertext, iv)
+```
+
+## API
+
+### Symmetric encryption (AES-256-GCM)
+
+| Function | Description |
+|---|---|
+| `seal(key, plaintext)` | Encrypts with a random 96-bit IV. Returns `{ ciphertext, iv }`. |
+| `unseal(key, ciphertext, iv)` | Decrypts. Throws on tampered data. |
+| `generateAesKey(extractable?)` | Generates a random AES-256 key. |
+| `importAesKey(raw, extractable?)` | Imports raw key bytes as a CryptoKey. |
+
+### Passphrase key wrapping (PBKDF2 + AES-KW)
+
+| Function | Description |
+|---|---|
+| `wrapKey(passphrase, key)` | Wraps a CryptoKey with a passphrase. Returns `{ wrappedKey, salt }`. |
+| `unwrapKey(passphrase, wrappedKey, salt)` | Unwraps. Throws on wrong passphrase. |
+| `rekey(oldPass, newPass, wrappedKey, salt)` | Changes passphrase without re-encrypting data. |
+
+### Asymmetric encryption (ECDH P-256)
+
+| Function | Description |
+|---|---|
+| `sealMessage(recipientPublicKey, plaintext)` | Encrypts for a recipient using ephemeral ECDH. |
+| `unsealMessage(privateKey, ciphertext, iv, ephemeralPublicKey)` | Decrypts with the recipient's private key. |
+| `generateECDHKeyPair()` | Generates a P-256 ECDH key pair. |
+
+### Digital signatures (ECDSA P-256)
+
+| Function | Description |
+|---|---|
+| `sign(privateKey, data)` | Signs data with ECDSA-SHA256. |
+| `verify(publicKey, signature, data)` | Verifies a signature. Returns `true` or `false`. |
+| `generateECDSAKeyPair()` | Generates a P-256 ECDSA key pair. |
+
+### Envelope encryption (passcode-protected)
+
+| Function | Description |
+|---|---|
+| `sealEnvelope(plaintext, passcode)` | Encrypts for a recipient without a Conseal account. |
+| `unsealEnvelope(envelope, passcode)` | Decrypts with the passcode. |
+| `encodeEnvelope(envelope)` | Serialises a `SealedEnvelope` to JSON. |
+| `decodeEnvelope(json)` | Deserialises JSON back to a `SealedEnvelope`. |
+
+### Device initialisation
+
+| Function | Description |
+|---|---|
+| `init(wrappedKey, salt, passphrase)` | Unwraps the AEK and stores it in IndexedDB. |
+| `AEK_KEY_ID` | The IndexedDB key id for the AEK (`'aek'`). |
+
+### Mnemonic recovery (BIP-39)
+
+| Function | Description |
+|---|---|
+| `generateMnemonic()` | Generates a 24-word recovery phrase. |
+| `recoverWithMnemonic(mnemonic)` | Derives the AEK from the mnemonic. |
+
+### Key serialisation (JWK)
+
+| Function | Description |
+|---|---|
+| `exportPublicKeyAsJwk(key)` | Exports a public CryptoKey to JWK. |
+| `importPublicKeyFromJwk(jwk, algorithm)` | Imports a JWK as a CryptoKey (`'ECDH'` or `'ECDSA'`). |
+
+### IndexedDB key storage
+
+```ts
+import { save, load, remove } from 'conseal/storage'
+```
+
+| Function | Description |
+|---|---|
+| `save(name, key)` | Persists a CryptoKey to IndexedDB. |
+| `load(name)` | Loads a CryptoKey. Returns `null` if not found. |
+| `remove(name)` | Deletes a CryptoKey. |
+
+### Utilities
+
+| Function | Description |
+|---|---|
+| `toBase64(buf)` / `fromBase64(b64)` | Standard base64 encoding/decoding. |
+| `toBase64Url(buf)` / `fromBase64Url(b64)` | URL-safe base64 (no padding). |
+| `digest(data)` | SHA-256 hash. |
+
+## Design
+
+- **Zero runtime secrets on the server.** All encryption and decryption happens in the browser. The server stores only wrapped keys and ciphertext.
+- **SubtleCrypto everywhere.** No OpenSSL, no polyfills, no WASM. The only runtime dependency is [`@scure/bip39`](https://github.com/nicolo-ribaudo/noble-bip39) for mnemonic wordlists (bundled into the output).
+- **Non-extractable keys.** Keys stored in IndexedDB have `extractable: false` — JavaScript cannot read the raw bytes, only use them for encrypt/decrypt.
+- **PBKDF2 at 600,000 iterations.** Passphrase-derived keys use SHA-256 with a 128-bit random salt per wrap. Intentionally slow to resist offline brute-force.
+
+## Requirements
+
+- Browser with [SubtleCrypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) support (all modern browsers)
+- Node.js >= 18 (for testing / SSR with `globalThis.crypto`)
+
+## Development
+
+```bash
+npm install
+npm test           # run tests
+npm run build      # build to dist/
+```
+
+## License
+
+Dual-licensed under [AGPL-3.0](LICENSE) and a [commercial license](COMMERCIAL-LICENSE.md).

package/dist/chunk-MDWFWP7Z.js

@@ -0,0 +1,63 @@
+// src/storage.ts
+var DB_NAME = "conseal-keys";
+var STORE = "keys";
+var VERSION = 1;
+function openDb() {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, VERSION);
+    req.onupgradeneeded = () => {
+      req.result.createObjectStore(STORE);
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+async function save(name, key) {
+  const db = await openDb();
+  try {
+    return await new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE, "readwrite");
+      tx.objectStore(STORE).put(key, name);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+}
+async function load(name) {
+  const db = await openDb();
+  try {
+    return await new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE, "readonly");
+      const req = tx.objectStore(STORE).get(name);
+      let result = null;
+      req.onsuccess = () => {
+        result = req.result ?? null;
+      };
+      tx.oncomplete = () => resolve(result);
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+}
+async function remove(name) {
+  const db = await openDb();
+  try {
+    return await new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE, "readwrite");
+      tx.objectStore(STORE).delete(name);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+}
+
+export {
+  save,
+  load,
+  remove
+};

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+export { load, remove, save } from './storage.js';
+
+/**
+ * AES-256-GCM symmetric encryption.
+ *
+ * seal()   encrypts an ArrayBuffer with a CryptoKey, returning ciphertext + a
+ *          random 96-bit IV. The 128-bit authentication tag is appended to the
+ *          ciphertext by SubtleCrypto automatically.
+ *
+ * unseal() decrypts ciphertext given the same key and IV. Throws if the
+ *          authentication tag fails — any tampering is detected.
+ *
+ * Callers convert File objects before passing in: await file.arrayBuffer()
+ */
+/** Encrypts plaintext with AES-256-GCM. Returns ciphertext (with auth tag appended) and IV. */
+declare function seal(key: CryptoKey, plaintext: ArrayBuffer): Promise<{
+    ciphertext: ArrayBuffer;
+    iv: Uint8Array;
+}>;
+/** Decrypts AES-256-GCM ciphertext. Throws if the auth tag check fails. */
+declare function unseal(key: CryptoKey, ciphertext: ArrayBuffer, iv: Uint8Array): Promise<ArrayBuffer>;
+/**
+ * Generates a random AES-256-GCM CryptoKey.
+ * Pass extractable: true when the key must be wrapped before storage (e.g. via wrapKey).
+ */
+declare function generateAesKey(extractable?: boolean): Promise<CryptoKey>;
+/**
+ * Imports raw key bytes as an AES-256-GCM CryptoKey.
+ * Pass extractable: true when the key must be wrapped before storage (e.g. via wrapKey).
+ */
+declare function importAesKey(raw: ArrayBuffer | Uint8Array, extractable?: boolean): Promise<CryptoKey>;
+
+/** Wraps a CryptoKey with a passphrase. The input key must have extractable: true. */
+declare function wrapKey(passphrase: string, key: CryptoKey): Promise<{
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}>;
+/** Unwraps a CryptoKey. Always returns extractable: false. */
+declare function unwrapKey(passphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array): Promise<CryptoKey>;
+/**
+ * Changes the passphrase protecting the AEK without re-encrypting any content.
+ * Internally unwraps with extractable: true so the key can be immediately re-wrapped.
+ */
+declare function rekey(oldPassphrase: string, newPassphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array): Promise<{
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}>;
+
+/** Generates a long-term ECDH P-256 key pair for an account identity. */
+declare function generateECDHKeyPair(): Promise<CryptoKeyPair>;
+/** Encrypts plaintext for a recipient. Only the recipient's private key can decrypt. */
+declare function sealMessage(recipientPublicKey: CryptoKey, plaintext: ArrayBuffer): Promise<{
+    ciphertext: ArrayBuffer;
+    iv: Uint8Array;
+    ephemeralPublicKey: JsonWebKey;
+}>;
+/** Decrypts a message sealed with the recipient's public key. */
+declare function unsealMessage(recipientPrivateKey: CryptoKey, ciphertext: ArrayBuffer, iv: Uint8Array, ephemeralPublicKey: JsonWebKey): Promise<ArrayBuffer>;
+
+/**
+ * ECDSA P-256 signing for sender verification.
+ *
+ * Provides cryptographic proof that a file or message came from the claimed sender.
+ * The sender signs with their private key; any recipient who has the sender's public
+ * key can verify the signature.
+ *
+ * sign()   produces a raw ECDSA signature over arbitrary data.
+ * verify() checks a signature against data using the signer's public key.
+ *          Returns true if valid, false if not — never throws on invalid signatures.
+ *
+ * Hash: SHA-256.
+ */
+/** Generates a long-term ECDSA P-256 key pair for an account identity. */
+declare function generateECDSAKeyPair(): Promise<CryptoKeyPair>;
+/** Signs data with the sender's ECDSA private key. */
+declare function sign(privateKey: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
+/** Verifies a signature against data using the sender's ECDSA public key. */
+declare function verify(publicKey: CryptoKey, signature: ArrayBuffer, data: ArrayBuffer): Promise<boolean>;
+
+/**
+ * JWK serialisation for public keys.
+ *
+ * exportPublicKeyAsJwk() serialises a CryptoKey to a JSON Web Key — used when
+ * registering a public key with the Conseal identity registry.
+ *
+ * importPublicKeyFromJwk() deserialises a JWK back to a CryptoKey — used when
+ * loading a recipient's public key before encrypting a message.
+ *
+ * Only public keys are exported. Private keys are never extracted.
+ */
+/** Serialises a public CryptoKey to a JSON Web Key object. */
+declare function exportPublicKeyAsJwk(key: CryptoKey): Promise<JsonWebKey>;
+/** Deserialises a JSON Web Key to a CryptoKey for the given algorithm. */
+declare function importPublicKeyFromJwk(jwk: JsonWebKey, algorithm: 'ECDH' | 'ECDSA'): Promise<CryptoKey>;
+
+/** The IndexedDB key id under which the AEK is stored after init(). */
+declare const AEK_KEY_ID = "aek";
+/**
+ * Unwraps the AEK with the given passphrase and stores it in IndexedDB.
+ * After this completes, the AEK is available via loadKey(AEK_KEY_ID).
+ */
+declare function init(wrappedKey: ArrayBuffer, salt: Uint8Array, passphrase: string): Promise<void>;
+
+/** Generates a fresh 24-word BIP-39 mnemonic (256 bits of entropy). */
+declare function generateMnemonic(): string;
+/**
+ * Derives a deterministic AES-256-GCM CryptoKey from a BIP-39 mnemonic.
+ * Throws if the mnemonic is invalid or not in the BIP-39 word list.
+ */
+declare function recoverWithMnemonic(mnemonic: string): Promise<CryptoKey>;
+
+/** Encrypts plaintext and wraps the key with a passcode, returning a SealedEnvelope. */
+declare function sealEnvelope(plaintext: ArrayBuffer, passcode: string): Promise<SealedEnvelope>;
+/** Decrypts a SealedEnvelope using the passcode. Throws if the passcode is wrong. */
+declare function unsealEnvelope(envelope: SealedEnvelope, passcode: string): Promise<ArrayBuffer>;
+/** The fields produced by sealEnvelope(), ready for JSON serialisation. */
+interface SealedEnvelope {
+    ciphertext: ArrayBuffer;
+    iv: Uint8Array;
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}
+/**
+ * Serialises a SealedEnvelope to a JSON string.
+ * Each binary field is base64-encoded. Safe to store server-side or pass over text channels.
+ */
+declare function encodeEnvelope(envelope: SealedEnvelope): string;
+/**
+ * Deserialises a JSON string produced by encodeEnvelope() back to a SealedEnvelope.
+ * Throws SyntaxError if the string is not valid JSON.
+ * Throws TypeError if required fields are missing or not strings.
+ */
+declare function decodeEnvelope(json: string): SealedEnvelope;
+
+/**
+ * Base64 encoding and decoding utilities.
+ *
+ * Helper functions for converting between binary data (ArrayBuffer / Uint8Array)
+ * and standard base64 strings — used when serialising encrypted payloads for
+ * storage or transmission over text-based channels.
+ *
+ * Two variants are provided:
+ *   toBase64 / fromBase64       — standard base64 (uses +, /, = padding)
+ *   toBase64Url / fromBase64Url — base64url (uses -, _, no padding; safe in URLs and JWKs)
+ */
+/**
+ * Encodes an ArrayBuffer or Uint8Array to a standard base64 string.
+ * Uses a loop instead of spread to avoid stack overflow on large buffers.
+ */
+declare function toBase64(buf: ArrayBuffer | Uint8Array): string;
+/** Decodes a standard base64 string to a Uint8Array. */
+declare function fromBase64(b64: string): Uint8Array;
+/**
+ * Encodes an ArrayBuffer or Uint8Array to a base64url string.
+ * Replaces + with -, / with _, and strips = padding.
+ * Used for JWK coordinates and URL-safe contexts.
+ */
+declare function toBase64Url(buf: ArrayBuffer | Uint8Array): string;
+/** Decodes a base64url string to a Uint8Array. */
+declare function fromBase64Url(b64url: string): Uint8Array;
+
+/**
+ * SHA-256 digest.
+ *
+ * Thin wrapper around SubtleCrypto.digest for the hash function used throughout
+ * this library — key fingerprinting, content hashing, and integrity checks.
+ */
+/** Returns the SHA-256 hash of the input data as an ArrayBuffer. */
+declare function digest(data: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>;
+
+export { AEK_KEY_ID, type SealedEnvelope, decodeEnvelope, digest, encodeEnvelope, exportPublicKeyAsJwk, fromBase64, fromBase64Url, generateAesKey, generateECDHKeyPair, generateECDSAKeyPair, generateMnemonic, importAesKey, importPublicKeyFromJwk, init, recoverWithMnemonic, rekey, seal, sealEnvelope, sealMessage, sign, toBase64, toBase64Url, unseal, unsealEnvelope, unsealMessage, unwrapKey, verify, wrapKey };