Encryption

NodeLoom uses AES-256-GCM encryption to protect credentials, OAuth secrets, and other sensitive data at rest. This page covers the encryption architecture, key management, and important operational considerations.

Encryption Algorithm

All sensitive data stored in the database is encrypted using AES-256-GCM (Advanced Encryption Standard with 256-bit keys in Galois/Counter Mode). GCM provides both confidentiality and authenticity -- encrypted data cannot be read or tampered with without the correct key.

Property	Value
Algorithm	AES-256-GCM
Key size	256 bits (32 bytes minimum)
IV/Nonce	Randomly generated per encryption
Authentication tag	Included for tamper detection
Encrypted data types	Credentials, OAuth client secrets, SCIM bearer tokens

APP_ENCRYPTION_KEY

The encryption key is provided via the APP_ENCRYPTION_KEY environment variable. This key must be at least 32 characters long and should be a cryptographically random string.

Setting the encryption key

# Generate a secure random key
openssl rand -base64 48

# Set it in your environment
export APP_ENCRYPTION_KEY="your-cryptographically-random-key-here-min-32-chars"

Keep this key safe

The encryption key is the master secret for all credential data in NodeLoom. If you lose this key, all encrypted credentials become permanently unreadable. Store it in a secure secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault, or your cloud provider's KMS).

Weak Key Detection

In production mode, NodeLoom validates the encryption key at startup and rejects keys that match common insecure patterns such as placeholder values, trivially guessable strings, and keys copied from documentation. Always use a cryptographically random key generated with openssl rand -base64 48.

Best practice

Always use a cryptographically random key in all environments, including development. This ensures consistent behavior and prevents accidental deployment of weak keys to production.

What Is Encrypted

The following data is encrypted at rest in the database:

Data Type	Description
Credentials	All credential values (API keys, passwords, access tokens, etc.) stored via the credential management system.
OAuth client secrets	Client secrets for OAuth 2.0 integrations configured in the workspace.
SCIM bearer tokens	Tokens used for SCIM 2.0 provisioning with identity providers.

Non-sensitive data such as workflow definitions, node configurations, user profiles, and execution logs are stored unencrypted for performance and queryability.

Session Security

User authentication tokens are stored in secure, httpOnly cookies. This approach prevents client-side JavaScript from accessing the token, mitigating XSS-based token theft.

httpOnly: The cookie cannot be read by JavaScript, only sent automatically by the browser.
Secure: The cookie is only transmitted over HTTPS connections.
SameSite: Configured to prevent CSRF attacks by restricting cross-origin cookie transmission.

Changing the Encryption Key

If you need to change the encryption key (for example, due to a suspected compromise), be aware of the following critical implications:

Existing credentials become unreadable

Changing the APP_ENCRYPTION_KEY environment variable without migrating existing data will make all previously encrypted credentials permanently unreadable. Follow the manual rotation procedure below to safely change the key.

To safely rotate the encryption key:

Export all credentials using the current key (via the API or dashboard export).
Update the APP_ENCRYPTION_KEY environment variable to the new key.
Restart the NodeLoom backend.
Re-import all credentials. They will be encrypted with the new key.

Plan ahead

Document your key rotation procedure and test it in a staging environment before performing it in production. Ensure all team members who manage credentials are notified before the rotation.

Audit Logs

Anomaly Detection