{"id":19889534,"url":"https://github.com/tsmx/mongoose-encrypted-string","last_synced_at":"2025-05-02T17:33:41.734Z","repository":{"id":57156418,"uuid":"303511452","full_name":"tsmx/mongoose-encrypted-string","owner":"tsmx","description":"EncryptedString type for Mongoose schemas.","archived":false,"fork":false,"pushed_at":"2024-08-08T18:49:00.000Z","size":510,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-08T21:25:39.701Z","etag":null,"topics":["encryption","mongoose","mongoose-schemas","string-crypto"],"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/tsmx.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":"2020-10-12T20:57:53.000Z","updated_at":"2024-08-08T18:49:03.000Z","dependencies_parsed_at":"2023-01-30T02:00:57.895Z","dependency_job_id":"e40eba61-98f8-4ff7-9abc-a2133fc89a77","html_url":"https://github.com/tsmx/mongoose-encrypted-string","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/tsmx%2Fmongoose-encrypted-string","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsmx%2Fmongoose-encrypted-string/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsmx%2Fmongoose-encrypted-string/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsmx%2Fmongoose-encrypted-string/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsmx","download_url":"https://codeload.github.com/tsmx/mongoose-encrypted-string/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224324404,"owners_count":17292521,"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","mongoose","mongoose-schemas","string-crypto"],"created_at":"2024-11-12T18:10:39.270Z","updated_at":"2024-11-12T18:10:39.959Z","avatar_url":"https://github.com/tsmx.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [**@tsmx/mongoose-encrypted-string**](https://github.com/tsmx/mongoose-encrypted-string)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n![npm (scoped)](https://img.shields.io/npm/v/@tsmx/mongoose-encrypted-string)\n![node-current (scoped)](https://img.shields.io/node/v/@tsmx/mongoose-encrypted-string)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/tsmx/mongoose-encrypted-string/git-build.yml?branch=master)](https://img.shields.io/github/actions/workflow/status/tsmx/mongoose-encrypted-string/git-build.yml?branch=master)\n[![Coverage Status](https://coveralls.io/repos/github/tsmx/mongoose-encrypted-string/badge.svg?branch=master)](https://coveralls.io/github/tsmx/mongoose-encrypted-string?branch=master)\n\n\u003e `EncryptedString` type for Mongoose schemas. Provides AES-256-CBC encryption-at-rest for strings.\n\n## Usage\n\n```js\nvar mongoose = require('mongoose');\nconst mes = require('@tsmx/mongoose-encrypted-string');\nconst key = 'YOUR KEY HERE';\n\n// register the new type EncryptedString\nmes.registerEncryptedString(mongoose, key);\n\n// use EncryptedString in your schemas\nPerson = mongoose.model('Person', {\n    id: { type: String, required: true },\n    firstName: { type: mongoose.Schema.Types.EncryptedString },\n    lastName: { type: mongoose.Schema.Types.EncryptedString }\n});\n\nlet testPerson = new Person();\ntestPerson.id = 'id-test';\ntestPerson.firstName = 'Hans'; // stored encrypted\ntestPerson.lastName = 'Müller'; // stored encrypted\nawait testPerson.save();\n\n\nlet queriedPerson = await Person.findOne({ id: 'id-test' });\nconsole.log(queriedPerson.firstName); // 'Hans', decrypted automatically\nconsole.log(queriedPerson.lastName); // 'Müller, decrypted automatically\n```\nDirectly querying the MongoDB will return the encrypted data.\n```bash\n\u003e db.persons.findOne({ id: 'id-test' });\n{\n        \"_id\" : ObjectId(\"5f8576cc0a6ca01d8e5c479c\"),\n        \"id\" : \"id-test\",\n        \"firstName\" : \"66db1589b5c0de7f98f5260092e6799f|a6cb74bc05a52d1244addb125352bb0d\",\n        \"lastName\" : \"2b85f4ca2d98ad1234da376a6d0d9128|d5b0257d3797da7047bfea6dfa62e19c\",\n        \"__v\" : 0\n}\n```\n\n## API\n\n### registerEncryptedString(mongoose, key)\n\nRegisters the new type `EncryptedString` in the `mongoose` instance's schema types. Encryption/decryption is done with AES-256-CBC using the given `key`. After calling this funtion you can start using the new type via `mongoose.Schema.Types.EncryptedString` in your schemas.\n\n#### mongoose\n\nThe mongoose instance where `EncryptedString` should be registered.\n\n#### key\n\nThe key used for encryption/decryption. Length must be 32 bytes. See [notes](#notes) for details.\n\n## Use with lean() queries\n\nFor performance reasons it maybe useful to use Mongoose's `lean()` queries. Doing so, the query will return the raw JSON objects from the MongoDB database where all properties of type `EncryptedString` are encrypted.\n\nTo get the clear text values back you can directly use [@tsmx/string-crypto](https://www.npmjs.com/package/@tsmx/string-crypto) which is also used internally in this package for encryption and decryption.\n\n```js\nconst key = 'YOUR KEY HERE';\nconst sc = require('@tsmx/string-crypto');\n\n// query raw objects with encrypted string values\nlet person = await Person.findOne({ id: 'id-test' }).lean();\n\n// decrypt using string-crypto\nlet firstName = sc.decrypt(person.firstName, { key: key });\nlet lastName = sc.decrypt(person.lastName, { key: key });\n```\n\n## Notes\n\n- Encryption/decryption is done via the package [@tsmx/string-crypto](https://www.npmjs.com/package/@tsmx/string-crypto).\n- Key length must be 32 bytes. The key can be provided as\n    - a string of 32 characters length, or\n    - a hexadecimal value of 64 characters length (= 32 bytes)\n- Don't override getters/setter for `EncryptedString` class or schema elements of this type. This would break the encryption.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsmx%2Fmongoose-encrypted-string","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsmx%2Fmongoose-encrypted-string","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsmx%2Fmongoose-encrypted-string/lists"}