{"id":19701832,"url":"https://github.com/kuzzleio/kuzzle-vault","last_synced_at":"2025-10-19T23:48:16.564Z","repository":{"id":43808411,"uuid":"206044992","full_name":"kuzzleio/kuzzle-vault","owner":"kuzzleio","description":"Securely share secrets for your application with JSON and cryptography ","archived":false,"fork":false,"pushed_at":"2024-08-27T07:18:47.000Z","size":490,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-18T23:19:17.267Z","etag":null,"topics":["devops","encryption","key-management","kuzzle"],"latest_commit_sha":null,"homepage":"","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/kuzzleio.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":"2019-09-03T09:54:23.000Z","updated_at":"2024-08-27T07:18:49.000Z","dependencies_parsed_at":"2022-09-17T03:30:51.132Z","dependency_job_id":null,"html_url":"https://github.com/kuzzleio/kuzzle-vault","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuzzleio","download_url":"https://codeload.github.com/kuzzleio/kuzzle-vault/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251465532,"owners_count":21593897,"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":["devops","encryption","key-management","kuzzle"],"created_at":"2024-11-11T21:10:58.854Z","updated_at":"2025-10-19T23:48:11.507Z","avatar_url":"https://github.com/kuzzleio.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://travis-ci.org/kuzzleio/kuzzle-vault\"\u003e\n    \u003cimg src=\"https://travis-ci.org/kuzzleio/kuzzle-vault.svg?branch=master\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/kuzzleio/kuzzle-vault\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/kuzzleio/kuzzle-vault/branch/master/graph/badge.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/kuzzleio/kuzzle-vault/blob/master/LICENSE\"\u003e\n    \u003cimg alt=\"undefined\" src=\"https://img.shields.io/github/license/kuzzleio/kuzzle-vault.svg?style=flat\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## About\n\nKuzzle Vault is a system to **securely share your API keys** and other secrets within your team.\n\nSecrets are saved in **an encrypted JSON or YAML file** that you can version alongside your code.\n\nYou only need to **share one encryption key** with your team members.\n\nThen you can load and decrypt the contents of the file into your **application memory** for secure usage.\n\nSee the related article on [Kuzzle Blog](https://blog.kuzzle.io/share-sensitive-data-with-git-and-cryptography)\n\nImplementations are available for the following languages:\n - [Node.js](https://github.com/kuzzleio/kuzzle-vault/)\n - [PHP](https://github.com/kuzzleio/kuzzle-vault/tree/php)\n\n___\n\n## Usage\n\n\n### Encrypt your secrets in a JSON file\n\n#### With Kourou (NPM package)\n\nFirst, you need to encrypt your secrets. The easiest way to do that is to use [Kourou, the Kuzzle CLI](https://github.com/kuzzleio/kourou/#kourou-vaultadd-secrets-file-key-value).\n\n```bash\n$ npm install -g kourou\n\n$ kourou vault:encrypt config/prod/secrets.json --vault-key \u003cpassword\u003e\n\n 🚀 Kourou - Encrypts an entire file.\n \n [✔] Secrets were successfully encrypted into the file config/prod/secrets.enc.json\n```\n\nThen, you can securely store your secrets inside your repository and share them with you team. \n\n#### With Bash\n\nAlternatively, you can also use the [bash script provided](./bin/kuzzle-vault-encrypt-string) in this repository to encrypt a string in Kuzzle Vault format.\n\nIt will give you an encrypted string that you have to put in your JSON file containing encrypted secrets.\n\nExample:\n```bash\n$ bash bin/kuzzle-vault-encrypt-string kuzzle-vault-encrypt-string something_secret vaultKey\ncad308c9e857accc2d82dffb70e59dbe1460545372d6c0620dd46136ad16ae44.52a6a6e897696ec45f5715df12818939\n```\n\nThen put the encrypted string in a JSON file:\n```json\n{\n  \"secret-key\": \"cad308c9e857accc2d82dffb70e59dbe1460545372d6c0620dd46136ad16ae44.52a6a6e897696ec45f5715df12818939\"\n}\n```\n\nThe complete script documentation is available with `bash bin/kuzzle-vault-encrypt-string --help`.\n\n### Use encrypted secrets within your application\n\nTo load the secrets inside an application, instantiate the Vault with the same password as for the encryption.\n\nThen, use the decrypt method with the path of the encrypted secrets file to load the secrets into the memory.  \n\n```js\nconst vault = new Vault('password');\nvault.decrypt('config/prod/secrets.enc.json');\n// or\nvault.decrypt('config/prod/secrets.enc.yaml');\n\n// secrets are now available\nvault.secrets\n```\n\nYou can also provide the password with the environment variable `KUZZLE_VAULT_KEY`.  \n\n```js\n// process.env.KUZZLE_VAULT_KEY === 'password'\n\nconst vault = new Vault();\nvault.decrypt('config/prod/secrets.enc.json');\n\n// secrets are now available\nvault.secrets\n```\n\n### Data encryption\n\nThe cipher used is `aes-256-cbc` with a 16 bytes initialization vector.  \n\nThe encryption key is hashed with SHA256 and then used with a random initialization vector to encrypt the data.  \n\nEncrypted values are represented under the following format `\u003cencrypted-data\u003e.\u003cinitialization-vector\u003e`.  \n\nBoth `\u003cencrypted-data\u003e` and `\u003cinitialization-vector\u003e` are in hexadecimal.\n\n### Secrets file format\n\nThe secrets file is in JSON or YAML format. String values are encrypted but the key names remain the same.\n\n```json\n/* secrets.json */\n{\n  \"aws\": {\n    \"secretKeyId\": \"lfiduras\"\n  },\n  \"cloudinaryKey\": \"ho-chi-minh\"\n}\n```\n\n```yaml\naws:\n  - secretKeyId: \"lfiduras\"\n  - groups:\n    primary\n    secondary    \n```\n\nOnce encrypted, the file looks like the following:\n\n```json\n/* secrets.enc.json */\n{\n  \"aws\": {\n    \"secretKeyId\": \"81f52891e336c76c82033c38f44d28.81f3214be3836bbb9fa165dfa691071a\"\n  },\n  \"cloudinaryKey\": \"f700cac98100f1266536553f3181ada6.65dfa691071a81f3214be3836bbb9fa1\"\n}\n```\n\n```yaml\naws:\n  - secretKeyId: \"81f52891e336c76c82033c38f44d28.81f3214be3836bbb9fa165dfa691071a\"\n  - groups:\n    \"f700cac98100f1266536553f3181ada6.65dfa691071a81f3214be3836bbb9fa1\"\n    \"1266536553ff700cac98100f3181ada6.a81f3214be3865dfa69107136bbb9fa1\"    \n```\n\n\n## Vault class\n\n[Vault.constructor](#constructor)\n[Vault.decrypt](#decrypt)\n\n___\n\n### Vault.constructor\n\nThe constructor of the `Vault` class.\n\n```js\nVault(vaultKey: string | undefined);\n```\n\n**Arguments**\n\n| Name | Type              | Description |\n| -------- | ----------------- | ----------- |\n| `vaultKey`  | \u003cpre\u003eString\u003c/pre\u003e | The key used to encrypt and decrypt secrets   |\n\n#### Usage\n\n```js\nconst vault = new Vault('my vault key');\n```\n\n___\n\n### Vault.decrypt\n\nDecrypts the content of the file designated by `encryptedVaultPath` and store the decrypted content inside the property `secrets` of the `Vault` class.\n\n\u003cbr/\u003e\n\n```js\ndecrypt(encryptedVaultPath: string);\n```\n\n\n#### Usage\n\n```js\nconst vault = new Vault('my vault key');\nvault.decrypt('path/to/secrets.enc.json');\n\nvault.secrets // Contains decrypted secrets\n```\n\n## [Cryptonomicon](./src/Cryptonomicon.ts) class\n\nThis class contains the cryptography primitives used to encrypt and decrypt the secrets.  \n\nThere are 4 methods available:\n - `decryptObject`\n - `encryptObject`\n - `encryptString`\n - `decryptString`\n\nYou can use this class to build your own tools to decrypt or encrypt secrets inside your application.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuzzleio%2Fkuzzle-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuzzleio%2Fkuzzle-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuzzleio%2Fkuzzle-vault/lists"}