Prisma-crypto NPM

Prisma-Crypto: Automated Encryption for Prisma ORM

The prisma-crypto is an extension for the Prisma ORM that simplifies the implementation of encryption in your database models. With a simple annotation and some configurations, you can ensure that your data is stored securely while still maintaining the ability to query these data efficiently.

📑 Table of Contents

🚀 Installation

npm install prisma-crypto

yarn add prisma-crypto

🌐 Environment Configuration

Before starting, set up the following environment variables:

- PRISMA_CRYPTO_SECRET_KEY="" #Your secret key for encryption. Must be 32 characters
- PRISMA_CRYPTO_DIRECT_DB="" #Direct connection to the database. Useful for development environments with Docker.
- PRISMA_CRYPTO_WRITE_DB="" #Connection to the write instance. Used for write operations via Prisma Client.
- PRISMA_CRYPTO_READ_DB="" #Connection to the read instance. Used for read operations via Prisma Client.
- PRISMA_CRYPTO_DEBUG=false #Activate to get detailed logs of the package's operation.

In scenarios where the prisma client has not yet been initialized - as in the case of a project that has just been cloned - it will be necessary to do so. We recommend that you configure a post-installation script, as follows:

{ // package.json
  "scripts": {
    "postinstall": "npx prisma generate --generator client",
    // other scripts here
  },
  // other configs here
}

This way, whenever you run an npm i your prisma client will automatically be initialized. If you don't want to add the script, just run the command npx prisma generate --generator client manually via CLI.

📝 Schema Configuration

In your schema.prisma, setup a new generator and add the @encrypt annotation to the fields you want to encrypt.

generator encrypt {
    provider = "prisma-crypto"
}

model User {
  id       Int     @id @default(autoincrement())
  email    String  @unique // @encrypt
  password String  // @encrypt
}

🛠 Usage

With prisma-crypto set up, run your Prisma operations as usual. The extension will handle encryption and decryption for you.

import { PrismaCrypto } from "prisma-crypto";

const prisma = new PrismaCrypto({
    debug: true // It is possible to control the level of granularity of the debug by activating only the client and deactivating the env(general)
}).getPrismaClient();

const newUser = {
  email: 'example@example.com',
  password: 'securePassword',
};

await prisma.user.create({
  data: newUser,
});

When retrieving the user, the encrypted fields will be automatically decrypted:

import { PrismaCrypto } from "prisma-crypto";

const prisma = new PrismaCrypto().getPrismaClient();

const userEmail = 'example@example.com';

const user = await prisma.user.findUnique({
  where: {
    email: userEmail,
  },
});

console.log(user.password); // 'securePassword'

If necessary, you can call Prisma Crypto's encryption/decryption methods manually:

import { EncryptionMethods } from "@paipe/prisma-crypto";

const encryptedString = EncryptionMethods.encryptData("test");
const decryptedString = EncryptionMethods.decryptData("test");

📖 Technical Details

Encryption Algorithm

The prisma-crypto uses the aes-256-gcm algorithm for encryption. This is a symmetric encryption algorithm that is widely recognized for its security and efficiency.

Deterministic Encryption

To allow queries on encrypted fields, the prisma-crypto uses a deterministic approach, where the same input will always produce the same encrypted output. This is achieved through the use of hashes.