@getmyenv/crypto 0.4.1 → 0.6.0

package/dist/backup.d.ts

@@ -3,6 +3,7 @@ export declare function createBackupEnvelope(input: {
     projectName: string;
     publicKey: string;
     wrappedPrivateKey: WrappedPrivateKey;
+    recoveryWrappedKey?: WrappedPrivateKey | null;
     contexts: BackupContext[];
     keys: string[];
     tags?: Record<string, string>;
@@ -11,15 +12,15 @@ export declare function createBackupEnvelope(input: {
 export declare function serializeBackup(envelope: EncryptedBackupEnvelope): string;
 export declare function parseBackup(raw: string): EncryptedBackupEnvelope;
 /**
- * Open every context key in a backup with the Vault password it was made with.
- * Keyed by context slug. Caller wipes the returned keys when done.
+ * Open every context key in a backup with the Vault password or the recovery
+ * code it was made with. Keyed by context slug. Caller wipes the returned keys.
  */
-export declare function openBackupKeys(vaultPassword: string, envelope: EncryptedBackupEnvelope): Promise<Map<string, Uint8Array>>;
+export declare function openBackupKeys(secret: string, envelope: EncryptedBackupEnvelope): Promise<Map<string, Uint8Array>>;
 /**
- * Decrypt every value in a backup with the Vault password.
+ * Decrypt every value in a backup with the Vault password or the recovery code.
  * Works without getmyenv being reachable.
  */
-export declare function restoreValuesFromBackup(vaultPassword: string, envelope: EncryptedBackupEnvelope): Promise<{
+export declare function restoreValuesFromBackup(secret: string, envelope: EncryptedBackupEnvelope): Promise<{
     contexts: BackupContext[];
     keys: string[];
     values: Array<{

package/dist/backup.js

@@ -1,5 +1,6 @@
-import { BACKUP_FORMAT_VERSION } from "./types.js";
+import { BACKUP_FORMAT_VERSION, READABLE_BACKUP_VERSIONS } from "./types.js";
 import { decryptSecret, openSealedKey, parseSealedKey, parseWrappedKey, publicKeyFromPrivate, unwrapPrivateKey, wipe, } from "./envelope.js";
+import { looksLikeRecoveryCode, parseRecoveryCode, unwrapWithRecoveryCode } from "./recovery.js";
 export function createBackupEnvelope(input) {
     const hasTags = input.tags && Object.keys(input.tags).length > 0;
     return {
@@ -9,6 +10,7 @@ export function createBackupEnvelope(input) {
         projectName: input.projectName,
         publicKey: input.publicKey,
         wrappedPrivateKey: input.wrappedPrivateKey,
+        recoveryWrappedKey: input.recoveryWrappedKey ?? null,
         contexts: input.contexts,
         keys: input.keys,
         ...(hasTags ? { tags: input.tags } : {}),
@@ -23,7 +25,7 @@ export function parseBackup(raw) {
     if (parsed.format !== "getmyenv-backup") {
         throw new Error("Not a getmyenv backup file");
     }
-    if (parsed.version !== BACKUP_FORMAT_VERSION) {
+    if (!READABLE_BACKUP_VERSIONS.includes(parsed.version)) {
         throw new Error(`Unsupported backup version: ${String(parsed.version)}`);
     }
     if (typeof parsed.projectName !== "string" ||
@@ -34,6 +36,9 @@ export function parseBackup(raw) {
         throw new Error("Invalid backup file");
     }
     parseWrappedKey(JSON.stringify(parsed.wrappedPrivateKey));
+    if (parsed.recoveryWrappedKey != null) {
+        parseWrappedKey(JSON.stringify(parsed.recoveryWrappedKey));
+    }
     for (const c of parsed.contexts) {
         if (!Number.isInteger(c.id) || typeof c.slug !== "string") {
             throw new Error("Invalid backup file");
@@ -43,12 +48,45 @@ export function parseBackup(raw) {
     }
     return parsed;
 }
+function recoveryCodeOrNull(secret) {
+    if (!looksLikeRecoveryCode(secret))
+        return null;
+    try {
+        return parseRecoveryCode(secret);
+    }
+    catch {
+        return null;
+    }
+}
+/** The backup's private key, from the Vault password or the recovery code it was made with. */
+async function openBackupPrivateKey(secret, envelope) {
+    const code = recoveryCodeOrNull(secret);
+    if (code && envelope.recoveryWrappedKey) {
+        try {
+            return await unwrapWithRecoveryCode(code, envelope.recoveryWrappedKey);
+        }
+        catch {
+            throw new Error("That recovery code does not open this backup.");
+        }
+    }
+    try {
+        return await unwrapPrivateKey(secret, envelope.wrappedPrivateKey);
+    }
+    catch (err) {
+        if (code) {
+            throw new Error(envelope.version === 3
+                ? "This backup was made before recovery codes. Use the Vault password it was made with."
+                : "This backup has no recovery code. Use the Vault password it was made with.");
+        }
+        throw err;
+    }
+}
 /**
- * Open every context key in a backup with the Vault password it was made with.
- * Keyed by context slug. Caller wipes the returned keys when done.
+ * Open every context key in a backup with the Vault password or the recovery
+ * code it was made with. Keyed by context slug. Caller wipes the returned keys.
  */
-export async function openBackupKeys(vaultPassword, envelope) {
-    const privateKey = await unwrapPrivateKey(vaultPassword, envelope.wrappedPrivateKey);
+export async function openBackupKeys(secret, envelope) {
+    const privateKey = await openBackupPrivateKey(secret, envelope);
     try {
         if (publicKeyFromPrivate(privateKey) !== envelope.publicKey) {
             throw new Error("Backup key mismatch");
@@ -65,11 +103,11 @@ export async function openBackupKeys(vaultPassword, envelope) {
     }
 }
 /**
- * Decrypt every value in a backup with the Vault password.
+ * Decrypt every value in a backup with the Vault password or the recovery code.
  * Works without getmyenv being reachable.
  */
-export async function restoreValuesFromBackup(vaultPassword, envelope) {
-    const contextKeys = await openBackupKeys(vaultPassword, envelope);
+export async function restoreValuesFromBackup(secret, envelope) {
+    const contextKeys = await openBackupKeys(secret, envelope);
     try {
         return {
             contexts: envelope.contexts,

package/dist/envelope.d.ts

@@ -1,6 +1,6 @@
 import { type EncryptedSecretPayload, type SealedKey, type WrappedPrivateKey } from "./types.js";
-/** Overwrite key material in place. */
-export declare function wipe(...buffers: Array<Uint8Array | null | undefined>): void;
+import { wipe } from "./wrap.js";
+export { wipe };
 /** A fresh X25519 keypair. Used for server tokens and guest projects. */
 export declare function generateKeypair(): {
     publicKey: string;

package/dist/envelope.js

@@ -1,31 +1,13 @@
-import { gcm } from "@noble/ciphers/aes.js";
 import { x25519 } from "@noble/curves/ed25519.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
 import { sha256 } from "@noble/hashes/sha2.js";
 import { ALGORITHM, CRYPTO_FORMAT_VERSION, DEFAULT_KDF_PARAMS, KDF, SEAL, } from "./types.js";
-import { base64ToBytes, base64UrlToBytes, bytesToBase64, bytesToBase64Url, getRandomBytes, utf8Decode, utf8Encode, } from "./bytes.js";
-import { assertKdfParams, deriveKek, generateSalt } from "./kdf.js";
-const NONCE_LENGTH = 12;
-const KEY_LENGTH = 32;
+import { base64ToBytes, base64UrlToBytes, bytesToBase64, bytesToBase64Url, utf8Decode, utf8Encode, } from "./bytes.js";
+import { assertKdfParams } from "./kdf.js";
+import { aesGcmDecrypt, aesGcmEncrypt, assertKey, KEY_LENGTH, unwrapKeyWith, wipe, wrapKeyWith, } from "./wrap.js";
+export { wipe };
 const AAD_USER_KEY = "getmyenv:v2:userkey";
 const HKDF_INFO_SEAL = "getmyenv:v2:seal";
-/** Overwrite key material in place. */
-export function wipe(...buffers) {
-    for (const b of buffers)
-        b?.fill(0);
-}
-function aesGcmEncrypt(key, plaintext, aad) {
-    const nonce = getRandomBytes(NONCE_LENGTH);
-    const ciphertext = gcm(key, nonce, utf8Encode(aad)).encrypt(plaintext);
-    return { nonce, ciphertext };
-}
-function aesGcmDecrypt(key, nonce, ciphertext, aad) {
-    return gcm(key, nonce, utf8Encode(aad)).decrypt(ciphertext);
-}
-function assertKey(key) {
-    if (key.length !== KEY_LENGTH)
-        throw new Error("Invalid key length");
-}
 /** A fresh X25519 keypair. Used for server tokens and guest projects. */
 export function generateKeypair() {
     const privateKey = x25519.utils.randomSecretKey();
@@ -47,39 +29,11 @@ export function publicKeyFingerprint(publicKey) {
 }
 /** Wrap an X25519 private key with a key derived from a password. */
 export async function wrapPrivateKey(password, privateKey) {
-    assertKey(privateKey);
-    const salt = generateSalt();
-    const kek = await deriveKek(password, salt);
-    try {
-        const { nonce, ciphertext } = aesGcmEncrypt(kek, privateKey, AAD_USER_KEY);
-        return {
-            version: CRYPTO_FORMAT_VERSION,
-            kdf: KDF,
-            kdfParams: { ...DEFAULT_KDF_PARAMS },
-            salt: bytesToBase64(salt),
-            nonce: bytesToBase64(nonce),
-            ciphertext: bytesToBase64(ciphertext),
-        };
-    }
-    finally {
-        wipe(kek);
-    }
+    return wrapKeyWith(password, privateKey, AAD_USER_KEY, DEFAULT_KDF_PARAMS);
 }
 /** Throws when the password is wrong or the blob was changed. */
 export async function unwrapPrivateKey(password, wrapped) {
-    if (wrapped.version !== CRYPTO_FORMAT_VERSION || wrapped.kdf !== KDF) {
-        throw new Error("Unsupported wrapped key");
-    }
-    assertKdfParams(wrapped.kdfParams);
-    const kek = await deriveKek(password, base64ToBytes(wrapped.salt), wrapped.kdfParams);
-    try {
-        const key = aesGcmDecrypt(kek, base64ToBytes(wrapped.nonce), base64ToBytes(wrapped.ciphertext), AAD_USER_KEY);
-        assertKey(key);
-        return key;
-    }
-    finally {
-        wipe(kek);
-    }
+    return unwrapKeyWith(password, wrapped, AAD_USER_KEY);
 }
 /** New user keypair, wrapped with the Vault password. */
 export async function createUserKeys(password) {

package/dist/fingerprint.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Change detection for a push: HMAC-SHA256 over the sorted name/value pairs,
+ * keyed from the context key. Not a protection for the values. The key only
+ * stops the server, which stores the result, from guessing short values.
+ */
+export declare function pushFingerprint(contextKey: Uint8Array, values: Record<string, string>): string;

package/dist/fingerprint.js

@@ -0,0 +1,21 @@
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToBase64Url, utf8Encode } from "./bytes.js";
+import { wipe } from "./wrap.js";
+const HKDF_INFO_PUSH = "getmyenv push fingerprint";
+/**
+ * Change detection for a push: HMAC-SHA256 over the sorted name/value pairs,
+ * keyed from the context key. Not a protection for the values. The key only
+ * stops the server, which stores the result, from guessing short values.
+ */
+export function pushFingerprint(contextKey, values) {
+    const key = hkdf(sha256, contextKey, new Uint8Array(0), utf8Encode(HKDF_INFO_PUSH), 32);
+    const lines = Object.keys(values)
+        .sort()
+        .map((name) => `${name}\0${values[name]}`)
+        .join("\n");
+    const mac = hmac(sha256, key, utf8Encode(lines));
+    wipe(key);
+    return bytesToBase64Url(mac);
+}

package/dist/index.d.ts

@@ -2,5 +2,7 @@ export * from "./types.js";
 export * from "./bytes.js";
 export * from "./kdf.js";
 export * from "./envelope.js";
+export * from "./recovery.js";
 export * from "./backup.js";
 export * from "./identity.js";
+export * from "./fingerprint.js";

package/dist/index.js

@@ -2,5 +2,7 @@ export * from "./types.js";
 export * from "./bytes.js";
 export * from "./kdf.js";
 export * from "./envelope.js";
+export * from "./recovery.js";
 export * from "./backup.js";
 export * from "./identity.js";
+export * from "./fingerprint.js";

package/dist/recovery.d.ts

@@ -0,0 +1,29 @@
+import type { KdfParams, WrappedPrivateKey } from "./types.js";
+/** The code carries 128 bits of entropy, so the lowest accepted Argon2id cost is enough. */
+export declare const RECOVERY_KDF_PARAMS: KdfParams;
+/** XXXX-XXXX-... from the canonical form. */
+export declare function formatRecoveryCode(code: string): string;
+/** A new random recovery code, formatted for display. */
+export declare function generateRecoveryCode(): string;
+/** True when the input has the shape of a recovery code, whether or not its checksum is right. */
+export declare function looksLikeRecoveryCode(input: string): boolean;
+/**
+ * The canonical form (28 characters, no dashes) used as the KDF input.
+ * Formatting never changes the key. Throws on a typo.
+ */
+export declare function parseRecoveryCode(input: string): string;
+/** Same code, ignoring case, spaces and dashes. False when either one is not a valid code. */
+export declare function recoveryCodesMatch(a: string, b: string): boolean;
+export declare function wrapWithRecoveryCode(code: string, privateKey: Uint8Array): Promise<WrappedPrivateKey>;
+/** Throws "That recovery code does not open this vault." when the code is wrong. */
+export declare function unwrapWithRecoveryCode(code: string, wrapped: WrappedPrivateKey): Promise<Uint8Array>;
+/** A new recovery code and the private key wrapped with it. */
+export declare function createRecoveryWrap(privateKey: Uint8Array): Promise<{
+    code: string;
+    wrapped: WrappedPrivateKey;
+}>;
+/**
+ * Check a recovery wrap before upload: it must open with the code and hold the
+ * private key of this public key. The server cannot check this.
+ */
+export declare function assertRecoveryWrap(code: string, wrapped: WrappedPrivateKey, publicKey: string): Promise<void>;

package/dist/recovery.js

@@ -0,0 +1,146 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { getRandomBytes } from "./bytes.js";
+import { publicKeyFromPrivate } from "./envelope.js";
+import { unwrapKeyWith, wipe, wrapKeyWith } from "./wrap.js";
+/**
+ * Recovery code: 16 random bytes and 1 checksum byte, in Crockford base32,
+ * shown as 7 groups of 4. It wraps the same private key as the Vault password,
+ * so either one opens the vault.
+ */
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const SECRET_BYTES = 16;
+const CODE_CHARS = 28;
+const AAD_RECOVERY_KEY = "getmyenv:v2:recoverykey";
+/** The code carries 128 bits of entropy, so the lowest accepted Argon2id cost is enough. */
+export const RECOVERY_KDF_PARAMS = {
+    memory: 19_456,
+    iterations: 2,
+    parallelism: 1,
+    hashLength: 32,
+};
+function checksum(secret) {
+    return sha256(secret)[0];
+}
+function encode(bytes) {
+    let out = "";
+    let buffer = 0;
+    let bits = 0;
+    for (const b of bytes) {
+        buffer = (buffer << 8) | b;
+        bits += 8;
+        while (bits >= 5) {
+            out += ALPHABET[(buffer >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+        buffer &= (1 << bits) - 1;
+    }
+    if (bits > 0)
+        out += ALPHABET[(buffer << (5 - bits)) & 31];
+    return out;
+}
+function decode(chars) {
+    const out = [];
+    let buffer = 0;
+    let bits = 0;
+    for (const c of chars) {
+        const v = ALPHABET.indexOf(c);
+        if (v < 0)
+            return null;
+        buffer = (buffer << 5) | v;
+        bits += 5;
+        if (bits >= 8) {
+            out.push((buffer >>> (bits - 8)) & 255);
+            bits -= 8;
+        }
+        buffer &= (1 << bits) - 1;
+    }
+    if (buffer !== 0)
+        return null;
+    return new Uint8Array(out);
+}
+function normalize(input) {
+    return input
+        .toUpperCase()
+        .replace(/[\s-]/g, "")
+        .replace(/O/g, "0")
+        .replace(/[IL]/g, "1");
+}
+/** XXXX-XXXX-... from the canonical form. */
+export function formatRecoveryCode(code) {
+    return normalize(code).match(/.{1,4}/g).join("-");
+}
+/** A new random recovery code, formatted for display. */
+export function generateRecoveryCode() {
+    const secret = getRandomBytes(SECRET_BYTES);
+    const bytes = new Uint8Array(SECRET_BYTES + 1);
+    bytes.set(secret, 0);
+    bytes[SECRET_BYTES] = checksum(secret);
+    wipe(secret);
+    const code = formatRecoveryCode(encode(bytes));
+    wipe(bytes);
+    return code;
+}
+/** True when the input has the shape of a recovery code, whether or not its checksum is right. */
+export function looksLikeRecoveryCode(input) {
+    const n = normalize(input);
+    return n.length === CODE_CHARS && [...n].every((c) => ALPHABET.includes(c));
+}
+/**
+ * The canonical form (28 characters, no dashes) used as the KDF input.
+ * Formatting never changes the key. Throws on a typo.
+ */
+export function parseRecoveryCode(input) {
+    const n = normalize(input);
+    if (n.length !== CODE_CHARS)
+        throw new Error(`A recovery code has ${CODE_CHARS} characters.`);
+    const bytes = decode(n);
+    if (!bytes || bytes.length !== SECRET_BYTES + 1)
+        throw new Error("That recovery code has a typo.");
+    const ok = checksum(bytes.subarray(0, SECRET_BYTES)) === bytes[SECRET_BYTES];
+    wipe(bytes);
+    if (!ok)
+        throw new Error("That recovery code has a typo.");
+    return n;
+}
+/** Same code, ignoring case, spaces and dashes. False when either one is not a valid code. */
+export function recoveryCodesMatch(a, b) {
+    try {
+        return parseRecoveryCode(a) === parseRecoveryCode(b);
+    }
+    catch {
+        return false;
+    }
+}
+export async function wrapWithRecoveryCode(code, privateKey) {
+    return wrapKeyWith(parseRecoveryCode(code), privateKey, AAD_RECOVERY_KEY, RECOVERY_KDF_PARAMS);
+}
+/** Throws "That recovery code does not open this vault." when the code is wrong. */
+export async function unwrapWithRecoveryCode(code, wrapped) {
+    const canonical = parseRecoveryCode(code);
+    try {
+        return await unwrapKeyWith(canonical, wrapped, AAD_RECOVERY_KEY);
+    }
+    catch {
+        throw new Error("That recovery code does not open this vault.");
+    }
+}
+/** A new recovery code and the private key wrapped with it. */
+export async function createRecoveryWrap(privateKey) {
+    const code = generateRecoveryCode();
+    return { code, wrapped: await wrapWithRecoveryCode(code, privateKey) };
+}
+/**
+ * Check a recovery wrap before upload: it must open with the code and hold the
+ * private key of this public key. The server cannot check this.
+ */
+export async function assertRecoveryWrap(code, wrapped, publicKey) {
+    const key = await unwrapWithRecoveryCode(code, wrapped);
+    try {
+        if (publicKeyFromPrivate(key) !== publicKey) {
+            throw new Error("The recovery code does not match this vault key.");
+        }
+    }
+    finally {
+        wipe(key);
+    }
+}

package/dist/types.d.ts

@@ -59,7 +59,9 @@ export type EncryptedSecretPayload = {
     nonce: string;
     ciphertext: string;
 };
-export declare const BACKUP_FORMAT_VERSION: 3;
+export declare const BACKUP_FORMAT_VERSION: 4;
+/** Versions parseBackup reads. v3 has no recovery wrap and opens with its Vault password only. */
+export declare const READABLE_BACKUP_VERSIONS: readonly [3, 4];
 export type BackupContext = {
     /** Context id when the backup was made. Part of the sealed key's binding. */
     id: number;
@@ -78,15 +80,18 @@ export type BackupValue = {
 };
 /**
  * Portable encrypted backup. Opens with the Vault password that was set when
- * it was made: it carries the wrapped private key and the context keys sealed to it.
+ * it was made, or with the recovery code of that time: it carries both wraps
+ * of the private key and the context keys sealed to it.
  */
 export type EncryptedBackupEnvelope = {
     format: "getmyenv-backup";
-    version: typeof BACKUP_FORMAT_VERSION;
+    version: (typeof READABLE_BACKUP_VERSIONS)[number];
     createdAt: string;
     projectName: string;
     publicKey: string;
     wrappedPrivateKey: WrappedPrivateKey;
+    /** The private key wrapped with the recovery code. Absent in v3, null for guests and vaults without a code. */
+    recoveryWrappedKey?: WrappedPrivateKey | null;
     contexts: BackupContext[];
     /** Every variable name in the project, including ones with no values. */
     keys: string[];

package/dist/types.js

@@ -17,4 +17,6 @@ export const KDF_BOUNDS = {
     parallelism: { min: 1, max: 4 },
     hashLength: 32,
 };
-export const BACKUP_FORMAT_VERSION = 3;
+export const BACKUP_FORMAT_VERSION = 4;
+/** Versions parseBackup reads. v3 has no recovery wrap and opens with its Vault password only. */
+export const READABLE_BACKUP_VERSIONS = [3, 4];

package/dist/wrap.d.ts

@@ -0,0 +1,16 @@
+import { type KdfParams, type WrappedPrivateKey } from "./types.js";
+/** Internal. Not exported from the package index. */
+export declare const NONCE_LENGTH = 12;
+export declare const KEY_LENGTH = 32;
+/** Overwrite key material in place. */
+export declare function wipe(...buffers: Array<Uint8Array | null | undefined>): void;
+export declare function assertKey(key: Uint8Array): void;
+export declare function aesGcmEncrypt(key: Uint8Array, plaintext: Uint8Array, aad: string): {
+    nonce: Uint8Array;
+    ciphertext: Uint8Array;
+};
+export declare function aesGcmDecrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad: string): Uint8Array;
+/** Wrap a private key with a key derived from a secret. The AAD says which kind of secret. */
+export declare function wrapKeyWith(secret: string, privateKey: Uint8Array, aad: string, params: KdfParams): Promise<WrappedPrivateKey>;
+/** Throws when the secret is wrong, the AAD differs, or the blob was changed. */
+export declare function unwrapKeyWith(secret: string, wrapped: WrappedPrivateKey, aad: string): Promise<Uint8Array>;

package/dist/wrap.js

@@ -0,0 +1,60 @@
+import { gcm } from "@noble/ciphers/aes.js";
+import { CRYPTO_FORMAT_VERSION, KDF } from "./types.js";
+import { base64ToBytes, bytesToBase64, getRandomBytes, utf8Encode } from "./bytes.js";
+import { assertKdfParams, deriveKek, generateSalt } from "./kdf.js";
+/** Internal. Not exported from the package index. */
+export const NONCE_LENGTH = 12;
+export const KEY_LENGTH = 32;
+/** Overwrite key material in place. */
+export function wipe(...buffers) {
+    for (const b of buffers)
+        b?.fill(0);
+}
+export function assertKey(key) {
+    if (key.length !== KEY_LENGTH)
+        throw new Error("Invalid key length");
+}
+export function aesGcmEncrypt(key, plaintext, aad) {
+    const nonce = getRandomBytes(NONCE_LENGTH);
+    const ciphertext = gcm(key, nonce, utf8Encode(aad)).encrypt(plaintext);
+    return { nonce, ciphertext };
+}
+export function aesGcmDecrypt(key, nonce, ciphertext, aad) {
+    return gcm(key, nonce, utf8Encode(aad)).decrypt(ciphertext);
+}
+/** Wrap a private key with a key derived from a secret. The AAD says which kind of secret. */
+export async function wrapKeyWith(secret, privateKey, aad, params) {
+    assertKey(privateKey);
+    const salt = generateSalt();
+    const kek = await deriveKek(secret, salt, params);
+    try {
+        const { nonce, ciphertext } = aesGcmEncrypt(kek, privateKey, aad);
+        return {
+            version: CRYPTO_FORMAT_VERSION,
+            kdf: KDF,
+            kdfParams: { ...params },
+            salt: bytesToBase64(salt),
+            nonce: bytesToBase64(nonce),
+            ciphertext: bytesToBase64(ciphertext),
+        };
+    }
+    finally {
+        wipe(kek);
+    }
+}
+/** Throws when the secret is wrong, the AAD differs, or the blob was changed. */
+export async function unwrapKeyWith(secret, wrapped, aad) {
+    if (wrapped.version !== CRYPTO_FORMAT_VERSION || wrapped.kdf !== KDF) {
+        throw new Error("Unsupported wrapped key");
+    }
+    assertKdfParams(wrapped.kdfParams);
+    const kek = await deriveKek(secret, base64ToBytes(wrapped.salt), wrapped.kdfParams);
+    try {
+        const key = aesGcmDecrypt(kek, base64ToBytes(wrapped.nonce), base64ToBytes(wrapped.ciphertext), aad);
+        assertKey(key);
+        return key;
+    }
+    finally {
+        wipe(kek);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmyenv/crypto",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Encryption for getmyenv: Argon2id-wrapped X25519 keys, sealed per-context keys, AES-256-GCM values",
   "type": "module",
   "main": "./dist/index.js",