@codesense/conseal 0.3.2 → 0.4.0

package/README.md

@@ -8,8 +8,7 @@
 <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.
+  Zero-knowledge cryptography and private communication.
 </p>
 
 ---
@@ -78,6 +77,36 @@ const result = await unseal(key, ciphertext, iv)
 | `encodeEnvelope(envelope)` | Serialises a `SealedEnvelope` to JSON. |
 | `decodeEnvelope(json)` | Deserialises JSON back to a `SealedEnvelope`. |
 
+### Multi-device private communication (Circle)
+
+Establishes a bounded group of trusted devices that all hold the same Account Encryption Key (AEK). The mnemonic is the root of trust — the AEK is always derived from it, so any device can recover the AEK from the mnemonic alone if the passphrase or wrapped key is lost.
+
+Account creation flow:
+
+```ts
+const mnemonic = generateMnemonic()          // show to user — write it down, never store it
+const { wrappedAEK, aekCommitment, deviceId } = await initCircle(mnemonic, passphrase, secretKey)
+// store wrappedAEK + aekCommitment server-side
+```
+
+Recovery flow (lost passphrase or wrapped key):
+
+```ts
+const aek = await recoverWithMnemonic(mnemonic, true)  // re-derive AEK from mnemonic
+const { wrappedKey, salt } = await wrapKey(newPassphrase, aek, newSecretKey)
+// upload new wrappedKey to server
+```
+
+Four functions cover the full device-registration ceremony:
+
+| Function | Description |
+|---|---|
+| `initCircle(mnemonic, passphrase, secretKey)` | Founding device derives the shared AEK from the mnemonic, wraps it, and returns `wrappedAEK`, `aekCommitment`, and `deviceId`. |
+| `createJoinRequest(deviceMeta?)` | New device generates an ephemeral ECDH key pair. Returns the join request payload, the ephemeral private key (memory-only), and a `verificationCode` to display to the user. |
+| `authorizeJoin(joinRequest, wrappedAEK, passphrase, secretKey)` | Trusted device unwraps its AEK and seals it for the new device via ECDH. Rejects requests older than 5 minutes. |
+| `finalizeJoin(sealedAEK, ephemeralPrivateKey, passphrase, secretKey, aekCommitment)` | New device unseals the AEK, verifies the commitment, and re-wraps it under its own credentials. Throws on commitment mismatch. |
+| `deriveVerificationCode(ephemeralPublicKey)` | Derives a `XX-XX-XX` hex code from a public key. Both devices must show matching codes before approval to prevent MITM. |
+
 ### Device initialisation
 
 | Function | Description |
@@ -89,8 +118,8 @@ const result = await unseal(key, ciphertext, iv)
 
 | Function | Description |
 |---|---|
-| `generateMnemonic()` | Generates a 24-word recovery phrase. |
-| `recoverWithMnemonic(mnemonic)` | Derives the AEK from the mnemonic. |
+| `generateMnemonic()` | Generates a 24-word recovery phrase (256 bits of entropy). |
+| `recoverWithMnemonic(mnemonic, extractable?)` | Derives the AEK from the mnemonic. Pass `extractable: true` when passing to `initCircle` or `wrapKey`. |
 
 ### Key serialisation (JWK)
 

package/dist/index.d.ts

@@ -33,8 +33,12 @@ declare function wrapKey(passphrase: string, key: CryptoKey, secretKey?: Uint8Ar
     wrappedKey: ArrayBuffer;
     salt: Uint8Array;
 }>;
-/** Unwraps a CryptoKey. Always returns extractable: false. */
-declare function unwrapKey(passphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array, secretKey?: Uint8Array): Promise<CryptoKey>;
+/**
+ * Unwraps a CryptoKey. Returns extractable: false by default.
+ * Pass extractable: true only when the raw key bytes are needed for transfer
+ * (e.g. circle join ceremony) — export and discard as quickly as possible.
+ */
+declare function unwrapKey(passphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array, secretKey?: Uint8Array, extractable?: boolean): Promise<CryptoKey>;
 /**
  * Changes the passphrase protecting the AEK without re-encrypting any content.
  * The Secret Key (if any) stays the same — it is used on both the unwrap and re-wrap sides.
@@ -128,8 +132,11 @@ 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.
+ *
+ * Pass extractable: true when the key must be wrapped before storage —
+ * e.g. when passing it to initCircle().
  */
-declare function recoverWithMnemonic(mnemonic: string): Promise<CryptoKey>;
+declare function recoverWithMnemonic(mnemonic: string, extractable?: boolean): Promise<CryptoKey>;
 
 /** Encrypts plaintext and wraps the key with a passcode, returning a SealedEnvelope. */
 declare function sealEnvelope(plaintext: ArrayBuffer, passcode: string): Promise<SealedEnvelope>;
@@ -137,6 +144,8 @@ declare function sealEnvelope(plaintext: ArrayBuffer, passcode: string): Promise
 declare function unsealEnvelope(envelope: SealedEnvelope, passcode: string): Promise<ArrayBuffer>;
 /** The fields produced by sealEnvelope(), ready for JSON serialisation. */
 interface SealedEnvelope {
+    /** Format version — always 1 for envelopes produced by this library. */
+    version: 1;
     ciphertext: ArrayBuffer;
     iv: Uint8Array;
     wrappedKey: ArrayBuffer;
@@ -150,7 +159,7 @@ 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.
+ * Throws TypeError if required fields are missing, the wrong type, or the version is unsupported.
  */
 declare function decodeEnvelope(json: string): SealedEnvelope;
 
@@ -197,4 +206,103 @@ declare function loadCryptoKey(name: string): Promise<CryptoKey | null>;
 /** Removes a CryptoKey from IndexedDB. No-op if the name does not exist. */
 declare function deleteCryptoKey(name: string): Promise<void>;
 
-export { AEK_KEY_ID, type SealedEnvelope, combinePassphraseAndSecretKey, decodeEnvelope, deleteCryptoKey, digest, encodeEnvelope, exportPublicKeyAsJwk, fromBase64, fromBase64Url, generateAesKey, generateECDHKeyPair, generateECDSAKeyPair, generateMnemonic, generateSecretKey, importAesKey, importPublicKeyFromJwk, init, loadCryptoKey, recoverWithMnemonic, rekey, rekeySecretKey, saveCryptoKey, seal, sealEnvelope, sealMessage, sign, toBase64, toBase64Url, unseal, unsealEnvelope, unsealMessage, unwrapKey, verify, wrapKey };
+/** Wrapped AEK — opaque blob stored server-side per device. */
+interface WrappedAEK {
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}
+/** Serializable join request payload sent by a new device to the backend. */
+interface JoinRequest {
+    deviceId: string;
+    ephemeralPublicKey: JsonWebKey;
+    createdAt: string;
+    deviceMeta?: {
+        name?: string;
+        platform?: string;
+    };
+}
+/** AEK sealed for a specific device's ephemeral public key via ECDH. */
+interface SealedAEK {
+    ciphertext: ArrayBuffer;
+    iv: Uint8Array;
+    ephemeralPublicKey: JsonWebKey;
+}
+/**
+ * Derives a human-readable verification code from an ECDH public key JWK.
+ *
+ * Exports the key as its uncompressed point bytes (65 bytes for P-256),
+ * SHA-256 hashes them, and formats the first 3 bytes as uppercase hex pairs
+ * separated by dashes: e.g. "A3-K9-F2".
+ *
+ * Both the new device (createJoinRequest) and the authorizing device
+ * (authorizeJoin) call this with the same JWK and must get the same code.
+ * The user confirms the codes match out-of-band before approval proceeds.
+ */
+declare function deriveVerificationCode(ephemeralPublicKey: JsonWebKey): Promise<string>;
+/**
+ * Called once by the founding device when creating a new account.
+ *
+ * Derives the shared AEK from the mnemonic (so it can always be recovered),
+ * publishes its SHA-256 commitment (so joining devices can verify the AEK was
+ * not substituted), and wraps the AEK under the founding device's own
+ * passphrase + secretKey.
+ *
+ * The mnemonic is the root of trust — it must be shown to the user at account
+ * creation and never stored. The app stores wrappedAEK and aekCommitment on
+ * the server.
+ */
+declare function initCircle(mnemonic: string, passphrase: string, secretKey: Uint8Array): Promise<{
+    wrappedAEK: WrappedAEK;
+    aekCommitment: ArrayBuffer;
+    deviceId: string;
+}>;
+/**
+ * Called by a new device that wants to join the circle.
+ *
+ * Generates an ephemeral ECDH P-256 key pair for the one-time ceremony.
+ * The ephemeral private key is returned to the caller and must be held in
+ * memory only — never persisted — until finalizeJoin completes.
+ *
+ * The verification code is derived from the ephemeral public key and must
+ * be displayed prominently so the user can confirm it matches the code shown
+ * on the authorizing device.
+ */
+declare function createJoinRequest(deviceMeta?: {
+    name?: string;
+    platform?: string;
+}): Promise<{
+    request: JoinRequest;
+    ephemeralPrivateKey: CryptoKey;
+    verificationCode: string;
+}>;
+/**
+ * Called by a trusted device to approve a new device joining the circle.
+ *
+ * Rejects stale join requests (older than 5 minutes) regardless of server
+ * challenge state. The caller must present the verification code from
+ * joinRequest.ephemeralPublicKey and require explicit user confirmation that
+ * it matches the code on the new device before calling this function —
+ * calling without confirmation bypasses the primary MITM defence.
+ *
+ * Unwraps the AEK and seals its raw bytes for the new device's ephemeral
+ * public key via ECDH. Only the ephemeral private key held by the new device
+ * can open it.
+ */
+declare function authorizeJoin(joinRequest: JoinRequest, wrappedAEK: WrappedAEK, passphrase: string, secretKey: Uint8Array): Promise<SealedAEK>;
+/**
+ * Called by the new device after authorization.
+ *
+ * Unseals the AEK using the ephemeral private key generated in
+ * createJoinRequest, verifies it against aekCommitment (SHA-256 of the raw
+ * AEK published by initCircle), then re-wraps it under the new device's own
+ * passphrase + secretKey. The ephemeral private key is not needed after this
+ * call and should be discarded.
+ *
+ * Throws if the commitment check fails — the AEK was substituted or tampered
+ * with in transit. Do not use the returned wrappedAEK if this throws.
+ */
+declare function finalizeJoin(sealedAEK: SealedAEK, ephemeralPrivateKey: CryptoKey, passphrase: string, secretKey: Uint8Array, aekCommitment: ArrayBuffer): Promise<{
+    wrappedAEK: WrappedAEK;
+}>;
+
+export { AEK_KEY_ID, type JoinRequest, type SealedAEK, type SealedEnvelope, type WrappedAEK, authorizeJoin, combinePassphraseAndSecretKey, createJoinRequest, decodeEnvelope, deleteCryptoKey, deriveVerificationCode, digest, encodeEnvelope, exportPublicKeyAsJwk, finalizeJoin, fromBase64, fromBase64Url, generateAesKey, generateECDHKeyPair, generateECDSAKeyPair, generateMnemonic, generateSecretKey, importAesKey, importPublicKeyFromJwk, init, initCircle, loadCryptoKey, recoverWithMnemonic, rekey, rekeySecretKey, saveCryptoKey, seal, sealEnvelope, sealMessage, sign, toBase64, toBase64Url, unseal, unsealEnvelope, unsealMessage, unwrapKey, verify, wrapKey };

package/dist/index.js

@@ -105,10 +105,10 @@ async function wrapKey(passphrase, key, secretKey) {
   wrapped.set(new Uint8Array(ciphertext), IV_LENGTH);
   return { wrappedKey: wrapped.buffer, salt };
 }
-async function unwrapKey(passphrase, wrappedKey, salt, secretKey) {
+async function unwrapKey(passphrase, wrappedKey, salt, secretKey, extractable = false) {
   const effective = await resolvePassphrase(passphrase, secretKey);
   const wrappingKey = await deriveWrappingKey(effective, salt);
-  return decryptWrappedKey(wrappingKey, wrappedKey, false);
+  return decryptWrappedKey(wrappingKey, wrappedKey, extractable);
 }
 async function rekey(oldPassphrase, newPassphrase, wrappedKey, salt, secretKey) {
   const effectiveOld = await resolvePassphrase(oldPassphrase, secretKey);
@@ -2977,7 +2977,7 @@ zoo`.split("\n");
 function generateMnemonic2() {
   return generateMnemonic(wordlist, 256);
 }
-async function recoverWithMnemonic(mnemonic) {
+async function recoverWithMnemonic(mnemonic, extractable = false) {
   if (!validateMnemonic(mnemonic, wordlist)) {
     throw new Error("Invalid mnemonic: phrase does not pass BIP-39 checksum validation");
   }
@@ -2986,8 +2986,7 @@ async function recoverWithMnemonic(mnemonic) {
     "raw",
     entropy,
     { name: "AES-GCM", length: 256 },
-    false,
-    // extractable: false — key is for use only, never exported
+    extractable,
     ["encrypt", "decrypt"]
   );
 }
@@ -3001,7 +3000,7 @@ async function sealEnvelope(plaintext, passcode) {
   );
   const { ciphertext, iv } = await seal(dek, plaintext);
   const { wrappedKey, salt } = await wrapKey(passcode, dek);
-  return { ciphertext, iv, wrappedKey, salt };
+  return { version: 1, ciphertext, iv, wrappedKey, salt };
 }
 async function unsealEnvelope(envelope, passcode) {
   const dek = await unwrapKey(passcode, envelope.wrappedKey, envelope.salt);
@@ -3009,36 +3008,116 @@ async function unsealEnvelope(envelope, passcode) {
 }
 function encodeEnvelope(envelope) {
   return JSON.stringify({
+    version: envelope.version,
     ciphertext: toBase64(envelope.ciphertext),
     iv: toBase64(envelope.iv),
     wrappedKey: toBase64(envelope.wrappedKey),
     salt: toBase64(envelope.salt)
-  }, null, 2);
+  });
 }
 function decodeEnvelope(json) {
   const p = JSON.parse(json);
-  const required = ["ciphertext", "iv", "wrappedKey", "salt"];
-  for (const field of required) {
+  if (p["version"] !== 1) {
+    throw new TypeError(`Invalid envelope: unsupported or missing 'version' field (got ${JSON.stringify(p["version"])})`);
+  }
+  const binaryFields = ["ciphertext", "iv", "wrappedKey", "salt"];
+  for (const field of binaryFields) {
     if (typeof p[field] !== "string") {
       throw new TypeError(`Invalid envelope: missing or invalid '${field}' field`);
     }
   }
   const validated = p;
+  for (const field of binaryFields) {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(validated[field])) {
+      throw new TypeError(`Invalid envelope: '${field}' is not valid base64`);
+    }
+  }
   return {
+    version: 1,
     ciphertext: fromBase64(validated.ciphertext).buffer,
     iv: fromBase64(validated.iv),
     wrappedKey: fromBase64(validated.wrappedKey).buffer,
     salt: fromBase64(validated.salt)
   };
 }
+
+// src/circle.ts
+var JOIN_TTL_MS = 5 * 60 * 1e3;
+function buffersEqual(a, b) {
+  const ua = new Uint8Array(a);
+  const ub = new Uint8Array(b);
+  if (ua.length !== ub.length) return false;
+  let result = 0;
+  for (let i = 0; i < ua.length; i++) result |= ua[i] ^ ub[i];
+  return result === 0;
+}
+async function deriveVerificationCode(ephemeralPublicKey) {
+  const key = await importPublicKeyFromJwk(ephemeralPublicKey, "ECDH");
+  const raw = await crypto.subtle.exportKey("raw", key);
+  const hash = await digest(raw);
+  const bytes = new Uint8Array(hash);
+  const hex = (b) => b.toString(16).padStart(2, "0").toUpperCase();
+  return `${hex(bytes[0])}-${hex(bytes[1])}-${hex(bytes[2])}`;
+}
+async function initCircle(mnemonic, passphrase, secretKey) {
+  const aek = await recoverWithMnemonic(mnemonic, true);
+  const rawAEK = await crypto.subtle.exportKey("raw", aek);
+  const aekCommitment = await digest(rawAEK);
+  const { wrappedKey, salt } = await wrapKey(passphrase, aek, secretKey);
+  const deviceId = crypto.randomUUID();
+  return { wrappedAEK: { wrappedKey, salt }, aekCommitment, deviceId };
+}
+async function createJoinRequest(deviceMeta) {
+  const { publicKey, privateKey } = await generateECDHKeyPair();
+  const ephemeralPublicKey = await exportPublicKeyAsJwk(publicKey);
+  const verificationCode = await deriveVerificationCode(ephemeralPublicKey);
+  const deviceId = crypto.randomUUID();
+  const request = {
+    deviceId,
+    ephemeralPublicKey,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...deviceMeta ? { deviceMeta } : {}
+  };
+  return { request, ephemeralPrivateKey: privateKey, verificationCode };
+}
+async function authorizeJoin(joinRequest, wrappedAEK, passphrase, secretKey) {
+  const age = Date.now() - new Date(joinRequest.createdAt).getTime();
+  if (age > JOIN_TTL_MS) {
+    throw new Error("authorizeJoin: join request has expired (older than 5 minutes)");
+  }
+  const aek = await unwrapKey(passphrase, wrappedAEK.wrappedKey, wrappedAEK.salt, secretKey, true);
+  const rawAEK = await crypto.subtle.exportKey("raw", aek);
+  const recipientPublicKey = await importPublicKeyFromJwk(joinRequest.ephemeralPublicKey, "ECDH");
+  const { ciphertext, iv, ephemeralPublicKey } = await sealMessage(recipientPublicKey, rawAEK);
+  return { ciphertext, iv, ephemeralPublicKey };
+}
+async function finalizeJoin(sealedAEK, ephemeralPrivateKey, passphrase, secretKey, aekCommitment) {
+  const rawAEK = await unsealMessage(
+    ephemeralPrivateKey,
+    sealedAEK.ciphertext,
+    sealedAEK.iv,
+    sealedAEK.ephemeralPublicKey
+  );
+  const actualCommitment = await digest(rawAEK);
+  if (!buffersEqual(actualCommitment, aekCommitment)) {
+    throw new Error("finalizeJoin: AEK commitment mismatch \u2014 key may have been tampered with");
+  }
+  const aek = await importAesKey(rawAEK, true);
+  const { wrappedKey, salt } = await wrapKey(passphrase, aek, secretKey);
+  return { wrappedAEK: { wrappedKey, salt } };
+}
 export {
   AEK_KEY_ID,
+  authorizeJoin,
   combinePassphraseAndSecretKey,
+  createJoinRequest,
   decodeEnvelope,
   deleteCryptoKey,
+  deriveVerificationCode,
   digest,
   encodeEnvelope,
   exportPublicKeyAsJwk,
+  finalizeJoin,
   fromBase64,
   fromBase64Url,
   generateAesKey,
@@ -3049,6 +3128,7 @@ export {
   importAesKey,
   importPublicKeyFromJwk,
   init,
+  initCircle,
   loadCryptoKey,
   recoverWithMnemonic,
   rekey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codesense/conseal",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Browser-side zero-knowledge cryptography library using SubtleCrypto.",
   "type": "module",
   "main": "./dist/index.js",