# @meeco/cryppo

> In-browser encryption and decryption. Clone of Ruby Cryppo

Latest version **4.0.0** (published 2026-08-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @meeco/cryppo
pnpm add @meeco/cryppo
yarn add @meeco/cryppo
bun add @meeco/cryppo
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2026-08-25 |
| First published | 2020-03-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.0.0 |
| Dependencies | 3 |
| Unpacked size | 223.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Meeco |
| Maintainers | janvereecken-meeco, dmunneke-meeco, linasisganaitis-meeco, meeco-ci, vshiyani |
| Keywords | encryption, cryppo, decryption, rsa, pbkdf2, aes, aes-256 |

## Links

- npm: https://www.npmjs.com/package/@meeco/cryppo
- Repository: https://github.com/Meeco/cryppo-js
- Homepage: https://github.com/Meeco/cryppo-js#readme
- Issues: https://github.com/Meeco/cryppo-js/issues
- npm.io page: https://npm.io/package/@meeco/cryppo

## Dependencies (3)

- [bson](https://npm.io/package/bson.md) ^7.2.0
- [yaml](https://npm.io/package/yaml.md) ^2.8.2
- [buffer](https://npm.io/package/buffer.md) ^6.0.3

## Alternatives

- [@gemini-wallet/core](https://npm.io/package/@gemini-wallet/core.md) — 515.6K weekly downloads
- [utility](https://npm.io/package/utility.md) — 416.6K weekly downloads
- [@primno/dpapi](https://npm.io/package/@primno/dpapi.md) — 7.2K weekly downloads
- [pi-readseek](https://npm.io/package/pi-readseek.md) — 3.7K weekly downloads
- [@emilia-protocol/verify](https://npm.io/package/@emilia-protocol/verify.md) — 1.1K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2026-08-25
- 0.8.0-beta (beta) — 2020-09-17
- 3.0.2 — 2026-08-14
- 3.0.1 — 2026-03-07
- 3.0.0 — 2026-02-16
- 2.0.2 — 2021-03-31
- 2.0.1 — 2021-03-30
- 2.0.0 — 2021-01-08
- 2.0.0-beta.10 — 2021-01-05
- 2.0.0-beta.7 — 2021-01-05
- 2.0.0-beta.5 — 2020-12-24
- 2.0.0-beta.4 — 2020-12-21
- 2.0.0-beta.3 — 2020-12-21
- 2.0.0-beta.2 — 2020-12-17
- 2.0.0-beta.0 — 2020-12-17
- … 13 more at https://npm.io/package/@meeco/cryppo/versions

## README

# Cryppo JS

TypeScript version of [Cryppo](https://github.com/Meeco/cryppo) allowing easy encryption/decryption for [Meeco](https://dev.meeco.me) 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](https://developer.mozilla.org/en-US/docs/Web/API/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](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)/[caniuse](https://caniuse.com/cryptography), 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://developer.mozilla.org/en-US/docs/Web/Security/Defenses/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](https://claude.com/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](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`

```ts
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.

```ts
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`

```ts
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
1. Use the public key to encrypt
1. Decrypt with private key

```ts
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`

```ts
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

---
_Source: https://npm.io/package/@meeco/cryppo · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._