ޠj?NSrSSKJr SSKrSSKrSSKrSSKrSSKJr \R"S\RS9r \R"S\RS9r "SS \5r\R "S S 9SS j5r"S S\5rSSjr"SS5r"SS5r"SS5rg)a^Custom encryption support for LangGraph. .. warning:: This API is in beta and may change in future versions. This module provides a framework for implementing custom at-rest encryption in LangGraph applications. Similar to the Auth system, it allows developers to define custom encryption and decryption handlers that are executed server-side. ) annotationsN)types_BlobDecryptorT)bound_JsonDecryptorTc\rSrSrSrSrg)LangGraphBetaWarningz+Warning for beta features in LangGraph SDK.N__name__ __module__ __qualname____firstlineno____doc____static_attributes__r [/var/www/html/gaurav/venv/lib/python3.13/site-packages/langgraph_sdk/encryption/__init__.pyr r s5rr )maxsizec8[R"S[SS9 g)Nz@The Encryption API is in beta and may change in future versions.) stacklevel)warningswarnr r rr_warn_encryption_betars MMJrc\rSrSrSrSrg)DuplicateHandlerError&zMRaised when attempting to register a duplicate encryption/decryption handler.r Nr r rrrr&sWrrc[R"U5(d[US[U535e[R"U5nUR R 5Vs/sH-nURURUR4;dM+UPM/ nn[U5S:wa[US[U535egs snf)a Validate that a handler function has the correct signature. Args: fn: The handler function to validate handler_type: Description of the handler for error messages Raises: TypeError: If the handler is not an async function or has wrong parameter count z must be an async function, got z3 must accept exactly 2 parameters (ctx, data), got N) inspectiscoroutinefunction TypeErrortype signature parametersvalueskindPOSITIONAL_ONLYPOSITIONAL_OR_KEYWORDlen)fn handler_typesigpparamss r_validate_handlerr2,s  & &r * *<.(Hb STT   B C&&((A 66a'')@)@A A (   6{an #F } .   s ')CCc6\rSrSrSrSSjrS SjrS SjrSrg) _EncryptDecoratorsFzDecorators for encryption handlers. Provides @encryption.encrypt.blob and @encryption.encrypt.json decorators for registering encryption functions. cXlgN_parentselfparents r__init___EncryptDecorators.__init__M rcURRb [S5e[US5 XRlU$)a"Register a blob encryption handler. The handler will be called to encrypt opaque data like checkpoint blobs. Example: ```python @encryption.encrypt.blob async def encrypt_blob(ctx: EncryptionContext, blob: bytes) -> bytes: # Encrypt the blob using your encryption service return encrypted_blob ``` Args: fn: The encryption handler function Returns: The registered handler function Raises: DuplicateHandlerError: If blob encryptor already registered TypeError: If handler has invalid signature z!Blob encryptor already registeredzBlob encryptor)r9_blob_encryptorrr2r;r-s rblob_EncryptDecorators.blobP:. << ' ' 3'(KL L"./') $ rcURRb [S5e[US5 XRlU$)aRegister the JSON encryption handler. Example: ```python @encryption.encrypt.json async def encrypt_json(ctx: EncryptionContext, data: dict) -> dict: # Encrypt the data return encrypt_data(data) ``` Args: fn: The encryption handler function Returns: The registered handler function Raises: DuplicateHandlerError: If JSON encryptor already registered TypeError: If handler has invalid signature z!JSON encryptor already registeredzJSON encryptor)r9_json_encryptorrr2rBs rjson_EncryptDecorators.jsonms:* << ' ' 3'(KL L"./') $ rr8Nr< Encryption)r-types.BlobEncryptorreturnrL)r-types.JsonEncryptorrMrN r rrrrr=rCrHrr rrr4r4Fs :rr4c6\rSrSrSrSSjrS SjrS SjrSrg) _DecryptDecoratorszDecorators for decryption handlers. Provides @encryption.decrypt.blob and @encryption.decrypt.json decorators for registering decryption functions. cXlgr7r8r:s rr=_DecryptDecorators.__init__r?rcURRb [S5e[US5 XRlU$)aGRegister a blob decryption handler. The handler will be called to decrypt opaque data like checkpoint blobs. Example: ```python @encryption.decrypt.blob async def decrypt_blob( ctx: EncryptionContext, blob: bytes ) -> bytes | DecryptResult[bytes]: # Decrypt the blob using your encryption service return decrypted_blob ``` Args: fn: The decryption handler function Returns: The registered handler function Raises: DuplicateHandlerError: If blob decryptor already registered TypeError: If handler has invalid signature z!Blob decryptor already registeredzBlob decryptor)r9_blob_decryptorrr2rBs rrC_DecryptDecorators.blobs:2 << ' ' 3'(KL L"./') $ rcURRb [S5e[US5 XRlU$)aRegister the JSON decryption handler. Example: ```python @encryption.decrypt.json async def decrypt_json( ctx: EncryptionContext, data: dict ) -> dict | DecryptResult[dict]: # Decrypt the data return decrypt_data(data) ``` Args: fn: The decryption handler function Returns: The registered handler function Raises: DuplicateHandlerError: If JSON decryptor already registered TypeError: If handler has invalid signature z!JSON decryptor already registeredzJSON decryptor)r9_json_decryptorrr2rBs rrH_DecryptDecorators.jsonrErr8NrJ)r-rrMr)r-rrMrrOr rrrQrQs >rrQcl\rSrSrSrSr\rS SjrS SjrS S Sjjr S SSjjr SS jr Sr g)rKuAdd custom at-rest encryption to your LangGraph application. .. warning:: This API is in beta and may change in future versions. The Encryption class provides a system for implementing custom encryption of data at rest in LangGraph applications. It supports encryption of both opaque blobs (like checkpoints) and structured JSON data (like metadata, context, kwargs, values, etc.). To use, create a separate Python file and add the path to the file to your LangGraph API configuration file (`langgraph.json`). Within that file, create an instance of the Encryption class and register encryption and decryption handlers as needed. Example `langgraph.json` file: ```json { "dependencies": ["."], "graphs": { "agent": "./my_agent/agent.py:graph" }, "env": ".env", "encryption": { "path": "./encryption.py:my_encryption" } } ``` Then the LangGraph server will load your encryption file and use it to encrypt/decrypt data at rest. !!! warning "JSON Encryptors Must Preserve Keys" JSON encryptors **must not add or remove keys** from the input dict. Only values may be transformed. This constraint is **enforced at runtime by the server** and exists because SQL JSONB merge operations (used for partial updates) work at the key level. **Correct (per-key encryption):** ```python # Input: {"secret": "value", "plain": "x"} # Output: {"secret": "", "plain": "x"} ✓ Keys preserved ``` **Incorrect (key consolidation):** ```python # Input: {"secret": "value", "plain": "x"} # Output: {"__encrypted__": "", "plain": "x"} ✗ Key changed ``` If your encryptor needs to store auxiliary data (DEK, IV, etc.), embed it within the encrypted value itself, not as separate keys. ???+ example "Basic Usage" ```python from langgraph_sdk import Encryption, EncryptionContext my_encryption = Encryption() SKIP_FIELDS = {"tenant_id", "owner", "thread_id", "assistant_id"} ENCRYPTED_PREFIX = "encrypted:" @my_encryption.encrypt.blob async def encrypt_blob(ctx: EncryptionContext, blob: bytes) -> bytes: return your_encrypt_bytes(blob) @my_encryption.decrypt.blob async def decrypt_blob(ctx: EncryptionContext, blob: bytes) -> bytes: return your_decrypt_bytes(blob) @my_encryption.encrypt.json async def encrypt_json(ctx: EncryptionContext, data: dict) -> dict: result = {} for k, v in data.items(): if k in SKIP_FIELDS or v is None: result[k] = v else: result[k] = ENCRYPTED_PREFIX + your_encrypt_string(v) return result @my_encryption.decrypt.json async def decrypt_json(ctx: EncryptionContext, data: dict) -> dict: result = {} for k, v in data.items(): if isinstance(v, str) and v.startswith(ENCRYPTED_PREFIX): result[k] = your_decrypt_string(v[len(ENCRYPTED_PREFIX):]) else: result[k] = v return result ``` ???+ example "Field-Specific Logic" The `ctx.model` and `ctx.field` attributes tell you which model type and specific field is being encrypted, allowing different logic: ```python @my_encryption.encrypt.json async def encrypt_json(ctx: EncryptionContext, data: dict) -> dict: if ctx.field == "metadata": # Metadata - standard encryption return encrypt_standard(data) elif ctx.field == "values": # Thread values - more sensitive, use stronger encryption return encrypt_sensitive(data) else: return encrypt_standard(data) ``` !!! warning "Model/Field May Differ Between Encrypt and Decrypt" Data encrypted with one `(model, field)` pair is **not guaranteed** to be decrypted with the same pair. The server performs SQL JSONB merges that can move encrypted values between models (e.g., cron metadata → run metadata). Your decryption logic must handle data regardless of the `ctx.model` or `ctx.field` values at decrypt time. **Safe:** Use `ctx.model`/`ctx.field` for logging or metrics only. **Safe:** Encrypt different keys based on `ctx.field`, but use a single decrypt handler that decrypts any value with the encrypted prefix (and passes through plaintext unchanged): ```python ENCRYPTED_PREFIX = "enc:" @my_encryption.encrypt.json async def encrypt_json(ctx: EncryptionContext, data: dict) -> dict: # Encrypt different keys depending on the field if ctx.field == "context": keys_to_encrypt = {"api_key", "secret_token"} else: keys_to_encrypt = {"email", "ssn"} return { k: ENCRYPTED_PREFIX + encrypt(v) if k in keys_to_encrypt else v for k, v in data.items() } @my_encryption.decrypt.json async def decrypt_json(ctx: EncryptionContext, data: dict) -> dict: # Decrypt ANY value with the prefix, regardless of model/field return { k: decrypt(v[len(ENCRYPTED_PREFIX):]) if isinstance(v, str) and v.startswith(ENCRYPTED_PREFIX) else v for k, v in data.items() } ``` **Unsafe:** Using different encryption keys or algorithms based on `ctx.model`/`ctx.field` will cause decryption failures. )rVrA_context_handlerrYrGdecryptencryptc[5 [U5Ul[U5UlSUlSUlSUlSUlSUl g)z#Initialize the Encryption instance.N) rr4r_rQr^rArVrGrYr])r;s rr=Encryption.__init__sH)$/ )$/ ;?;?;?;?=ArcXlU$)a'Register a context handler to derive encryption context from auth. The handler receives the authenticated user and current EncryptionContext, and returns a dict that becomes ctx.metadata for encrypt/decrypt handlers. This allows encryption context to be derived from JWT claims or other auth-derived data instead of requiring a separate X-Encryption-Context header. Note: The context handler is called once per request in middleware, so ctx.model and ctx.field will be None in the handler. Example: ```python from langgraph_sdk import Encryption, EncryptionContext from starlette.authentication import BaseUser encryption = Encryption() @encryption.context async def get_context(user: BaseUser, ctx: EncryptionContext) -> dict: # Derive encryption context from authenticated user return { **ctx.metadata, # preserve X-Encryption-Context header if present "tenant_id": user.tenant_id, } ``` Args: fn: The context handler function Returns: The registered handler function )r]rBs rcontextEncryption.contextsD!# rNcUR$)zGet the JSON encryptor. Args: _model: Ignored. Kept for backwards compatibility with langgraph-api which passes model_type to this method. Returns: The JSON encryptor, or None if not registered. )rGr;_models rget_json_encryptorEncryption.get_json_encryptor###rcUR$)zGet the JSON decryptor. Args: _model: Ignored. Kept for backwards compatibility with langgraph-api which passes model_type to this method. Returns: The JSON decryptor, or None if not registered. )rYrfs rget_json_decryptorEncryption.get_json_decryptorrjrc/nUR(aURS5 UR(aURS5 UR(aURS5 UR(aURS5 UR (aURS5 SSR U5S3$) Nblob_encryptorblob_decryptorjson_encryptorjson_decryptorcontext_handlerzEncryption(handlers=[z, z]))rAappendrVrGrYr]join)r;handlerss r__repr__Encryption.__repr__s    OO, -    OO, -    OO, -    OO, -  OO- .&tyy':&;2>>rrMNone)r-types.ContextHandlerrMr{r7)rg str | NonerMztypes.JsonEncryptor | None)rgr|rMztypes.JsonDecryptor | None)rMstr) r rrrr __slots__rr=rcrhrlrwrr rrrKrKseZxI E B#N" $ $ $ $"" $ $ $ $ ?rrKry)r-ztyping.Callabler.r}rMrz)r __future__r functoolsr"typingrlanggraph_sdk.encryptionrTypeVar BlobDecryptorr JsonDecryptorr UserWarningr lru_cacher Exceptionrr2r4rQrKr rrrs # *..!2%:M:MN..!2%:M:MN6;6 Q  I  4@@FDDNI?I?r