{"id":21531893,"url":"https://github.com/matrixai/js-encryptedfs","last_synced_at":"2025-07-13T21:06:40.615Z","repository":{"id":34264903,"uuid":"169530907","full_name":"MatrixAI/js-encryptedfs","owner":"MatrixAI","description":"Encrypted Filesystem for TypeScript/JavaScript Applications","archived":false,"fork":false,"pushed_at":"2025-05-29T05:34:29.000Z","size":5431,"stargazers_count":10,"open_issues_count":8,"forks_count":3,"subscribers_count":9,"default_branch":"staging","last_synced_at":"2025-06-15T04:06:29.702Z","etag":null,"topics":["encrypted-store","encryption","filesystem"],"latest_commit_sha":null,"homepage":"https://polykey.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MatrixAI.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,"zenodo":null}},"created_at":"2019-02-07T06:50:44.000Z","updated_at":"2025-05-29T05:22:10.000Z","dependencies_parsed_at":"2024-06-19T19:03:01.879Z","dependency_job_id":"f8348eef-358a-460f-b0d9-a4c53fb28d16","html_url":"https://github.com/MatrixAI/js-encryptedfs","commit_stats":{"total_commits":335,"total_committers":7,"mean_commits":"47.857142857142854","dds":0.7074626865671642,"last_synced_commit":"e6834200f62f31e40b03cdc1ddd9a51775c839cd"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/MatrixAI/js-encryptedfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-encryptedfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-encryptedfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-encryptedfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-encryptedfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatrixAI","download_url":"https://codeload.github.com/MatrixAI/js-encryptedfs/tar.gz/refs/heads/staging","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-encryptedfs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265205680,"owners_count":23727511,"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":["encrypted-store","encryption","filesystem"],"created_at":"2024-11-24T02:18:05.173Z","updated_at":"2025-07-13T21:06:40.601Z","avatar_url":"https://github.com/MatrixAI.png","language":"TypeScript","readme":"# js-encryptedfs\n\nEncrypted filesystem library for TypeScript/JavaScript applications\n\n- Virtualised - files, directories, permissions are all virtual constructs, they\n  do not correspond to real filesystems\n- Orthogonally Persistent - all writes automatically persisted\n- Encrypted-At-Rest - all persistence is encrypted\n- Random Read \u0026 Write - encryption and decryption operates over fixed-block\n  sizes\n- Streamable - files do not need to loaded fully in-memory\n- Comprehensive continuous benchmarks in CI/CD\n\nDevelopment based on js-virtualfs: https://github.com/MatrixAI/js-virtualfs\n\n## Installation\n\n```sh\nnpm install --save encryptedfs\n```\n\n## Usage\n\n```ts\nimport type { EFSWorkerModule } from 'encryptedfs';\n\nimport { WorkerManager } from '@matrixai/workers';\nimport { EncryptedFS, utils } from 'encryptedfs';\n\nconst key = utils.generateKeySync(256);\n\nconst efs = await EncryptedFS.createEncryptedFS({\n  dbPath: '/tmp/efs',\n  dbKey: key,\n});\n\n// optionally set up the worker manager for multi-threaded encryption/decryption\nconst workerManager = await WorkerManager.createWorkerManager\u003cEFSWorkerModule\u003e({\n  workerFactory: () =\u003e spawn(new Worker('./src/workers/efsWorker')),\n});\n\nefs.setWorkerManager(workerManager);\n\n// create a new directory\nconst newDir = `test`;\nawait efs.mkdir(newDir);\n\n// write out to a file\nawait efs.writeFile(`${newDir}/testFile`, 'output');\n\n// read in the file (contents = 'output')\nconst contents = await efs.readFile(`${newDir}/testFile`);\n\n// closes the EFS\nawait efs.stop();\n\n// destroys the EFS state\nawait efs.destroy();\n```\n\n### Encryption \u0026 Decryption Protocol\n\nEncryption \u0026 Decryption implemented using the `node-forge` library. However it\nis possible to plug in your own `encrypt` and `decrypt` functions.\n\nInternally we use the AES-GCM symmetric encryption using a master `dbKey` that\ncan be 128, 192 or 256 bits long.\n\nThe `dbKey` can be generated from several methods:\n\n- `generateKey` - random asynchronous\n- `generateKeySync` - random synchronous\n- `generateKeyFromPass` - derived from user-provided \"password\" asynchronous\n- `generateKeyFromPassSync` - derived from user-provided \"password\" synchronous\n\nFor example:\n\n```ts\nconst [key, salt] = await generateKeyFromPass('secure password');\n```\n\nThis uses PBKDF2 to derive a symmetric key. The default key length will be 256\nbits. For deterministic key generation, make sure to specify the `salt`\nparameter.\n\n```ts\nconst [key, salt] = await generateKeyFromPass('secure password', 'salt');\n```\n\nConstruction of `EncryptedFS` relies on an optional `blockSize` parameter. This\nis by default set to 4 KiB. All files are broken up into 4 KiB plaintext blocks.\nWhen encrypted, they are persisted as ciphertext blocks.\n\nThe ciphertext blocks contain an initialization vector plus an authorisation\ntag. Here is an example of the structure:\n\n```\n| iv (16 bytes) | authTag (16 bytes) | ciphertext data (x bytes) |\n```\n\nThe ciphertext data length is equal to the plaintext block length.\n\n### Differences with Node Filesystem\n\nThere are some differences between EFS and Node FS:\n\n- User, Group and Other permissions: In EFS User, Group and Other permissions\n  are strictly confined to their permission class. For example, a User in EFS\n  does not have the permissions that a Group or Other has while in Node FS a\n  User also has permissions that Group and Other have.\n- Sticky Files: In Node FS, a sticky bit is a permission bit that is set on a\n  file or a directory that lets only the owner of the file/directory or the root\n  user to delete or rename the file. EFS does not support the use of sticky\n  bits.\n- Character Devices: Node FS contains Character Devices which can be written to\n  and read from. However, in EFS Character Devices are not supported yet.\n\n## Development\n\nRun `nix develop`, and once you're inside, you can use:\n\n```sh\n# install (or reinstall packages from package.json)\nnpm install\n# build the dist\nnpm run build\n# run the repl (this allows you to import from ./src)\nnpm run tsx\n# run the tests\nnpm run test\n# lint the source code\nnpm run lint\n# automatically fix the source\nnpm run lintfix\n```\n\n## Benchmarks\n\n```sh\nnpm run bench\n```\n\nView benchmarks here:\nhttps://github.com/MatrixAI/js-encryptedfs/blob/master/benches/results with\nhttps://raw.githack.com/\n\n### Docs Generation\n\n```sh\nnpm run docs\n```\n\nSee the docs at: https://matrixai.github.io/js-encryptedfs/\n\n### Publishing\n\nPublishing is handled automatically by the staging pipeline.\n\nPrerelease:\n\n```sh\n# npm login\nnpm version prepatch --preid alpha # premajor/preminor/prepatch\ngit push --follow-tags\n```\n\nRelease:\n\n```sh\n# npm login\nnpm version patch # major/minor/patch\ngit push --follow-tags\n```\n\nManually:\n\n```sh\n# npm login\nnpm version patch # major/minor/patch\nnpm run build\nnpm publish --access public\ngit push\ngit push --tags\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixai%2Fjs-encryptedfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrixai%2Fjs-encryptedfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixai%2Fjs-encryptedfs/lists"}