Implementation:OpenHands OpenHands EncryptUtils

Knowledge Sources	OpenHands
Domains	Security, Encryption, Storage
Last Updated	2026-02-11 21:00 GMT

Overview

Concrete tools for encrypting and decrypting sensitive values using dual encryption strategies (JWE current, Fernet legacy), plus ORM serialization helpers, provided by the OpenHands enterprise storage layer.

Description

The encrypt_utils module provides a unified encryption interface that supports two encryption backends and handles the transition from the legacy system to the current one.

The encrypt_value function encrypts a plaintext string for secure storage. It uses the current encryption backend (JWE via JSON Web Encryption) to produce an encrypted ciphertext. All new encryption operations use this function, which delegates to get_jwt_service for key material and algorithm selection.

The decrypt_value function decrypts a stored ciphertext back to plaintext. It implements a dual-decryption strategy: it first attempts decryption using the current JWE backend, and if that fails (indicating the value was encrypted with the legacy system), falls back to Fernet decryption via get_fernet. This enables seamless migration from the legacy encryption scheme without requiring a bulk re-encryption of all stored values.

The get_jwt_service function initializes and returns the JWE encryption service configured with the appropriate key material from the application's secret management. It handles key loading, algorithm configuration (typically A256KW key wrapping with A256GCM content encryption), and service caching.

The get_fernet function initializes and returns a Fernet encryption instance for legacy decryption. Fernet provides symmetric authenticated encryption using the cryptography library. This function is used exclusively in the fallback path of decrypt_value for values that were encrypted before the migration to JWE.

The model_to_kwargs function is a serialization utility that converts a SQLAlchemy ORM model instance into a dictionary of keyword arguments suitable for reconstructing the model or passing to other functions. It handles column extraction, type coercion, and optional field exclusion.

Usage

Use encrypt_value and decrypt_value for all sensitive data that must be stored encrypted (OAuth tokens, API secrets, user credentials). The dual-decryption strategy in decrypt_value is transparent to callers; no special handling is needed for legacy vs. current encrypted values. Use model_to_kwargs when serializing ORM models for cross-boundary transfer or reconstruction.

Code Reference

Source Location

• Repository: OpenHands
• File: enterprise/storage/encrypt_utils.py
• Lines: 1-137

Signature

def encrypt_value(plaintext: str) -> str:
    ...

def decrypt_value(ciphertext: str) -> str:
    ...

def get_jwt_service():
    ...

def get_fernet():
    ...

def model_to_kwargs(
    model_instance,
    exclude: set[str] | None = None,
) -> dict:
    ...

Import

from enterprise.storage.encrypt_utils import encrypt_value, decrypt_value

I/O Contract

Inputs

Name	Type	Required	Description
plaintext	str	Yes	The sensitive value to encrypt (for encrypt_value)
ciphertext	str	Yes	The encrypted value to decrypt; may be either JWE or Fernet format (for decrypt_value)
model_instance	ORM model	Yes	A SQLAlchemy model instance to serialize (for model_to_kwargs)
exclude	set[str] or None	No	Set of column names to exclude from the output dictionary (for model_to_kwargs)

Outputs

Name	Type	Description
ciphertext	str	The JWE-encrypted representation of the input plaintext (from encrypt_value)
plaintext	str	The decrypted plaintext value (from decrypt_value)
jwt_service	service object	The configured JWE encryption service instance (from get_jwt_service)
fernet	Fernet	The configured Fernet encryption instance (from get_fernet)
kwargs	dict	Dictionary of column name to value mappings from the ORM model (from model_to_kwargs)

Encryption Strategy

Backend	Algorithm	Status	Usage
JWE (JSON Web Encryption)	A256KW + A256GCM	Current	All new encrypt operations; primary decrypt path
Fernet	AES-128-CBC + HMAC-SHA256	Legacy	Decrypt fallback only; no new encryptions

The dual-decryption flow in decrypt_value:

  ciphertext --> try JWE decrypt
                   |
                success --> return plaintext
                   |
                failure --> try Fernet decrypt
                              |
                           success --> return plaintext
                              |
                           failure --> raise DecryptionError

Usage Examples

from enterprise.storage.encrypt_utils import encrypt_value, decrypt_value, model_to_kwargs

# Encrypt a sensitive value before storing
encrypted_token = encrypt_value("gho_abc123secrettoken")

# Store encrypted_token in the database...

# Later, decrypt the value (handles both JWE and legacy Fernet)
original_token = decrypt_value(encrypted_token)

# Serialize an ORM model to kwargs
from enterprise.storage.auth_token_store import AuthToken
token_record = session.query(AuthToken).first()
kwargs = model_to_kwargs(token_record, exclude={"id", "created_at"})

Related Pages

Environment

• Environment:OpenHands_OpenHands_SaaS_Server_Environment