@growy/strapi-plugin-encrypted-field 2.3.1 → 2.3.3

package/README.md

@@ -6,29 +6,22 @@
   <img src="https://img.shields.io/badge/Strapi-v5-blueviolet" alt="Strapi v5" />
 </div>
 
----
-
-### [English](#english-version) | [Español](#versión-en-español)
-
----
-
-## English Version
-
-Official **Growy AI** plugin for Strapi that provide a custom encrypted text field using AES-256-GCM. Protect sensitive information directly in your database with transparent encryption and robust validation.
-
-### Features
-
-- ✅ **Custom Field** "Encrypted Text" in the Content-Type Builder.
-- ✅ **Automatic Encryption** AES-256-GCM when saving.
-- ✅ **Transparent Decryption** when reading (Admin panel and API).
-- ✅ **Backend Validation** with regex support and length constraints.
-- ✅ **Native Strapi v5 UI** with visibility controls and copy to clipboard.
-- ✅ **Multi-language support (i18n)**: English and Spanish.
-- ✅ **Secure Key Management** with validation and clear error messages.
-- ✅ **Encrypted Data** in database with unique IV and Auth Tag.
-- ✅ **Nested Components support** at any depth.
-
-### Installation
+Official **Growy AI** plugin for Strapi that provides a custom encrypted text field using AES-256-GCM. Protect sensitive information directly in your database with transparent encryption and robust validation.
+
+- ✅ **Custom field** "Encrypted Text" in the Content-Type Builder
+- ✅ **Automatic encryption** AES-256-GCM on save
+- ✅ **Transparent decryption** on read (admin panel and API)
+- ✅ **Backend validation** with regex and length constraint support
+- ✅ **Native Strapi v5 UI** with visibility controls, resizable inputs and copy to clipboard
+- ✅ **Values hidden** by default with show/hide toggle
+- ✅ **Copy notifications** confirmation when copying values
+- ✅ **Multi-language support (i18n)**: English and Spanish
+- ✅ **Robust key management** with validation and clear error messages
+- ✅ **Encrypted data** in database with unique IV and Auth Tag per operation
+- ✅ **Reusable** in any collection or component
+- ✅ **Full support** for nested components and complex structures
+
+## Installation
 
 ```bash
 npm install @growy/strapi-plugin-encrypted-field
@@ -36,9 +29,9 @@ npm install @growy/strapi-plugin-encrypted-field
 yarn add @growy/strapi-plugin-encrypted-field
 ```
 
-### Configuration
+## Configuration
 
-#### 1. Enable the plugin
+### 1. Enable the plugin
 
 Create or edit `config/plugins.js` or `config/plugins.ts`:
 
@@ -50,7 +43,9 @@ module.exports = {
 };
 ```
 
-#### 2. Configure Encryption Key (REQUIRED)
+### 2. Configure the encryption key (REQUIRED)
+
+#### Option A: Environment variable (recommended)
 
 Add to your `.env`:
 
@@ -58,103 +53,190 @@ Add to your `.env`:
 ENCRYPTION_KEY=your_64_character_hex_key_here
 ```
 
-Generate a secure key:
+#### Option B: Configuration file
+
+Edit `config/plugins.js`:
+
+```javascript
+module.exports = ({ env }) => ({
+  'encrypted-field': {
+    enabled: true,
+    config: {
+      encryptionKey: env('ENCRYPTION_KEY'),
+    },
+  },
+});
+```
+
+#### Generate a secure key
+
 ```bash
 node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 ```
 
-### Usage
+This will generate a 64-character hexadecimal key (32 bytes).
 
-1. Go to **Content-Type Builder**.
-2. Select a collection or create a new one.
-3. Click on **"Add another field"**.
-4. Select **"Encrypted Text"** (look for the 🔒 icon).
-5. Values are hidden by default in the Admin Panel but can be revealed or copied using the inline buttons.
+⚠️ **CRITICAL - Key Management**:
+- **Store the key securely** (secrets manager, encrypted environment variables)
+- **Never** include it in version control
+- **If you lose the key**, you will not be able to decrypt existing data
+- **Use the same key** across all environments sharing the same database
+- **For production**, consider services like AWS Secrets Manager, HashiCorp Vault or similar
 
----
+### 3. Rebuild the admin
 
-## Versión en Español
+```bash
+npm run build
+npm run develop
+```
 
-Plugin oficial de **Growy AI** para Strapi que proporciona un campo personalizado de texto cifrado con AES-256-GCM. Protege información sensible directamente en tu base de datos con cifrado transparente y validación robusta.
+## Requirements
 
-### Características
+- **Strapi**: v5.0.0 or higher
+- **Node.js**: 18.x - 22.x
+- **npm**: 6.0.0 or higher
 
-- ✅ **Campo personalizado** "Texto Cifrado" en el Content-Type Builder.
-- ✅ **Cifrado automático** AES-256-GCM al guardar.
-- ✅ **Descifrado transparente** al leer (panel y API).
-- ✅ **Validación backend** con soporte para regex y restricciones.
-- ✅ **UI Nativa Strapi v5** con controles de visibilidad y copiar al portapapeles.
-- ✅ **Soporte multi-idioma (i18n)**: Inglés y Español.
-- ✅ **Gestión de claves robusta** con validación y mensajes de error claros.
-- ✅ **Datos cifrados** en base de datos con IV único y Auth Tag.
-- ✅ **Soporte para componentes anidados** a cualquier profundidad.
+## Data Validation
 
-### Instalación
+The plugin supports validation before encryption:
 
-```bash
-npm install @growy/strapi-plugin-encrypted-field
-# o
-yarn add @growy/strapi-plugin-encrypted-field
+### Configure regex validation
+
+1. In Content-Type Builder, select the encrypted field
+2. Go to the **"Advanced Settings"** tab
+3. In **"RegEx pattern"**, enter your regular expression
+4. Save the changes
+
+**Example**: To validate API key format:
+```regex
+^sk-[a-zA-Z0-9]{32}$
 ```
 
-### Configuración
+If the value does not match the pattern, an error will be thrown before encryption.
 
-#### 1. Habilitar el plugin
+## Usage
 
-Edita `config/plugins.js`:
+### 1. Add an encrypted field to a collection
 
-```javascript
-module.exports = {
-  'encrypted-field': {
-    enabled: true,
-  },
-};
-```
+1. Go to **Content-Type Builder**
+2. Select a collection or create a new one
+3. Click **"Add another field"**
+4. Search for **"Encrypted Text"** (with 🔒 icon)
+5. Set the field name
+6. Save and restart Strapi
+
+### 2. Using the field
+
+The field works like a regular text field with additional security features:
 
-#### 2. Configurar la clave (REQUERIDO)
+- **In the panel**: Type text normally
+- **Hidden values**: Values are shown as `***` by default
+- **Eye button**: Toggles between show/hide the value
+- **Copy button**: Copies the value to clipboard with a confirmation notification
+- **On save**: Automatically encrypted
+- **On read**: Automatically decrypted
+- **In the DB**: Stored encrypted with format `iv:authTag:encrypted`
+- **In components**: Works the same in nested components at any depth
 
-Agrega a tu `.env`:
+### 3. API Usage
 
 ```bash
-ENCRYPTION_KEY=tu_clave_de_64_caracteres_hexadecimales_aqui
+# Create with an encrypted field
+curl -X POST http://localhost:1337/api/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "name": "John",
+      "apiKey": "my-secret-key-123"
+    }
+  }'
+
+# Read (returns decrypted)
+curl -X GET http://localhost:1337/api/users/1
+# Response: { "name": "John", "apiKey": "my-secret-key-123" }
 ```
 
-### Uso
+## Usage Example
 
-1. Ve a **Content-Type Builder**.
-2. Selecciona una colección.
-3. Click en **"Add another field"**.
-4. Selecciona **"Texto Cifrado"** (icono 🔒).
-5. Los valores están ocultos por defecto en el panel pero pueden mostrarse o copiarse con los botones integrados.
+### "User" collection with an encrypted API Key
 
-### Seguridad y Especificaciones
+**Schema:**
+```json
+{
+  "name": "string",
+  "email": "email",
+  "apiKey": "plugin::encrypted-field.encrypted-text"
+}
+```
 
-- **Algoritmo**: AES-256-GCM.
-- **IV (Initialization Vector)**: 96 bits generado aleatoriamente por operación.
-- **Auth Tag**: 128 bits para verificación de integridad.
-- **Formato almacenado**: `iv:authTag:encryptedData`.
+**In the DB:**
+```
+apiKey: "a1b2c3d4e5f6....:f9e8d7c6b5a4....:9f8e7d6c5b4a3..."
+```
 
-### Limitaciones
+**In the panel and API:**
+```
+apiKey: "sk-1234567890abcdef"
+```
 
-- ❌ **Búsqueda**: No se puede buscar por campos cifrados.
-- ❌ **Ordenamiento**: No se puede ordenar por campos cifrados.
-- ❌ **Filtros**: No se pueden aplicar filtros directos sobre datos cifrados.
+## Security & Architecture
 
----
+### Technical Specifications
+
+- **Algorithm**: AES-256-GCM (NIST standard, military grade)
+- **Key size**: 256 bits (32 bytes, 64 hex characters)
+- **IV (Initialization Vector)**: 96 bits (12 bytes) randomly generated per operation
+- **Auth Tag**: 128 bits (16 bytes) for integrity verification
+- **Stored format**: `iv:authTag:encryptedData` (all in hexadecimal)
+- **Key caching**: Encryption key is parsed and cached in memory for optimal performance
+
+### Security Features
+
+- ✅ **Authenticated encryption**: GCM provides both confidentiality and integrity
+- ✅ **Unique IV**: Every encryption operation generates a random IV
+- ✅ **Tamper resistance**: Auth Tag detects any modification
+- ✅ **Input validation**: Regex and custom constraints supported
+- ✅ **Safe error handling**: Controlled logs without exposing sensitive data
+- ✅ **Double-layer decryption**: Lifecycle hooks (internal) + middleware (API responses)
+
+### Best Practices
+
+1. **Key rotation**: Plan a periodic rotation process
+2. **Environment separation**: Use different keys per dev/staging/prod
+3. **Auditing**: Monitor encryption/decryption error logs
+4. **Key backup**: Keep secure copies of keys in multiple locations
+5. **Private fields**: Mark sensitive fields as "private" to exclude them from the public API
+
+## Use Cases
+
+- 🔑 Third-party API Keys
+- 🔐 Access tokens
+- 🔒 Webhook secrets
+- 💳 Sensitive information
+- 📧 SMTP credentials
+- 🔑 Application passwords
+
+## Known Limitations
+
+- ❌ **Search**: Cannot search by encrypted fields (data is encrypted in DB)
+- ❌ **Sorting**: Cannot sort by encrypted fields
+- ❌ **Filters**: Cannot apply direct filters on encrypted fields
+- ⚠️ **Performance**: Encryption/decryption adds minimal overhead (~1-2ms per operation)
+- ⚠️ **Key synchronization**: All environments sharing the same DB must use the same key
 
-## License / Licencia
+## License
 
 MIT © 2025 Growy AI
 
-## Credits / Créditos
+## Developed by
 
-**Growy AI** - Soluciones de IA y automatización empresarial
+**Growy AI** - AI and business automation solutions
 
-**Main Author / Autor principal**: Zahir El isaac
+**Main author**: Zahir El isaac
 
 ---
 
 <div align="center">
-  <p>If this plugin is useful to you, consider giving it a ⭐ on GitHub / Si este plugin te resulta útil, considera darle una ⭐ en GitHub</p>
-  <p>Made with ❤️ by Growy AI Team</p>
+  <p>If this plugin is useful to you, consider giving it a ⭐ on GitHub</p>
+  <p>Made with ❤️ by the Growy AI team</p>
 </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growy/strapi-plugin-encrypted-field",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "Campo personalizado de texto cifrado para Strapi",
   "strapi": {
     "name": "encrypted-field",