{"id":18676959,"url":"https://github.com/ecies/js","last_synced_at":"2025-05-15T11:09:27.783Z","repository":{"id":33552212,"uuid":"159298440","full_name":"ecies/js","owner":"ecies","description":"Elliptic Curve Integrated Encryption Scheme for secp256k1/curve25519 in TypeScript","archived":false,"fork":false,"pushed_at":"2025-05-08T09:16:11.000Z","size":1556,"stargazers_count":147,"open_issues_count":2,"forks_count":15,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-08T10:27:05.772Z","etag":null,"topics":["bitcoin","cryptocurrency","cryptography","ecies","elliptic-curve-cryptography","ethereum","javascript","secp256k1","typescript"],"latest_commit_sha":null,"homepage":"https://ecies.org/js","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ecies.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"kigawas"}},"created_at":"2018-11-27T08:05:26.000Z","updated_at":"2025-05-08T09:14:59.000Z","dependencies_parsed_at":"2024-05-01T08:30:00.381Z","dependency_job_id":"03693f4a-f649-4ace-843f-1533a4990a15","html_url":"https://github.com/ecies/js","commit_stats":{"total_commits":576,"total_committers":7,"mean_commits":82.28571428571429,"dds":0.6024305555555556,"last_synced_commit":"13905edb3606ad66f481c688ae5c8140f42938a0"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecies%2Fjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecies%2Fjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecies%2Fjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecies%2Fjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecies","download_url":"https://codeload.github.com/ecies/js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328386,"owners_count":22052632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","cryptocurrency","cryptography","ecies","elliptic-curve-cryptography","ethereum","javascript","secp256k1","typescript"],"created_at":"2024-11-07T09:31:53.835Z","updated_at":"2025-05-15T11:09:27.750Z","avatar_url":"https://github.com/ecies.png","language":"TypeScript","readme":"# eciesjs\n\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/47784cde956642b1b9e8e33cb8551674)](https://app.codacy.com/app/ecies/js)\n[![License](https://img.shields.io/github/license/ecies/js.svg)](https://github.com/ecies/js)\n[![NPM Package](https://img.shields.io/npm/v/eciesjs.svg)](https://www.npmjs.com/package/eciesjs)\n[![NPM Downloads](https://img.shields.io/npm/dm/eciesjs)](https://npm-stat.link/eciesjs)\n[![Bundle size](https://badgen.net/bundlephobia/minzip/eciesjs)](https://bundlephobia.com/package/eciesjs@latest)\n[![CI](https://img.shields.io/github/actions/workflow/status/ecies/js/ci.yml)](https://github.com/ecies/js/actions)\n[![Codecov](https://img.shields.io/codecov/c/github/ecies/js.svg)](https://codecov.io/gh/ecies/js)\n\nElliptic Curve Integrated Encryption Scheme for secp256k1/curve25519 in TypeScript.\n\nThis is the JavaScript/TypeScript version of [eciespy](https://github.com/ecies/py) with a built-in class-like secp256k1/curve25519 [API](#privatekey).\n\nYou can learn the details in [DETAILS.md](./DETAILS.md).\n\n## Install\n\n```bash\nnpm install eciesjs\n```\n\nWe recommend using the latest Node runtime although it's still possible to install on old versions (as long as 16+).\n\nFor security, see [Security](#security).\n\n## Quick Start\n\n```typescript\nimport { PrivateKey, decrypt, encrypt } from \"eciesjs\";\n\nconst sk = new PrivateKey();\nconst data = Buffer.from(\"hello world🌍\");\nconst decrypted = decrypt(sk.secret, encrypt(sk.publicKey.toBytes(), data));\nconsole.log(Buffer.from(decrypted).toString());\n```\n\nOr run the example code:\n\n```bash\n$ pnpm install \u0026\u0026 pnpm build \u0026\u0026 cd example/runtime \u0026\u0026 pnpm install \u0026\u0026 node main.js\nhello world🌍\n```\n\nSee [Configuration](#configuration) to control with more granularity.\n\nThis library also supports multiple platforms (browser, node, bun/deno, react native), see [Multi-platform Support](#multi-platform-support).\n\n## Sponsors\n\n\u003ca href=\"https://dotenvx.com\"\u003e\u003cimg alt=\"dotenvx\" src=\"https://dotenvx.com/logo.png\" width=\"200\" height=\"200\"/\u003e\u003c/a\u003e\n\n## API\n\n### `encrypt(receiverRawPK: string | Uint8Array, data: Uint8Array): Buffer`\n\nParameters:\n\n- **receiverRawPK** - Receiver's public key, hex `string` or `Uint8Array`\n- **data** - Data to encrypt\n\nReturns: **Buffer**\n\n### `decrypt(receiverRawSK: string | Uint8Array, data: Uint8Array): Buffer`\n\nParameters:\n\n- **receiverRawSK** - Receiver's private key, hex `string` or `Uint8Array`\n- **data** - Data to decrypt\n\nReturns: **Buffer**\n\n### `PrivateKey`\n\n- Methods\n\n```typescript\nstatic fromHex(hex: string, curve?: EllipticCurve): PrivateKey;\nconstructor(secret?: Uint8Array, curve?: EllipticCurve);\ntoHex(): string;\nencapsulate(pk: PublicKey, compressed?: boolean): Uint8Array;\nmultiply(pk: PublicKey, compressed?: boolean): Uint8Array;\nequals(other: PrivateKey): boolean;\n```\n\n- Properties\n\n```typescript\nget secret(): Buffer;\nreadonly publicKey: PublicKey;\n```\n\n### `PublicKey`\n\n- Methods\n\n```typescript\nstatic fromHex(hex: string, curve?: EllipticCurve): PublicKey;\nconstructor(data: Uint8Array, curve?: EllipticCurve);\ntoBytes(compressed?: boolean): Uint8Array;\ntoHex(compressed?: boolean): string;\ndecapsulate(sk: PrivateKey, compressed?: boolean): Uint8Array;\nequals(other: PublicKey): boolean;\n```\n\n- Properties\n\n```typescript\n/** @deprecated - use `PublicKey.toBytes(false)` instead. You may also need `Buffer.from`. */\nget uncompressed(): Buffer;\n/** @deprecated - use `PublicKey.toBytes()` instead. You may also need `Buffer.from`. */\nget compressed(): Buffer;\n```\n\n## Configuration\n\nFollowing configurations are available.\n\n- Elliptic curve: secp256k1 or curve25519 (x25519/ed25519)\n- Ephemeral key format in the payload: compressed or uncompressed (only for secp256k1)\n- Shared elliptic curve key format in the key derivation: compressed or uncompressed (only for secp256k1)\n- Symmetric cipher algorithm: AES-256-GCM or XChaCha20-Poly1305\n- Symmetric nonce length: 12 or 16 bytes (only for AES-256-GCM)\n\nFor compatibility, make sure different applications share the same configuration.\n\n```ts\nexport type EllipticCurve = \"secp256k1\" | \"x25519\" | \"ed25519\";\nexport type SymmetricAlgorithm = \"aes-256-gcm\" | \"xchacha20\";\nexport type NonceLength = 12 | 16;\n\nclass Config {\n  ellipticCurve: EllipticCurve = \"secp256k1\";\n  isEphemeralKeyCompressed: boolean = false;\n  isHkdfKeyCompressed: boolean = false;\n  symmetricAlgorithm: SymmetricAlgorithm = \"aes-256-gcm\";\n  symmetricNonceLength: NonceLength = 16;\n}\n\nexport const ECIES_CONFIG = new Config();\n```\n\n### Elliptic curve configuration\n\nOn `ellipticCurve = \"x25519\"` or `ellipticCurve = \"ed25519\"`, x25519 (key exchange function on curve25519) or ed25519 (signature algorithm on curve25519) will be used for key exchange instead of secp256k1.\n\nIn this case, the payload would always be: `32 Bytes + Ciphered` regardless of `isEphemeralKeyCompressed`.\n\n\u003e If you don't know how to choose between x25519 and ed25519, just use the dedicated key exchange function x25519 for efficiency.\n\u003e\n\u003e Because any 32-byte data is a valid curve25519 public key, the payload would seem random. This property is excellent for circumventing censorship by adversaries.\n\n### Secp256k1-specific configuration\n\nOn `isEphemeralKeyCompressed = true`, the payload would be: `33 Bytes + Ciphered` instead of `65 Bytes + Ciphered`.\n\nOn `isHkdfKeyCompressed = true`, the hkdf key would be derived from `ephemeral public key (compressed) + shared public key (compressed)` instead of `ephemeral public key (uncompressed) + shared public key (uncompressed)`.\n\n### Symmetric cipher configuration\n\nOn `symmetricAlgorithm = \"xchacha20\"`, plaintext data would be encrypted with XChaCha20-Poly1305.\n\nOn `symmetricNonceLength = 12`, the nonce of AES-256-GCM would be 12 bytes. XChaCha20-Poly1305's nonce is always 24 bytes regardless of `symmetricNonceLength`.\n\n### Which configuration should I choose?\n\nFor compatibility with other [ecies libraries](https://github.com/orgs/ecies/repositories), start with the default (secp256k1 with AES-256-GCM).\n\nFor speed and security, pick x25519 with XChaCha20-Poly1305.\n\nIf you know exactly what you are doing, configure as you wish or build your own ecies logic with this library.\n\n## Multi-platform Support\n\n|              | Fully Supported |\n| ------------ | --------------- |\n| Node         | ✅              |\n| Bun          | ✅              |\n| Deno         | ⚠️ (only aes)   |\n| Browser      | ✅              |\n| React Native | ✅              |\n\nVia [`@ecies/ciphers`](https://github.com/ecies/js-ciphers), `node:crypto`'s native implementation of AES-256-GCM and XChaCha20-Poly1305 is chosen if available.\n\n### Browser\n\nThis library is browser-friendly, check the [`example/browser`](./example/browser) directory for details. The online demo is hosted [here](https://js-demo.ecies.org/).\n\nCurrently it's necessary to polyfill `Buffer` for backward compatibility. From v0.5.0, it can run in browsers as is.\n\nIf you want a WASM version to run directly in modern browsers or on some blockchains, you can also try [`ecies-wasm`](https://github.com/ecies/rs-wasm).\n\n### Bun/Deno\n\nFor bun/deno, see [`example/runtime`](./example/runtime). There are some limitations currently, mentioned in [`@ecies/ciphers`](https://github.com/ecies/js-ciphers#known-limitations):\n\n- `chacha20-poly1305`'s pure JS implementation is used on bun (`node:crypto`'s `chacha20-poly1305` is not available due to lack of implementation);\n- `chacha20-poly1305` does not work on deno. If you found such a problem, try to upgrade deno to the latest version (no guarantee whether it works though).\n\n### React Native\n\nSee the [React Native demo](https://github.com/ecies/js-rn-demo).\n\n## Security\n\nTo mitigate security risks, such as [supply chain attacks](https://slowmist.medium.com/supply-chain-attack-on-ledger-connect-kit-analyzing-the-impact-and-preventive-measures-1005e39422fd) and zero-day [vulnerabilities](https://github.com/advisories/GHSA-vjh7-7g9h-fjfh), we only use `node:crypto` and these audited dependencies:\n\n- [noble-curves](https://github.com/paulmillr/noble-curves#security)\n- [noble-hashes](https://github.com/paulmillr/noble-hashes#security)\n- [noble-ciphers](https://github.com/paulmillr/noble-ciphers#security)\n\nEvery release is built on GitHub Actions with [provenance](https://www.npmjs.com/package/eciesjs#provenance).\n\nThis library is fully auditable as well. We're seeking funding for a professional third-party security audit to verify implementation and identify potential vulnerabilities.\n\nIf you rely on this library or value secure open-source cryptography, please consider [donating](https://github.com/sponsors/kigawas) to help fund this audit.\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md).\n","funding_links":["https://github.com/sponsors/kigawas"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecies%2Fjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecies%2Fjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecies%2Fjs/lists"}