{"id":18207636,"url":"https://github.com/muhdhanish/queryable_encryption_mongodb_node","last_synced_at":"2026-01-28T06:40:31.375Z","repository":{"id":260724633,"uuid":"870090992","full_name":"MuhdHanish/queryable_encryption_mongodb_node","owner":"MuhdHanish","description":"Queryable Encryption with MongoDB in Node.js","archived":false,"fork":false,"pushed_at":"2024-11-02T04:22:20.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T08:12:17.942Z","etag":null,"topics":["encryption","mongodb","mongodb-atlas","mongodb-encryption","mongoose","nodejs","nodemon","queryable-encryption","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MuhdHanish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-10-09T12:30:52.000Z","updated_at":"2024-11-02T04:22:24.000Z","dependencies_parsed_at":"2024-11-02T05:19:23.817Z","dependency_job_id":"b3ab6946-28c9-48fb-b641-6ec5003f6481","html_url":"https://github.com/MuhdHanish/queryable_encryption_mongodb_node","commit_stats":null,"previous_names":["muhdhanish/queryable_encryption_mongodb_node"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuhdHanish%2Fqueryable_encryption_mongodb_node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuhdHanish%2Fqueryable_encryption_mongodb_node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuhdHanish%2Fqueryable_encryption_mongodb_node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MuhdHanish%2Fqueryable_encryption_mongodb_node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MuhdHanish","download_url":"https://codeload.github.com/MuhdHanish/queryable_encryption_mongodb_node/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248190501,"owners_count":21062284,"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","mongodb","mongodb-atlas","mongodb-encryption","mongoose","nodejs","nodemon","queryable-encryption","typescript"],"created_at":"2024-11-03T13:03:47.080Z","updated_at":"2026-01-28T06:40:31.323Z","avatar_url":"https://github.com/MuhdHanish.png","language":"TypeScript","readme":"# Queryable Encryption with MongoDB in Node.js\n\nThis project demonstrates how to implement **Client-Side Field Level Encryption (CSFLE)** using MongoDB and Node.js. It uses **Queryable Encryption** to allow searching on encrypted fields, such as emails, while keeping the data secure. Sensitive fields like passwords and Social Security Numbers (SSNs) are encrypted using MongoDB's CSFLE feature.\n\n## Table of Contents\n\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Environment Variables](#environment-variables)\n- [How It Works](#how-it-works)\n- [Running the App](#running-the-app)\n- [API Endpoints](#api-endpoints)\n- [Schema Map](#schema-map)\n- [Encryption Algorithms](#encryption-algorithms)\n- [Feedback](#feedback)\n- [Support](#support)\n\n## Features\n\n- **Queryable Encryption**: Perform equality queries on encrypted fields (e.g., search users by email).\n- **Field-Level Encryption**: Encrypt sensitive fields such as passwords and SSNs using random encryption.\n- **Local Key Management**: Supports local KMS (Key Management System) with a base64-encoded master key.\n- **Secure Registration and Query**: Registers new users with encrypted fields and allows searching users by email.\n\n## Prerequisites\n\nBefore you can run this project, ensure you have the following:\n\n1. **MongoDB 4.2+**: You need MongoDB 4.2 or later with support for **Client-Side Field Level Encryption (CSFLE)**.\n2. **Node.js**: Ensure you have Node.js installed (version 14+ is recommended).\n3. **MongoDB URI**: You need access to a MongoDB instance (either locally or via MongoDB Atlas).\n4. **Master Key**: A base64-encoded master key for local KMS (for demo purposes).\n\n## Installation\n\n1. Clone this repository:\n\n   ```bash\n   git clone https://github.com/MuhdHanish/queryable_encryption_mongodb_node.git\n   ```\n\n2. Navigate into the project directory:\n\n   ```bash\n   cd queryable_encryption_mongodb_node\n   ```\n\n3. Install the required dependencies:\n\n   ```bash\n   npm install\n   ```\n\n## Environment Variables\n\nYou need to create a `.env` file in the root of the project with the following variables:\n\n```env\nMONGO_URI=mongodb+srv://\u003cusername\u003e:\u003cpassword\u003e@cluster0.mongodb.net/mydb?retryWrites=true\u0026w=majority\nMASTER_KEY=your_base64_encoded_master_key\nPORT=8000  # Port number for the server\n```\n\n### How to Generate a Master Key (with OpenSSL)\n\nFor the **local KMS provider**, you need a 96-byte key. You can generate it using the `openssl` command:\n\n```bash\nopenssl rand -base64 96\n```\n\nThis will output a base64-encoded 96-byte key, which you can store in your `.env` file as `MASTER_KEY`.\n\n### How to Generate the Key ID\n\nIn the code, a **Key ID** (used for encrypting data fields) will be generated automatically if it doesn't exist. When running the server for the first time, it will generate the Key ID and prompt you to add it to the `.env` file.\n\nTo create the **KEY_ID**:\n1. Run the following command:\n    ```bash\n    npm run start:dev\n    ```\n\n2. If the `KEY_ID` is not set in your `.env`, the application will generate a new key and print it in the console:\n    ```bash\n    Add this KEY_ID to your .env file: \u003cgenerated_key_id\u003e\n    ```\n\n3. Copy the generated key and add it to the `.env` file as follows:\n    ```env\n    KEY_ID=your_base64_encoded_key_id\n    ```\n\nThis **KEY_ID** is necessary for encrypting the data fields and will be used in future operations.\n\n## How It Works\n\n- **Deterministic Encryption**: Allows for queries on fields like `email`.\n- **Random Encryption**: Provides stronger security for fields like `password` and `ssn`, but does not support querying.\n- The app uses MongoDB's native client (`mongodb` package) to perform encryption. Mongoose is also used for schema management, but MongoClient is required for handling encrypted fields.\n\n## Running the App\n\nOnce you've configured everything, you can start the app:\n\n```bash\nnpm run start:dev\n```\n\nThe app will run on the port defined in your `.env` file (default: 8000).\n\n## API Endpoints\n\n### Register a New User\n\n- **URL**: `/api/register`\n- **Method**: `POST`\n- **Description**: Registers a new user and encrypts sensitive fields such as `email`, `password`, and `ssn`.\n\n#### Request Body:\n\n```json\n{\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\",\n  \"password\": \"supersecret\",\n  \"ssn\": \"123-45-6789\"\n}\n```\n\n#### Response:\n\n```json\n{\n  \"message\": \"User registered successfully\",\n  \"userId\": \"\u003cMongoDB Document ID\u003e\"\n}\n```\n\n### Retrieve User by Email\n\n- **URL**: `/api/user/:email`\n- **Method**: `GET`\n- **Description**: Retrieves a user by their email. Only non-sensitive fields are returned (i.e., password and SSN are excluded).\n\n#### Response:\n\n```json\n{\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\"\n}\n```\n\n## Schema Map\n\nThe encryption schema used by MongoDB to encrypt specific fields:\n\n```js\nconst schemaMap = {\n  \"queryable_encryption.users\": {\n    bsonType: \"object\",\n    encryptMetadata: {\n      keyId: [new Binary(Buffer.from(process.env.KEY_ID!, 'base64'), 4)]\n    },\n    properties: {\n      email: {\n        encrypt: {\n          bsonType: \"string\",\n          algorithm: \"AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic\"\n        }\n      },\n      password: {\n        encrypt: {\n          bsonType: \"string\",\n          algorithm: \"AEAD_AES_256_CBC_HMAC_SHA_512-Random\"\n        }\n      },\n      ssn: {\n        encrypt: {\n          bsonType: \"string\",\n          algorithm: \"AEAD_AES_256_CBC_HMAC_SHA_512-Random\"\n        }\n      }\n    }\n  }\n};\n```\n\n## Encryption Algorithms\n\n- **Deterministic Encryption**: Used for the `email` field, allows queries on encrypted data.\n- **Random Encryption**: Used for sensitive fields like `password` and `ssn`, provides stronger security but no querying capabilities.\n\n## Feedback\n\nIf you have any feedback, please reach me at [muhammedhanish11@gmail.com](mailto:muhammedhanish11@gmail.com) or connect with me on [LinkedIn](https://www.linkedin.com/in/muhdhanish/).\n\n## Support\n\nShow your support by 🌟 starring the project!!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuhdhanish%2Fqueryable_encryption_mongodb_node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuhdhanish%2Fqueryable_encryption_mongodb_node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuhdhanish%2Fqueryable_encryption_mongodb_node/lists"}