{"id":20632149,"url":"https://github.com/vladimiry/fs-json-store-encryption-adapter","last_synced_at":"2025-10-27T10:02:23.988Z","repository":{"id":27284643,"uuid":"113207155","full_name":"vladimiry/fs-json-store-encryption-adapter","owner":"vladimiry","description":"Encryption adapter for https://github.com/vladimiry/fs-json-store","archived":false,"fork":false,"pushed_at":"2024-12-16T08:41:12.000Z","size":771,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T23:51:14.625Z","etag":null,"topics":["adapter","aes-256","argon2","buffer","encryption","key-derivation","pbkdf2","preset","sodium"],"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/vladimiry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2017-12-05T16:36:19.000Z","updated_at":"2024-08-25T13:31:58.000Z","dependencies_parsed_at":"2024-06-16T11:24:46.605Z","dependency_job_id":"dc991a38-b637-4503-a1ea-00c755cc3008","html_url":"https://github.com/vladimiry/fs-json-store-encryption-adapter","commit_stats":{"total_commits":62,"total_committers":3,"mean_commits":"20.666666666666668","dds":0.4193548387096774,"last_synced_commit":"1e901380c9751fcb873d7584750a7b6bcdd92770"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimiry%2Ffs-json-store-encryption-adapter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimiry%2Ffs-json-store-encryption-adapter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimiry%2Ffs-json-store-encryption-adapter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimiry%2Ffs-json-store-encryption-adapter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vladimiry","download_url":"https://codeload.github.com/vladimiry/fs-json-store-encryption-adapter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248519545,"owners_count":21117761,"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":["adapter","aes-256","argon2","buffer","encryption","key-derivation","pbkdf2","preset","sodium"],"created_at":"2024-11-16T14:15:06.011Z","updated_at":"2025-10-06T01:13:02.555Z","avatar_url":"https://github.com/vladimiry.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fs-json-store-encryption-adapter\n\nis an encryption adapter for the [fs-json-store](https://github.com/vladimiry/fs-json-store) module.\n\n[![GitHub Actions CI](https://github.com/vladimiry/fs-json-store-encryption-adapter/workflows/GitHub%20Actions%20CI/badge.svg?branch=master)](https://github.com/vladimiry/fs-json-store-encryption-adapter/actions)\n\n## Features\n- Predefined presets.\n- Switching between built-in node's `crypto` and `libsodium` (like Argon2 key derivation function) implementations.\n- Keeping all the needed options in the produced buffer in along with the encrypted data itself.\n- Random `salting` is enabled for every key derivation and encryption execution, which helps against the lookup tables and rainbow tables hash cracking attacks.\n\n## Implementation Notes\n- Module executes a native [libsodium](https://github.com/jedisct1/libsodium) code with help of the [sodium-native](https://github.com/sodium-friends/sodium-native) bindings library. It's supposed to work faster than the WebAssembly versions.\n- Module can be used as a general purpose `Buffer` encryption library, adapter simply implements the following interface:\n```typescript\nexport interface Adapter {\n    write(data: Buffer): Promise\u003cBuffer\u003e;\n    read(data: Buffer): Promise\u003cBuffer\u003e;\n}\n```\n\n## Supported Presets\n\n### `key derivation`\n- **`type`**: `sodium.crypto_pwhash`\n  - **`preset`**: `mode:interactive|algorithm:default` - default algorithm as for now is `Argon2id`.\n  - **`preset`**: `mode:moderate|algorithm:default`\n  - **`preset`**: `mode:sensitive|algorithm:default`\n- **`type`**: `pbkdf2`\n  - **`preset`**: `mode:interactive|digest:sha256`\n  - **`preset`**: `mode:moderate|digest:sha256`\n  - **`preset`**: `mode:sensitive|digest:sha256`\n\n### `encryption`\n- **`type`**: `sodium.crypto_secretbox_easy`\n  - **`preset`**: `algorithm:default`\n- **`type`**: `crypto`\n  - **`preset`**: `algorithm:aes-256-cbc`\n\nYou should not rely on the `types / presets` respective inner values, but only on the `types / presets` names listed above. Presets values can be changed in the code in any time (for example, increasing key derivation work factor), but that won't break the decryption of the previously encrypted data since adapter stores all the encryption options in the same buffer and so decryption can be reproduced even if values of the presets have been changed in the code with new module release.\n\n## Usage Examples\n\nUsing TypeScript and async/await:\n\n```typescript\nimport {Model, Store} from \"fs-json-store\";\nimport {EncryptionAdapter} from \"fs-json-store-encryption-adapter\";\n\ninterface DataModel extends Partial\u003cModel.StoreEntity\u003e {\n    someProperty: string;\n}\n\nconst password = process.env.STORE_PASSWORD;\n\nif (!password) {\n    throw new Error(\"Empty password is not allowed\");\n}\n\n// data file example\n(async () =\u003e {\n    const store = new Store\u003cDataModel\u003e({\n        file: \"./data.bin\",\n        adapter: new EncryptionAdapter({\n            password,\n            preset: {\n                keyDerivation: {type: \"sodium.crypto_pwhash\", preset: \"mode:interactive|algorithm:default\"},\n                encryption: {type: \"sodium.crypto_secretbox_easy\", preset: \"algorithm:default\"},\n            },\n        }),\n    });\n    const data = await store.write({someProperty: \"super secret data\"}); // writes encrypted data into the `./data.bin` file\n    console.log(data); // prints stored data\n    console.log(await store.read()); // reads and prints stored data\n})();\n\n// standalone example using default options\n(async () =\u003e {\n    const adapter = EncryptionAdapter.default({password});\n    const dataBuffer = Buffer.from(\"super secret data\");\n    const encryptedDataBuffer = await adapter.write(dataBuffer);\n    const decryptedDataBuffer = await adapter.read(encryptedDataBuffer);\n    console.log(decryptedDataBuffer.toString()); // prints `super secret data`\n})();\n```\n\nUsing JavaScript and Promises:\n\n```javascript\nconst {Store} = require(\"fs-json-store\");\nconst {EncryptionAdapter} = require(\"fs-json-store-encryption-adapter\");\n\nconst password = process.env.STORE_PASSWORD;\n\nif (!password) {\n    throw new Error(\"Empty password is not allowed\");\n}\n\n\n// data file example\n(() =\u003e {\n    const store = new Store({\n        file: \"./data.bin\",\n        adapter: new EncryptionAdapter({\n            password,\n            preset: {\n                keyDerivation: {type: \"pbkdf2\", preset: \"mode:interactive|digest:sha256\"},\n                encryption: {type: \"sodium.crypto_secretbox_easy\", preset: \"algorithm:default\"},\n            },\n        }),\n    });\n\n    store\n        .write({someProperty: \"super secret data\"}) // writes encrypted data into the `./data.bin` file\n        .then((data) =\u003e console.log(data)) // prints stored data\n        .then(() =\u003e store.read()) // reads stored data\n        .then(console.log); // prints stored data\n})();\n\n// standalone example using default options\n(() =\u003e {\n    const adapter = EncryptionAdapter.default({password});\n\n    adapter\n        .write(Buffer.from(\"super secret data\"))\n        .then((encryptedDataBuffer) =\u003e adapter.read(encryptedDataBuffer))\n        .then((decryptedDataBuffer) =\u003e console.log(decryptedDataBuffer.toString())); // prints `super secret data`\n})();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladimiry%2Ffs-json-store-encryption-adapter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvladimiry%2Ffs-json-store-encryption-adapter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladimiry%2Ffs-json-store-encryption-adapter/lists"}