haive.core.persistence.serializers

Custom serializers for LangGraph persistence with SecretStr support.

This module provides secure serialization for SecretStr and other sensitive data while maintaining security and avoiding the pickle_fallback security issue. Supports both basic secure serialization and production-grade encryption.

Classes

SecretStrSerializer	Alternative serializer that preserves SecretStr values using model_dump.
SecureSecretStrSerializer	Custom serializer that handles SecretStr securely.

Functions

create_encrypted_serializer_for_postgres(connection_string)	Create an encrypted serializer specifically optimized for PostgreSQL.
create_production_serializer([encryption_key])	Create a production-ready serializer with optional encryption.

Module Contents

class haive.core.persistence.serializers.SecretStrSerializer(*, pickle_fallback=False, __unpack_ext_hook__=None)

Bases: langgraph.checkpoint.serde.jsonplus.JsonPlusSerializer

Alternative serializer that preserves SecretStr values using model_dump.

WARNING: This approach exposes the actual secret values during serialization. Only use this if you have proper encryption at the storage layer.

Parameters:

• pickle_fallback (bool)

• __unpack_ext_hook__ (Callable[[int, bytes], Any] | None)

class haive.core.persistence.serializers.SecureSecretStrSerializer(*, pickle_fallback=False, __unpack_ext_hook__=None)

Bases: langgraph.checkpoint.serde.jsonplus.JsonPlusSerializer

Custom serializer that handles SecretStr securely.

This serializer extends JsonPlusSerializer to handle SecretStr objects by converting them to masked values during serialization, preserving security while avoiding serialization errors.

Parameters:

• pickle_fallback (bool)

• __unpack_ext_hook__ (Callable[[int, bytes], Any] | None)

dumps(obj)

Override dumps to handle SecretStr objects before JSON serialization.

Parameters:

obj (Any)

Return type:

bytes

loads_typed(data)

Override to handle loading of masked secrets.

Parameters:

data (tuple[str, bytes])

Return type:

Any

haive.core.persistence.serializers.create_encrypted_serializer_for_postgres(connection_string, encryption_key=None)

Create an encrypted serializer specifically optimized for PostgreSQL.

This function creates a production-ready encrypted serializer that’s optimized for PostgreSQL storage. It includes additional security measures and PostgreSQL-specific optimizations.

Parameters:

• connection_string (str) – PostgreSQL connection string for logging/validation

• encryption_key (str | None) – AES encryption key. If not provided, will try LANGGRAPH_AES_KEY environment variable.

Returns:

Production-ready encrypted serializer

Return type:

JsonPlusSerializer

Raises:

ValueError – If no encryption key is available in production

Examples

Production PostgreSQL setup:

serializer = create_encrypted_serializer_for_postgres(
    connection_string="postgresql://user:pass@host:5432/db",
    encryption_key=os.getenv("LANGGRAPH_AES_KEY")
)

haive.core.persistence.serializers.create_production_serializer(encryption_key=None)

Create a production-ready serializer with optional encryption.

This function creates the appropriate serializer based on environment and security requirements. For production, it uses EncryptedSerializer when an encryption key is available, otherwise falls back to SecureSecretStrSerializer.

Parameters:

encryption_key (str | None) – Optional AES encryption key. If not provided, will try to load from LANGGRAPH_AES_KEY environment variable.

Returns:

Either EncryptedSerializer or SecureSecretStrSerializer

Return type:

JsonPlusSerializer

Examples

Basic usage with environment key:

# Set LANGGRAPH_AES_KEY environment variable
serializer = create_production_serializer()

With explicit key:

serializer = create_production_serializer("your-32-byte-key-here")

Development (no encryption):

serializer = create_production_serializer(encryption_key=None)