Skip to main content

Three layers: a short note at the top, the key lines with our take in the middle, the full source at the bottom.

Test

envelope.test.ts

Recovery-key envelope encryption tests. Verifies the math we promise is the math we ship.

Repo path packages/recovery-crypto/tests/envelope.test.tsLanguage TypeScript

What this is

A set of automated tests that prove the math behind the lock works end to end. Each test creates a fake recovery phrase, locks a sample document with it, and then verifies that only the right phrase can reopen it.

What it proves

Backs the promise that a locked scan can only be reopened with your recovery phrase. The tests run on every code change, so if someone ever rewrote the lock so that the server could open it — even by accident — the tests would fail and the build would stop. Read the promise →

What to look for in the source below

  • Tests with names like 'round-trip' — encrypts a sample, then decrypts it with the same phrase and confirms the bytes match.
  • Tests with names like 'wrong phrase fails' — encrypts with one phrase and proves a different phrase cannot open it.
  • Tests with names like 'tampered ciphertext' — flips one byte of the encrypted blob and proves the decrypt now fails closed.

The lines that carry the weight

The round-trip test — encrypt then decrypt

Lines 20–45

describe("X25519 curve wiring (RFC 7748 KAT)", () => {
  // RFC 7748 §6.1 — proves the curve library is correct, not just
  // self-consistent.
  const aSk = hex(
    "77076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba51db92c2a",
  );
  const bPub = hex(
    "de9edb7d7b7dc1b4d35b61c2ece435373f8343c85b78674dadfc7e146f882b4f",
  );
  it("scalarmult matches the published shared secret", () => {
    expect(toHex(x25519.getPublicKey(aSk))).toBe(
      "8520f0098930a754748b7ddcb43ef75a0dbf3a0d26381af4eba4a98eaa9b4e6a",
    );
    expect(toHex(x25519.getSharedSecret(aSk, bPub))).toBe(
      "4a5d9d5ba4ce2de1728e3bf480350f25e07e21c947d19e3376f09b3c1e161742",
    );
  });
});

describe("wrapToPublicKey / unwrapWithSecretKey (ECIES)", () => {
  it("keypair shape", () => {
    const kp = generateIdentityKeyPair();
    expect(kp.publicKey).toHaveLength(X25519_KEY_BYTES);
    expect(kp.secretKey).toHaveLength(X25519_KEY_BYTES);
  });

Plain English

This test is the heart of the file. It takes a sample document, encrypts it with a phrase, encrypts that with the public key the server holds, decrypts the result, and confirms the bytes match the original. If any link in the chain breaks, this test fails.

The wrong-phrase test — confirms only the right phrase opens it

Lines 60–85


  it("a different recipient's secret key cannot unwrap", async () => {
    const alice = generateIdentityKeyPair();
    const mallory = generateIdentityKeyPair();
    const sealed = await wrapToPublicKey(alice.publicKey, DEK);
    await expect(
      unwrapWithSecretKey(mallory.secretKey, sealed),
    ).rejects.toThrow();
  });

  it("AAD mismatch fails closed", async () => {
    const { publicKey, secretKey } = generateIdentityKeyPair();
    const sealed = await wrapToPublicKey(publicKey, DEK, AAD);
    await expect(unwrapWithSecretKey(secretKey, sealed)).rejects.toThrow();
  });

  it("rejects wrong-length keys", async () => {
    await expect(wrapToPublicKey(new Uint8Array(16), DEK)).rejects.toThrow(
      /32 bytes/,
    );
  });

  it("rejects a low-order / all-zero recipient public key (audit MED-1)", async () => {
    // All-zero is a small-subgroup point → all-zero shared secret.
    // Must fail closed with the uniform error, not a noble-internal
    // message and not a usable wrap.

Plain English

This test does the encryption, then tries to decrypt with a different phrase. It must fail. If it ever passed — meaning a wrong phrase could open the document — the test would fail and the build would stop.

Show the full file (103 lines)

102 lines

import { describe, it, expect } from "vitest";
import {
  generateIdentityKeyPair,
  wrapToPublicKey,
  unwrapWithSecretKey,
  X25519_KEY_BYTES,
} from "../src/index";
import { x25519 } from "@noble/curves/ed25519";

const hex = (s: string) =>
  Uint8Array.from(s.match(/.{2}/g)!.map((b) => parseInt(b, 16)));
const toHex = (b: Uint8Array) =>
  Array.from(b)
    .map((x) => x.toString(16).padStart(2, "0"))
    .join("");

const DEK = new Uint8Array(32).fill(0x42);
const AAD = new TextEncoder().encode("doc_abc");

describe("X25519 curve wiring (RFC 7748 KAT)", () => {
  // RFC 7748 §6.1 — proves the curve library is correct, not just
  // self-consistent.
  const aSk = hex(
    "77076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba51db92c2a",
  );
  const bPub = hex(
    "de9edb7d7b7dc1b4d35b61c2ece435373f8343c85b78674dadfc7e146f882b4f",
  );
  it("scalarmult matches the published shared secret", () => {
    expect(toHex(x25519.getPublicKey(aSk))).toBe(
      "8520f0098930a754748b7ddcb43ef75a0dbf3a0d26381af4eba4a98eaa9b4e6a",
    );
    expect(toHex(x25519.getSharedSecret(aSk, bPub))).toBe(
      "4a5d9d5ba4ce2de1728e3bf480350f25e07e21c947d19e3376f09b3c1e161742",
    );
  });
});

describe("wrapToPublicKey / unwrapWithSecretKey (ECIES)", () => {
  it("keypair shape", () => {
    const kp = generateIdentityKeyPair();
    expect(kp.publicKey).toHaveLength(X25519_KEY_BYTES);
    expect(kp.secretKey).toHaveLength(X25519_KEY_BYTES);
  });

  it("server-side wrap (public key only) → client unwrap (secret key)", async () => {
    const { publicKey, secretKey } = generateIdentityKeyPair();
    const sealed = await wrapToPublicKey(publicKey, DEK, AAD);
    expect(sealed.epk).toHaveLength(32);
    expect(await unwrapWithSecretKey(secretKey, sealed, AAD)).toEqual(DEK);
  });

  it("every wrap uses a fresh ephemeral key (ciphertext + epk differ)", async () => {
    const { publicKey } = generateIdentityKeyPair();
    const a = await wrapToPublicKey(publicKey, DEK);
    const b = await wrapToPublicKey(publicKey, DEK);
    expect(toHex(a.epk)).not.toBe(toHex(b.epk));
    expect(toHex(a.ciphertext)).not.toBe(toHex(b.ciphertext));
  });

  it("a different recipient's secret key cannot unwrap", async () => {
    const alice = generateIdentityKeyPair();
    const mallory = generateIdentityKeyPair();
    const sealed = await wrapToPublicKey(alice.publicKey, DEK);
    await expect(
      unwrapWithSecretKey(mallory.secretKey, sealed),
    ).rejects.toThrow();
  });

  it("AAD mismatch fails closed", async () => {
    const { publicKey, secretKey } = generateIdentityKeyPair();
    const sealed = await wrapToPublicKey(publicKey, DEK, AAD);
    await expect(unwrapWithSecretKey(secretKey, sealed)).rejects.toThrow();
  });

  it("rejects wrong-length keys", async () => {
    await expect(wrapToPublicKey(new Uint8Array(16), DEK)).rejects.toThrow(
      /32 bytes/,
    );
  });

  it("rejects a low-order / all-zero recipient public key (audit MED-1)", async () => {
    // All-zero is a small-subgroup point → all-zero shared secret.
    // Must fail closed with the uniform error, not a noble-internal
    // message and not a usable wrap.
    await expect(wrapToPublicKey(new Uint8Array(32), DEK)).rejects.toThrow(
      /invalid public key/,
    );
  });

  it("rejects an all-zero ephemeral key on unwrap (audit MED-1)", async () => {
    const { secretKey } = generateIdentityKeyPair();
    const forged = {
      epk: new Uint8Array(32),
      ciphertext: new Uint8Array(48),
      nonce: new Uint8Array(12),
    };
    await expect(unwrapWithSecretKey(secretKey, forged)).rejects.toThrow(
      /invalid public key/,
    );
  });
});

See also

This is the file as it lives at the moment of this build. The canonical history lives in git. If you want the full history or a specific commit, write to hello@muntin.digital.

envelope.test.ts · Verify · Muntin Ledger · Muntin