{"id":15648104,"url":"https://github.com/perry-mitchell/iocane","last_synced_at":"2025-04-14T00:23:21.719Z","repository":{"id":49133171,"uuid":"54846314","full_name":"perry-mitchell/iocane","owner":"perry-mitchell","description":"An odorless, tasteless NodeJS crypto library that dissolves instantly in liquid","archived":false,"fork":false,"pushed_at":"2023-12-16T16:44:40.000Z","size":2409,"stargazers_count":42,"open_issues_count":2,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-27T14:22:09.703Z","etag":null,"topics":["crypto-js","decryption","encoding","encryption","hmac","nodejs","pbkdf2","security","subtlecrypto","web"],"latest_commit_sha":null,"homepage":"","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/perry-mitchell.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},"funding":{"github":["perry-mitchell"]}},"created_at":"2016-03-27T20:16:48.000Z","updated_at":"2024-10-11T22:32:19.000Z","dependencies_parsed_at":"2024-10-03T12:23:38.583Z","dependency_job_id":"1d0d93fa-c518-42c1-bff8-a00efa62d7dd","html_url":"https://github.com/perry-mitchell/iocane","commit_stats":{"total_commits":274,"total_committers":5,"mean_commits":54.8,"dds":0.06934306569343063,"last_synced_commit":"d70fc2aa2fb0b6ce8a99971a73b8c52b84670864"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fiocane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fiocane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fiocane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fiocane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perry-mitchell","download_url":"https://codeload.github.com/perry-mitchell/iocane/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248359967,"owners_count":21090627,"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":["crypto-js","decryption","encoding","encryption","hmac","nodejs","pbkdf2","security","subtlecrypto","web"],"created_at":"2024-10-03T12:23:31.537Z","updated_at":"2025-04-14T00:23:21.430Z","avatar_url":"https://github.com/perry-mitchell.png","language":"TypeScript","readme":"![iocane](https://raw.githubusercontent.com/perry-mitchell/iocane/master/iocane_header.jpg)\n\nA powerful and easy-to-use **text** and **data** encryption library for **NodeJS** and the **web**.\n\n[![Buttercup](https://cdn.rawgit.com/buttercup-pw/buttercup-assets/6582a033/badge/buttercup-slim.svg)](https://buttercup.pw) [![Downloads per month on NPM](https://img.shields.io/npm/dm/iocane.svg?maxAge=2592000)](https://www.npmjs.com/package/iocane/) [![npm version](https://badge.fury.io/js/iocane.svg)](https://www.npmjs.com/package/iocane/)\n\n## About\n\niocane makes text and data encryption and decryption easy by bundling all the complicated processes into one succinct library. Encrypt and decrypt **strings** and **buffers** easily by using iocane's encryption format - string-\u003estring / buffer-\u003ebuffer. Encrypt and decrypt **streams** in NodeJS.\n\nThis library uses \"sessions\" for encryption and decryption. A session describes one encryption/decryption action, and can also have options be further overridden at the time of execution. Check the examples below for a better idea of how this process works.\n\niocane works in the browser, too. Both a **node version** and a **web version** are available:\n\n```javascript\nconst iocane = require(\"iocane\"); // node\n```\n\n```javascript\nimport * as iocane from \"iocane/web\" // web\n```\n\n### Features\n\n**iocane** by default boasts the following features:\n\n * AES-CBC / AES-GCM encryption:\n   * Text\n   * Buffers\n   * Streams _(only in NodeJS)_\n * 256bit keys\n * PBKDF2 key derivation (with 250k/custom iterations)\n * 35KB minified web version (10KB gzipped)\n * Overridable encryption/derivation/packing functionality to allow for adaptation to yet-unsupported environments\n\n## Installation\n\nInstall `iocane` as a dependency using `npm`:\n\n```shell\nnpm install iocane --save\n```\n\n## Usage\n\n**iocane** can be easily used to encrypt text:\n\n```typescript\nimport { createAdapter } from \"iocane\";\n\ncreateAdapter()\n    .encrypt(\"some secret text\", \"myPassword\")\n    .then(encryptedString =\u003e {\n        // do something with the encrypted text\n    });\n```\n\nDecryption is even simpler, as instructions on _how_ to decrypt the payload is included in the payload itself:\n\n```typescript\nimport { createAdapter } from \"iocane\";\n\ncreateAdapter()\n    .decrypt(encryptedString, \"myPassword\")\n    .then(decryptedString =\u003e {\n        // ...\n    });\n```\n\nDuring encryption, you can override a variety of options:\n\n```typescript\nimport { EncryptionAlgorithm, createAdapter } from \"iocane\";\n\nconst encrypted = await createAdapter()\n    .setAlgorithm(EncryptionAlgorithm.GCM) // use GCM encryption\n    .setDerivationRounds(300000)\n    .encrypt(target, password);\n```\n\nEach cryptographic function can be overridden by simply replacing it on the adapter\n\n```typescript\nimport { createAdapter } from \"iocane\";\n\nconst adapter = createAdapter();\nadapter.deriveKey = async (password: string, salt: string) =\u003e { /* ... */ };\n\nawait adapter.encrypt(/* ... */);\n```\n\n_Note that the default encryption mode is `EncryptionAlgorithm.CBC` (AES-CBC encryption)._\n\n### Encrypting and decrypting data buffers\n\nIocane can handle buffers the same way it handles strings - just pass them into the same encrypt/decrypt functions:\n\n```typescript\nimport { createAdapter } from \"iocane\";\nimport fs from \"fs\";\n\ncreateAdapter()\n    .setAlgorithm(EncryptionAlgorithm.CBC)\n    .encrypt(fs.readFileSync(\"./test.bin\"), \"passw0rd\")\n    .then(data =\u003e fs.writeFileSync(\"./test.bin.enc\", data));\n```\n\n_The same can be performed on the web, with array buffers in place of standard buffers._\n\n### Encrypting and decrypting using streams\n\n_Available on the Node version only._\n\nIocane can create encryption and decryption streams, which is very useful for encrypting large amounts of data:\n\n```typescript\nimport { createAdapter } from \"iocane\";\nimport fs from \"fs\";\nimport zlib from \"zlib\";\n\n// Encrypt\nfs\n    .createReadStream(\"/my-file.dat\")\n    .pipe(zlib.createGzip())\n    .pipe(createAdapter().createEncryptStream(\"passw0rd\"))\n    .pipe(fs.createWriteStream(\"/destination.dat.enc\"));\n\n// Decrypt\nfs\n    .createReadStream(\"/destination.dat.enc\")\n    .pipe(createAdapter().createDecryptStream(\"passw0rd\"))\n    .pipe(zlib.createGunzip())\n    .pipe(fs.createWriteStream(\"/my-file-restored.dat\"));\n```\n\n### Web usage\n\nWhen building a project for the web, make sure to use the web-based version of iocane. Bundling the node version will create super-large bundles and result in slow encryption and decryption. iocane for the web uses UMD so it can be imported or simply loaded straight in the browser as a `\u003cscript\u003e`.\n\nIf you load iocane directly in the browser, it will create a global namespace at `window.iocane` (eg. `window.iocane.createAdapter`).\n\n## Supported environments\n\niocane supports NodeJS version 10 and above. Node 8 was supported in `3.x` and versions prior to 8 were supported in `1.x`.\n\niocane is used in the browser as well - it works everywhere that `SubtleCrypto`, `ArrayBuffer` and `Promise` are available.\n\n_Note: iocane is written in TypeScript, though versions before v2 were written in JavaScript._\n\n## Buttercup\n\niocane was originally part of the [Buttercup](https://github.com/buttercup) suite. Buttercup is a supported dependent of iocane and efforts are made to align iocane with Buttercup's target platforms and uses.\n","funding_links":["https://github.com/sponsors/perry-mitchell"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fiocane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperry-mitchell%2Fiocane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fiocane/lists"}