{"id":22355562,"url":"https://github.com/zbo14/passworld","last_synced_at":"2025-03-26T13:12:45.323Z","repository":{"id":44102409,"uuid":"147902004","full_name":"zbo14/passworld","owner":"zbo14","description":"A library and CLI to encrypt/decrypt files and directories with passwords.","archived":false,"fork":false,"pushed_at":"2022-12-30T18:19:00.000Z","size":394,"stargazers_count":1,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-18T11:12:53.011Z","etag":null,"topics":["encryption"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/zbo14.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}},"created_at":"2018-09-08T04:48:58.000Z","updated_at":"2020-09-22T02:06:39.000Z","dependencies_parsed_at":"2023-01-31T12:50:11.989Z","dependency_job_id":null,"html_url":"https://github.com/zbo14/passworld","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbo14%2Fpassworld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbo14%2Fpassworld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbo14%2Fpassworld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbo14%2Fpassworld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zbo14","download_url":"https://codeload.github.com/zbo14/passworld/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245659051,"owners_count":20651525,"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":["encryption"],"created_at":"2024-12-04T14:07:14.367Z","updated_at":"2025-03-26T13:12:45.287Z","avatar_url":"https://github.com/zbo14.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# passworld\n\nA library and CLI to encrypt/decrypt files and directories with passwords.\n\n## How does it work?\n\nFirst, you tell `passworld` what you want to encrypt and give it a password. It uses [scrypt](https://en.wikipedia.org/wiki/Scrypt) to derive two keys from your password. It encrypts your file or directory with the first key using [secretbox](http://nacl.cr.yp.to/secretbox.html). Then it encrypts the result from the previous step with the second key using [AES-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode). If the encryption target is a directory, `passworld` creates a tar archive, encrypts that, and `rm -r`s the directory.\n\nThe output, or \"bundle\", contains the ciphertext (doubly encrypted file or directory), two CSPRNG scrypt salts, two CSPRNG encryption nonces, and an authentication tag for `AES-GCM`.\n\nWhen you want to decrypt something, you hand `passworld` the bundle and your password. It derives the second key from your password and the second salt in the bundle. Then it decrypts the ciphertext with the second key and the second nonce in the bundle using `AES-GCM`. It performs similar steps to recover the first key and subsequently decrypts using `secretbox`. When you tell `passworld` to decrypt a tar archive, it should extract it following decryption and then remove it. Your plaintext file or directory should now be in the filesystem.\n\n## A note on security\n\nI'll try to keep Node and dependency versions up to date/bump them when security vulnerabilities are addressed. If you discover a vulnerability in `passworld`, let me know! Refer to the [contributing section](#Contributing) to see how you can help.\n\n**WARNING:** `passworld` hasn't received a formal security audit so use it at your own risk and beware of 🐉🐉!\n\n## Install\n\n`npm i [-g] passworld`\n\n### For development\n\nMake sure you have [nvm](https://github.com/nvm-sh/nvm) installed.\n\nThen `git clone` the repo, `cd` into it, `nvm i`, and `npm i [-g]`.\n\n## Usage\n\n**Note:** each JS example assumes top-level `async/await` and each CLI command prompts you for a password.\n\n## Encrypt a file\n\nEncrypt a file and overwrite it with the encrypted contents.\n\n### JS\n\n```js\nawait passworld.encrypt('/path/to/file', 'password', { gzip })\n```\n\n### CLI\n\n```\n$ passworld encrypt [-z] path/to/file\n```\n\n#### Options\n\n##### gzip `[-z]`\nCompress before encryption.\n\n## Encrypt a directory\n\nCreate a tar archive of a directory, encrypt it, write the encrypted contents to `/path/to/dir.{tar|tgz}`, and remove the original directory.\n\n### JS\n\n```js\nawait passworld.encrypt('/path/to/dir', 'password', { gzip })\n```\n\n### CLI\n\n```\n$ passworld encrypt [-z] path/to/dir\n```\n\n#### Options\n\n##### gzip `[-z]`\nCompress before encryption.\n\n**Note:** the encrypted tar archive will have extension `.tgz` instead of `.tar`.\n\n## Decrypt a file\n\nDecrypt a file and overwrite it with the plaintext contents.\n\n### JS\n\n```js\nawait passworld.decrypt('/path/to/file', 'password')\n```\n\n### CLI\n\n```\n$ passworld decrypt /path/to/file\n```\n\n## Decrypt a directory\n\nDecrypt an encrypted tar archive, extract the original directory, and remove the archive.\n\n### JS\n\n```js\nawait passworld.decrypt('/path/to/dir.{tar|tgz}', 'password')\n```\n\n### CLI\n\n```\n$ passworld decrypt /path/to/dir.{tar|tgz}\n```\n\n## \"Recrypt\" a file or directory\n\nDecrypt a file or directory and encrypt it again.\n\nThis command prompts you for two passwords: the first for decryption and the second for encryption.\n\nIf you enter an empty password the second time, `passworld` will use the same password to encrypt.\n\n### CLI\n\n```\n$ passworld recrypt [-z] /path/to/*\n```\n\n#### Options\n\n##### gzip `[-z]`\nCompress before encryption.\n\n## Documentation\n\n`npm run doc`\n\n## Test\n\n`npm test`\n\n## Lint\n\n`npm run lint`\n\n## Contributing\n\nPlease do!\n\nIf you find a bug, want a feature added, or just have a question, feel free to [open an issue](https://github.com/zbo14/passworld/issues/new). In addition, you're welcome to [create a pull request](https://github.com/zbo14/passworld/compare/develop...) addressing an issue. You should push your changes to a feature branch and request merge to `develop`.\n\nMake sure linting and tests pass and coverage is 💯 before creating a pull request!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzbo14%2Fpassworld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzbo14%2Fpassworld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzbo14%2Fpassworld/lists"}