adk-secure-sessions¶

Encrypted session storage for Google ADK

adk-secure-sessions is an encrypted session persistence service implementing ADK's BaseSessionService that encrypts session data at rest. Built for applications in healthcare, finance, and other regulated industries.

Quick Links¶

Features¶

• BaseSessionService Implementation: Implements ADK's BaseSessionService — use it anywhere ADK expects a session service
• Pluggable Backends: EncryptionBackend protocol — ships with FernetBackend; custom backends planned for Phase 3
• Field-Level Encryption: State values and events encrypted; IDs and timestamps stay queryable
• Multi-Database Support: SQLite, PostgreSQL, MySQL, and MariaDB via DatabaseSessionService
• Async-First: Wraps ADK's DatabaseSessionService, matching ADK's async runtime
• Well-Documented: Google-style docstrings with 95%+ coverage

Installation¶

uv add adk-secure-sessions

Basic Usage¶

from adk_secure_sessions import (
    EncryptedSessionService,
    FernetBackend,
    BACKEND_FERNET,
)

# Create encryption backend
backend = FernetBackend("your-secret-passphrase")

# Use as async context manager
async with EncryptedSessionService(
    db_url="sqlite+aiosqlite:///sessions.db",
    backend=backend,
) as service:
    # Create encrypted session
    session = await service.create_session(
        app_name="my-agent",
        user_id="user-123",
        state={"api_key": "sk-secret"},
    )

    # Retrieve with automatic decryption
    session = await service.get_session(
        app_name="my-agent",
        user_id="user-123",
        session_id=session.id,
    )

Custom Encryption Backend¶

The EncryptionBackend protocol defines the contract for encryption backends. Currently only FernetBackend is fully supported; generalized multi-backend dispatch is planned for Phase 3 (see Roadmap). The protocol already enables runtime validation and static type checking:

from adk_secure_sessions import EncryptionBackend

class MyBackend:
    async def encrypt(self, plaintext: bytes) -> bytes: ...
    async def decrypt(self, ciphertext: bytes) -> bytes: ...

assert isinstance(MyBackend(), EncryptionBackend)  # True

Project Status¶

Alpha — core functionality complete. EncryptedSessionService and FernetBackend are implemented and tested. See the Roadmap for planned features and Architecture Decision Records for design rationale.

License¶

Apache License 2.0 - see LICENSE for details.