Cryppo JS

TypeScript version of Cryppo allowing easy encryption/decryption for Meeco in the browser or node.

Works in both Node.js and the browser — a small polyfill in src/index.ts sets up Buffer/global on window so no manual polyfilling is needed when bundling for the browser (e.g. in Angular).

Requirements

• Node.js >=22.0.0 — comfortably above the >=19.0.0 (October 2022) this library's use of crypto.subtle as a global actually needs (unflagged and stable there); the >=22 requirement predates this and isn't specific to WebCrypto.
• In the browser: the Web Crypto API (crypto.subtle), which this library uses directly for every cryptographic operation. Support for it is essentially universal in browsers actually in use today — per MDN/caniuse, it only excludes browsers that are a decade or more old:
  • Chrome/Edge (Chromium) >=37 (August 2014), Firefox >=34 (December 2014)
  • Safari (desktop) >=11 (September 2017)
  • iOS Safari >=11 (September 2017) — this applies to all iOS browsers, since they all share WebKit/Safari's engine
  • Android >=5.0 "Lollipop" (November 2014), via Chrome for Android or a reasonably up-to-date WebView
  • Not supported: Internet Explorer (its msCrypto implementation predates Promises)
  • It's also only available in secure contexts (HTTPS, or localhost) — routine for any modern web app.

Installation

npm install @meeco/cryppo

Upgrading from v3 to v4

v4 replaced node-forge with native WebCrypto — see the CHANGELOG.md 4.0.0 entry for what changed. If you use Claude Code, this package ships a skill that automates most of the mechanical parts of the upgrade (adding await at now-async call sites, flagging removed password-protected-key usage for manual review): copy node_modules/@meeco/cryppo/.claude/skills/cryppo-migrate-v3-to-v4/ into your own project's .claude/skills/, then ask Claude to "migrate to cryppo v4".

Run the demo page

• npm install
• npm run demo (alias for npm start)

Will run the project in demo/ using Vite. Visit http://localhost:5173 to show a small UI demonstrating encryption/decryption with a derived key, with a generated key, and with an RSA signature.

Encrypting Data (Symmetric Key Encryption)

The public facing API is designed to make it as easy as possible to encrypt some data with a key.

If you want to encrypt with an arbitrary string as a key:

You can do so using encryptWithKeyDerivedFromString. This will return the serialized encrypted data along with some information about the encryption (such as key derivation information). encryptWithKeyDerivedFromString and encryptWithGeneratedKey have two serialization formats: a legacy format and a more efficient current format. current format is default format, In order to serialize a structure using the old format please use SerializationFormat.legacy

async function encryptData() {
  const result = await encryptWithKeyDerivedFromString({
    passphrase: 'Password123!',
    data: utf8ToBytes('My Secret Data'),
    strategy: CipherStrategy.AES_GCM,
    serializationVersion: SerializationFormat.latest_version,
  });
  console.log(result.serialized);
}

If you want to encrypt with a randomly generated key

You can do so using encryptWithGeneratedKey. This will return the generated key.

async function encryptData() {
  const result = await encryptWithGeneratedKey(
    {
      data: utf8ToBytes('My Secret Data'),
      strategy: CipherStrategy.AES_GCM,
    },
    SerializationFormat.latest_version
  );
  console.log(result.serialized);
  console.log(result.generatedKey.serialize);
}

If you want to encrypt with an existing key that is of the required length for the given strategy

You can do so using encryptWithKey

async function encryptData() {
  const result = await encryptWithKey(
    {
      key: EncryptionKey.generateRandom(),
      data: utf8ToBytes('This is some test data that will be encrypted'),
      strategy: CipherStrategy.AES_GCM,
    },
    SerializationFormat.latest_version
  );
  console.log(result.serialized);
}

Encrypting Data (Asymmetric Key Encryption)

1. Generate a new key pair
2. Use the public key to encrypt
3. Decrypt with private key

import { generateRSAKeyPair, encryptWithPublicKey, decryptWithPrivateKey } from '@meeco/cryppo';

async function encryptDecryptData() {
  const { publicKey: publicKeyPem, privateKey: privateKeyPem } = await generateRSAKeyPair();

  // Note: unlike the symmetric encryption functions above, `data` here is a plain string, not a Uint8Array
  const { encrypted, serialized } = await encryptWithPublicKey({
    publicKeyPem,
    data: 'My Super Secret Data',
  });

  const decryptedData = await decryptWithPrivateKey({
    privateKeyPem,
    encrypted,
  });
  console.log(decryptedData); // 'My Super Secret Data'
}

serialized is the portable string form (as produced by the symmetric functions above); to decrypt from that directly, use decryptSerializedWithPrivateKey({ privateKeyPem, serialized }) instead of extracting encrypted yourself.

Decryption

If you have a serialized encrypted payload

Note: cryppo will use a derived key or the provided key and correct SerializationFormat based on the structure of the serialized data.

Call decryptWithKeyDerivedFromString

async function decryptData() {
  const decrypted = await decryptWithKeyDerivedFromString({
    serialized: `Aes256Gcm.J9YhaGdIUBKa2dULbMU=.LS0tCml2OiAhYmluYXJ5IHwtCiAgd1JGK2QrRjYzRHJhbDRmdgphdDogIWJpbmFyeSB8LQogIGllS3JnK05iV0JVY2N3L3VVS2N6Rnc9PQphZDogbm9uZQo=.Pbkdf2Hmac.LS0tCml2OiAitIb79btSrS8k4KhbyfR_f79OkukiCmk6IDIxOTQ5Cmw6IDMyCmhhc2g6IFNIQTI1Ngo=`,
    passphrase: 'Password123!',
  });
  console.log(bytesToUtf8(decrypted!));
  // 'My Secret Data'
}

Serialization Format

The serialization format of encrypted data is designed to be easy to parse and store.

There are two serialization formats:

• Encrypted data encrypted without a derived key
• Encrypted data encrypted with a derived key

Encrypted data encrypted without a derived key

A string containing 3 parts concatenated with a ..

1. Encryption Strategy Name: The strategy name as defined by EncryptionStrategy#strategy_name
2. Encoded Encrypted Data: Encrypted Data is encoded with Base64.urlsafe_encode64
3. Encoded Encryption Artefacts: Encryption Artefacts are serialized into a hash by EncryptionStrategy#serialize_artefact, converted to YAML for legacy & BSON for latest_version, then encoded with Base64.urlsafe_encode64

Encrypted data encrypted with a derived key

A string containing 5 parts concatenated with a .. The first 3 parts are the same as above.

4. Key Derivation Strategy Name: The strategy name as defined by EncryptionStrategy#strategy_name
5. Encoded Key Derivation Artefacts: Encryption Artefacts are serialized into a hash by EncryptionStrategy#serialize_artefact, converted to YAML for legacy & BSON for latest_version, then encoded with Base64.urlsafe_encode64

Other exports

Beyond symmetric/asymmetric encryption shown above, @meeco/cryppo also exports:

• Signing — signWithPrivateKey, verifyWithPublicKey, loadRsaSignature (see src/signing/rsa-signature.ts) for RSA signatures, using key pairs from generateRSAKeyPair.
• HMAC digests — helpers in src/digests/hmac-digest.ts.
• Key derivation — lower-level PBKDF2-HMAC helpers (src/key-derivation/pbkdf2-hmac.ts, src/key-derivation/derived-key.ts) if you need to derive/manage keys without going through the encryption functions directly.
• Encoding/serialization utilities — encode64/decode64, utf8ToBytes/bytesToUtf8, utf16ToBytes/bytesToUtf16, binaryStringToBytes/bytesToBinaryString, serialize/deSerialize, and related helpers (see src/util.ts).

See src/index.ts for the full list of public exports.

License

MIT