@codesense/conseal 0.1.8 → 0.2.0

package/dist/index.d.ts

@@ -30,21 +30,44 @@ declare function generateAesKey(extractable?: boolean): Promise<CryptoKey>;
  */
 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<{
+/** Wraps a CryptoKey with a passphrase (and optional Secret Key). The input key must have extractable: true. */
+declare function wrapKey(passphrase: string, key: CryptoKey, secretKey?: Uint8Array): Promise<{
     wrappedKey: ArrayBuffer;
     salt: Uint8Array;
 }>;
 /** Unwraps a CryptoKey. Always returns extractable: false. */
-declare function unwrapKey(passphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array): Promise<CryptoKey>;
+declare function unwrapKey(passphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array, secretKey?: 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.
+ * The Secret Key (if any) stays the same — it is used on both the unwrap and re-wrap sides.
  */
-declare function rekey(oldPassphrase: string, newPassphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array): Promise<{
+declare function rekey(oldPassphrase: string, newPassphrase: string, wrappedKey: ArrayBuffer, salt: Uint8Array, secretKey?: Uint8Array): Promise<{
     wrappedKey: ArrayBuffer;
     salt: Uint8Array;
 }>;
+/**
+ * Rotates the Secret Key while keeping the passphrase the same.
+ * Use only when the Secret Key is compromised — this is a rare, heavyweight operation.
+ * Unwraps with passphrase + oldSecretKey, re-wraps with passphrase + newSecretKey.
+ *
+ * @param passphrase  - the passphrase (unchanged)
+ * @param oldSecretKey - the current Secret Key (used to unwrap)
+ * @param newSecretKey - the replacement Secret Key (used to re-wrap)
+ * @param wrappedKey   - the currently wrapped AEK
+ * @param salt         - the salt used when the AEK was wrapped
+ */
+declare function rekeySecretKey(passphrase: string, oldSecretKey: Uint8Array, newSecretKey: Uint8Array, wrappedKey: ArrayBuffer, salt: Uint8Array): Promise<{
+    wrappedKey: ArrayBuffer;
+    salt: Uint8Array;
+}>;
+
+/** Generates a random 128-bit (16-byte) secret key. */
+declare function generateSecretKey(): Uint8Array;
+/**
+ * Combines a passphrase and secret key into a single opaque string for PBKDF2.
+ * SHA-256(passphrase + ':' + base64(secretKey)), hex-encoded.
+ */
+declare function combinePassphraseAndSecretKey(passphrase: string, secretKey: Uint8Array): Promise<string>;
 
 /** Generates a long-term ECDH P-256 key pair for an account identity. */
 declare function generateECDHKeyPair(): Promise<CryptoKeyPair>;
@@ -96,10 +119,11 @@ declare function importPublicKeyFromJwk(jwk: JsonWebKey, algorithm: 'ECDH' | 'EC
 /** 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).
+ * Unwraps the AEK with the given passphrase (and optional Secret Key) and
+ * stores it in IndexedDB. After this completes, the AEK is available via
+ * load(AEK_KEY_ID).
  */
-declare function init(wrappedKey: ArrayBuffer, salt: Uint8Array, passphrase: string): Promise<void>;
+declare function init(wrappedKey: ArrayBuffer, salt: Uint8Array, passphrase: string, secretKey?: Uint8Array): Promise<void>;
 
 /** Generates a fresh 24-word BIP-39 mnemonic (256 bits of entropy). */
 declare function generateMnemonic(): string;
@@ -168,4 +192,4 @@ declare function fromBase64Url(b64url: string): Uint8Array;
 /** 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 };
+export { AEK_KEY_ID, type SealedEnvelope, combinePassphraseAndSecretKey, decodeEnvelope, digest, encodeEnvelope, exportPublicKeyAsJwk, fromBase64, fromBase64Url, generateAesKey, generateECDHKeyPair, generateECDSAKeyPair, generateMnemonic, generateSecretKey, importAesKey, importPublicKeyFromJwk, init, recoverWithMnemonic, rekey, rekeySecretKey, seal, sealEnvelope, sealMessage, sign, toBase64, toBase64Url, unseal, unsealEnvelope, unsealMessage, unwrapKey, verify, wrapKey };

package/dist/index.js

@@ -33,6 +33,39 @@ async function importAesKey(raw, extractable = false) {
   );
 }
 
+// src/digest.ts
+async function digest(data) {
+  return crypto.subtle.digest("SHA-256", data);
+}
+
+// src/base64.ts
+function toBase64(buf) {
+  const u8 = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  let binary = "";
+  for (const byte of u8) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function fromBase64(b64) {
+  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+}
+function toBase64Url(buf) {
+  return toBase64(buf).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function fromBase64Url(b64url) {
+  const b64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+}
+
+// src/secret-key.ts
+function generateSecretKey() {
+  return crypto.getRandomValues(new Uint8Array(16));
+}
+async function combinePassphraseAndSecretKey(passphrase, secretKey) {
+  const input = `${passphrase}:${toBase64(secretKey)}`;
+  const hash = await digest(new TextEncoder().encode(input));
+  return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
 // src/pbkdf2.ts
 var ITERATIONS = 6e5;
 var SALT_LENGTH = 16;
@@ -52,17 +85,22 @@ async function deriveWrappingKey(passphrase, salt) {
     ["wrapKey", "unwrapKey"]
   );
 }
-async function wrapKey(passphrase, key) {
+async function resolvePassphrase(passphrase, secretKey) {
+  return secretKey ? combinePassphraseAndSecretKey(passphrase, secretKey) : passphrase;
+}
+async function wrapKey(passphrase, key, secretKey) {
   if (!key.extractable) {
     throw new Error("wrapKey: key must be extractable (extractable: true)");
   }
+  const effective = await resolvePassphrase(passphrase, secretKey);
   const salt = crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
-  const wrappingKey = await deriveWrappingKey(passphrase, salt);
+  const wrappingKey = await deriveWrappingKey(effective, salt);
   const wrappedKey = await crypto.subtle.wrapKey("raw", key, wrappingKey, "AES-KW");
   return { wrappedKey, salt };
 }
-async function unwrapKey(passphrase, wrappedKey, salt) {
-  const wrappingKey = await deriveWrappingKey(passphrase, salt);
+async function unwrapKey(passphrase, wrappedKey, salt, secretKey) {
+  const effective = await resolvePassphrase(passphrase, secretKey);
+  const wrappingKey = await deriveWrappingKey(effective, salt);
   return crypto.subtle.unwrapKey(
     "raw",
     wrappedKey,
@@ -74,8 +112,27 @@ async function unwrapKey(passphrase, wrappedKey, salt) {
     ["encrypt", "decrypt"]
   );
 }
-async function rekey(oldPassphrase, newPassphrase, wrappedKey, salt) {
-  const oldWrappingKey = await deriveWrappingKey(oldPassphrase, salt);
+async function rekey(oldPassphrase, newPassphrase, wrappedKey, salt, secretKey) {
+  const effectiveOld = await resolvePassphrase(oldPassphrase, secretKey);
+  const oldWrappingKey = await deriveWrappingKey(effectiveOld, salt);
+  const aek = await crypto.subtle.unwrapKey(
+    "raw",
+    wrappedKey,
+    oldWrappingKey,
+    "AES-KW",
+    { name: "AES-GCM", length: 256 },
+    true,
+    // extractable: true — needed so wrapKey() can wrap it again
+    ["encrypt", "decrypt"]
+  );
+  return wrapKey(newPassphrase, aek, secretKey);
+}
+async function rekeySecretKey(passphrase, oldSecretKey, newSecretKey, wrappedKey, salt) {
+  if (oldSecretKey.length === newSecretKey.length && oldSecretKey.every((b, i) => b === newSecretKey[i])) {
+    throw new Error("rekeySecretKey: oldSecretKey and newSecretKey must be different");
+  }
+  const effectiveOld = await resolvePassphrase(passphrase, oldSecretKey);
+  const oldWrappingKey = await deriveWrappingKey(effectiveOld, salt);
   const aek = await crypto.subtle.unwrapKey(
     "raw",
     wrappedKey,
@@ -86,7 +143,7 @@ async function rekey(oldPassphrase, newPassphrase, wrappedKey, salt) {
     // extractable: true — needed so wrapKey() can wrap it again
     ["encrypt", "decrypt"]
   );
-  return wrapKey(newPassphrase, aek);
+  return wrapKey(passphrase, aek, newSecretKey);
 }
 
 // src/jwk.ts
@@ -154,8 +211,8 @@ async function verify(publicKey, signature, data) {
 
 // src/init.ts
 var AEK_KEY_ID = "aek";
-async function init(wrappedKey, salt, passphrase) {
-  const aek = await unwrapKey(passphrase, wrappedKey, salt);
+async function init(wrappedKey, salt, passphrase, secretKey) {
+  const aek = await unwrapKey(passphrase, wrappedKey, salt, secretKey);
   await save(AEK_KEY_ID, aek);
 }
 
@@ -2897,24 +2954,6 @@ async function recoverWithMnemonic(mnemonic) {
   );
 }
 
-// src/base64.ts
-function toBase64(buf) {
-  const u8 = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
-  let binary = "";
-  for (const byte of u8) binary += String.fromCharCode(byte);
-  return btoa(binary);
-}
-function fromBase64(b64) {
-  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
-}
-function toBase64Url(buf) {
-  return toBase64(buf).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
-}
-function fromBase64Url(b64url) {
-  const b64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
-  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
-}
-
 // src/envelope.ts
 async function sealEnvelope(plaintext, passcode) {
   const dek = await crypto.subtle.generateKey(
@@ -2954,13 +2993,9 @@ function decodeEnvelope(json) {
     salt: fromBase64(validated.salt)
   };
 }
-
-// src/digest.ts
-async function digest(data) {
-  return crypto.subtle.digest("SHA-256", data);
-}
 export {
   AEK_KEY_ID,
+  combinePassphraseAndSecretKey,
   decodeEnvelope,
   digest,
   encodeEnvelope,
@@ -2971,12 +3006,14 @@ export {
   generateECDHKeyPair,
   generateECDSAKeyPair,
   generateMnemonic2 as generateMnemonic,
+  generateSecretKey,
   importAesKey,
   importPublicKeyFromJwk,
   init,
   load,
   recoverWithMnemonic,
   rekey,
+  rekeySecretKey,
   remove,
   save,
   seal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codesense/conseal",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Browser-side zero-knowledge cryptography library using SubtleCrypto.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,11 +27,12 @@
     "node": ">=18"
   },
   "devDependencies": {
+    "@scure/bip39": "^2.0.0",
     "fake-indexeddb": "^6.2.5",
     "happy-dom": "^20.0.0",
+    "jsdom": "^29.0.1",
     "tsup": "^8.0.0",
     "typescript": "^6.0.0",
-    "vitest": "^4.0.0",
-    "@scure/bip39": "^2.0.0"
+    "vitest": "^4.1.2"
   }
 }