{"id":13528360,"url":"https://github.com/adieuadieu/aws-kms-thingy","last_synced_at":"2025-04-01T11:31:30.877Z","repository":{"id":29574852,"uuid":"113064982","full_name":"adieuadieu/aws-kms-thingy","owner":"adieuadieu","description":"🔐 Convenience wrapper \u0026 CLI around the AWS Node.js SDK to make encrypting/decrypting secrets with the AWS KMS service a one-liner. Suitable for use with AWS Lambda.","archived":true,"fork":false,"pushed_at":"2023-03-22T13:56:40.000Z","size":853,"stargazers_count":20,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-09-21T12:13:25.143Z","etag":null,"topics":["aws","aws-kms","aws-lambda","aws-sdk-javascript","cli","functionalesque-programming","no-if-statement","secrets","typescript"],"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/adieuadieu.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},"funding":{"github":"adieuadieu"}},"created_at":"2017-12-04T16:12:36.000Z","updated_at":"2023-03-22T13:56:50.000Z","dependencies_parsed_at":"2024-01-13T22:23:18.072Z","dependency_job_id":null,"html_url":"https://github.com/adieuadieu/aws-kms-thingy","commit_stats":{"total_commits":575,"total_committers":4,"mean_commits":143.75,"dds":"0.10434782608695647","last_synced_commit":"f61ba03b0b0d9031d460665f7167cfa9e87c8f9e"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adieuadieu%2Faws-kms-thingy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adieuadieu%2Faws-kms-thingy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adieuadieu%2Faws-kms-thingy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adieuadieu%2Faws-kms-thingy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adieuadieu","download_url":"https://codeload.github.com/adieuadieu/aws-kms-thingy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222696694,"owners_count":17024681,"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":["aws","aws-kms","aws-lambda","aws-sdk-javascript","cli","functionalesque-programming","no-if-statement","secrets","typescript"],"created_at":"2024-08-01T06:02:27.955Z","updated_at":"2024-11-02T13:31:39.014Z","avatar_url":"https://github.com/adieuadieu.png","language":"TypeScript","funding_links":["https://github.com/sponsors/adieuadieu"],"categories":["TypeScript"],"sub_categories":[],"readme":"# aws-kms-thingy\n\nConvenience wrapper around the AWS Node.js SDK to simplify encrypting/decrypting secrets with the AWS KMS service. Suitable for use with AWS Lambda.\n\n[![CircleCI](https://img.shields.io/circleci/project/github/adieuadieu/aws-kms-thingy/master.svg?style=flat-square)](https://circleci.com/gh/adieuadieu/aws-kms-thingy)\n[![Coveralls](https://img.shields.io/coveralls/adieuadieu/aws-kms-thingy/master.svg?style=flat-square)](https://coveralls.io/github/adieuadieu/aws-kms-thingy)\n[![David](https://img.shields.io/david/adieuadieu/aws-kms-thingy.svg?style=flat-square)]()\n[![David](https://img.shields.io/david/dev/adieuadieu/aws-kms-thingy.svg?style=flat-square)]()\n[![GitHub release](https://img.shields.io/github/release/adieuadieu/aws-kms-thingy.svg?style=flat-square)](https://github.com/adieuadieu/aws-kms-thingy)\n\n## Contents\n\n1.  [Features](#features)\n1.  [Usage](#usage)\n    1.  [With the CLI](#with-the-cli)\n    1.  [With AWS Lambda](#with-aws-lambda)\n    1.  [With Multiple Secrets](#with-multiple-secrets)\n    1.  [Locally In Development](#locally-in-development)\n1.  [API](#api)\n1.  [Related Thingies](#related-thingies)\n1.  [License](#license)\n\n### Features\n\n* Unencrypted strings simply returned, useful for testing/local development\n* Encrypt/decrypt multiple values in one go\n* Results are cached, so multiple decrypt/encrypt calls incur only a single call to the AWS SDK\n* CLI to encrypt/decrypt secrets\n* Well tested\n\n## Usage\n\nThe module assumes that the Amazon SDK has access to AWS credentials that are able to access the KMS key used for encryption and decryption.\n\n```bash\nnpm install aws-kms-thingy aws-sdk@^2\n```\n\n### With the CLI\n\nEncrypt with:\n\n```bash\naws-kms-thingy encrypt\n```\n\nYou'll be prompted for the string to encrypt.\n\nDecrypt with:\n\n```bash\naws-kms-thingy decrypt\n```\n\nYou'll be prompted for the encrypted string to decrypt.\n\n### With AWS Lambda\n\nSafe to use within a Lambda handler. After cold-start, decrypted values are cached so subsequent invocations won't incur an AWS KMS API call:\n\n```javascript\nconst { decrypt } = require('aws-kms-thingy')\n\nmodule.exports.myLambdaHandler = (event, context, callback) =\u003e {\n  decrypt(process.env.SOME_API_TOKEN) // Only incurs network call on cold-start\n    .then(doStuffWithDecryptedApiToken)\n    .then(resultOrWhatever =\u003e callback(null, resultOrWhatever))\n    .catch(callback)\n}\n```\n\n### With Multiple Secrets\n\nDecrypt multiple values in parallel\n\n```typescript\nimport { decrypt } from 'aws-kms-thingy'\n\nconst [\n  decryptedApiToken1,\n  decryptedApiToken2,\n  decryptedDatabasePassword,\n  somethingElseSecret,\n] = await decrypt([\n  process.env.API_TOKEN_1,\n  process.env.API_TOKEN_2,\n  process.env.DATABASE_PASSWORD,\n  process.env.SOMETHING_ELSE_SECRET,\n])\n```\n\n### Locally In Development\n\nProviding a non-base64 encoded value will skip en/decrypting with AWS KMS and just return the same value. This is useful in local development where you may not be necessary to have your secrets encrypted. This helps to avoid the need to write development environment exception code:\n\n```typescript\nimport { decrypt } from 'aws-kms-thingy'\n\nprocess.env.DATABASE_PASSWORD = 'foobar'\n\nconst dbPassword = await decrypt(process.env.DATABASE_PASSWORD)\n\nconsole.log(dbPassword) // \"foobar\"\n```\n\nAn `undefined` value is also OK. This does nothing and returns undefined. Useful when environment variables are unset in local development.\n\n```typescript\nprocess.env.DATABASE_PASSWORD = undefined // e.g. not set in development\n\nconst dbPassword = await decrypt(process.env.DATABASE_PASSWORD)\n\nconsole.log(dbPassword) // undefined\n```\n\nAlternatively, one can also disable en/decryption entirely with `DISABLE_AWS_KMS_THINGY` environment variable:\n\n```typescript\nimport { decrypt } from 'aws-kms-thingy'\n\nprocess.env.DISABLE_AWS_KMS_THINGY = 'true'\n\nconst token = await decrypt('aHR0cDovL2JpdC5seS8xVHFjd243')\n\nconsole.log(token) // \"aHR0cDovL2JpdC5seS8xVHFjd243\"\n```\n\n## API\n\n**Methods**\n\n* [`encrypt(parameters)`](#api-encrypt)\n* [`decrypt(ciphertext)`](#api-decrypt)\n\n---\n\n\u003ca name=\"api-encrypt\" /\u003e\n\n### encrypt(parameters)\n\n```typescript\ninterface InterfaceEncryptParameters {\n  readonly plaintext: string\n  readonly keyId: string\n}\n\nasync function encrypt(\n  parameters:\n    | InterfaceEncryptParameters\n    | ReadonlyArray\u003cInterfaceEncryptParameters\u003e,\n): Promise\u003cstring | ReadonlyArray\u003cstring\u003e\u003e\n```\n\nEncrypt a plaintext string. Requires a AWS KMS key ID (or key Arn).\n\n```js\nconst ciphertext = await encrypt({\n  plaintext: 'secret text',\n  keyId:\n    'arn:aws:kms:eu-west-1:000000000000:key/55kkmm11-aann-99ff-mmaa-3322115566hh',\n})\n```\n\n---\n\n\u003ca name=\"api-decrypt\" /\u003e\n\n### decrypt(ciphertext)\n\nAWS KMS encrypted ciphertext contains metadata so it is not necessary to provide context or key ID.\n\n```typescript\nasync function decrypt(\n  ciphertext: undefined | string | ReadonlyArray\u003cstring\u003e,\n): Promise\u003cundefined | string | ReadonlyArray\u003cstring\u003e\u003e\n```\n\nDecrypt KMS-encrypted ciphertext.\n\n```js\nconst plaintext = await decrypt('aHR0cDovL2JpdC5seS8xVHFjd243')\n```\n\n## Related Thingies\n\n* [aws-s3-thingy](https://github.com/adieuadieu/aws-s3-thingy)\n* [alagarr](https://github.com/adieuadieu/alagarr) — AWS Lambda/API Gateway Request/Response Thingy\n* [aws-kms-crypt](https://github.com/sjakthol/aws-kms-crypt)\n\n## License\n\n**aws-kms-thingy** © [Marco Lüthy](https://github.com/adieuadieu). Released under the [MIT](./LICENSE) license.\u003cbr\u003e\nAuthored and maintained by Marco Lüthy with help from [contributors](https://github.com/adieuadieu/aws-kms-thingy/contributors).\n\n\u003e [github.com/adieuadieu](https://github.com/adieuadieu) · GitHub [@adieuadieu](https://github.com/adieuadieu) · Twitter [@adieuadieu](https://twitter.com/adieuadieu) · Medium [@marco.luethy](https://medium.com/@marco.luethy)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadieuadieu%2Faws-kms-thingy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadieuadieu%2Faws-kms-thingy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadieuadieu%2Faws-kms-thingy/lists"}