feat: custom encryption at rest (#6482)

**Description:** 
This PR adds the Python SDK types necessary for langgraph platform users
to inject their own custom encryption-at-rest functions. See [docs
PR](https://github.com/langchain-ai/docs/pull/1715) for more details.

note: this PR adds a starlette dev dependency so that custom encryption
can access BaseUser information.

**Issue:**
required for LSD-172 

**Dependencies:**
- [depended upon by associated langgraph-api
changes](https://github.com/langchain-ai/langgraph-api/pull/1773)(this
PR must merge before that one)
- [docs PR](https://github.com/langchain-ai/docs/pull/1715)

**TODO:**
- [x] move docs to docs repo
- [x] bump package versions before merge

---------

Signed-off-by: Connor Braa <cwlbraa@langchain.dev>
Co-authored-by: Claude <noreply@anthropic.com>

libs/cli/langgraph_cli/config.py

@@ -154,6 +154,7 @@ def validate_config(config: Config) -> Config:
         "env": config.get("env", {}),
         "store": config.get("store"),
         "auth": config.get("auth"),
+        "encryption": config.get("encryption"),
         "http": config.get("http"),
         "checkpointer": config.get("checkpointer"),
         "ui": config.get("ui"),
@@ -228,6 +229,14 @@ def validate_config(config: Config) -> Config:
                     f"Invalid auth.path format: '{auth_conf['path']}'. "
                     "Must be in format './path/to/file.py:attribute_name'"
                 )
+    # Validate encryption config
+    if encryption_conf := config.get("encryption"):
+        if "path" in encryption_conf:
+            if ":" not in encryption_conf["path"]:
+                raise ValueError(
+                    f"Invalid encryption.path format: '{encryption_conf['path']}'. "
+                    "Must be in format './path/to/file.py:attribute_name'"
+                )
     if http_conf := config.get("http"):
         if "app" in http_conf:
             if ":" not in http_conf["app"]:
@@ -614,6 +623,49 @@ def _update_auth_path(
     )
 
 
+def _update_encryption_path(
+    config_path: pathlib.Path, config: Config, local_deps: LocalDeps
+) -> None:
+    """Update encryption.path to use Docker container paths."""
+    encryption_conf = config.get("encryption")
+    if not encryption_conf or not (path_str := encryption_conf.get("path")):
+        return
+
+    module_str, sep, attr_str = path_str.partition(":")
+    if not sep or not module_str.startswith("."):
+        return  # Already validated or absolute path
+
+    resolved = config_path.parent / module_str
+    if not resolved.exists():
+        raise FileNotFoundError(
+            f"Encryption file not found: {resolved} (from {path_str})"
+        )
+    if not resolved.is_file():
+        raise IsADirectoryError(f"Encryption path must be a file: {resolved}")
+
+    # Check faux packages first (higher priority)
+    for faux_path, (_, destpath) in local_deps.faux_pkgs.items():
+        if resolved.is_relative_to(faux_path):
+            new_path = f"{destpath}/{resolved.relative_to(faux_path)}:{attr_str}"
+            encryption_conf["path"] = new_path
+            return
+
+    # Check real packages
+    for real_path in local_deps.real_pkgs:
+        if resolved.is_relative_to(real_path):
+            new_path = (
+                f"/deps/{real_path.name}/{resolved.relative_to(real_path)}:{attr_str}"
+            )
+            encryption_conf["path"] = new_path
+            return
+
+    raise ValueError(
+        f"Encryption file '{resolved}' not covered by dependencies.\n"
+        "Add its parent directory to the 'dependencies' array in your config.\n"
+        f"Current dependencies: {config['dependencies']}"
+    )
+
+
 def _update_http_app_path(
     config_path: pathlib.Path, config: Config, local_deps: LocalDeps
 ) -> None:
@@ -809,6 +861,8 @@ def python_config_to_docker(
     _update_graph_paths(config_path, config, local_deps)
     # Rewrite auth path, so it points to the correct location in the Docker container
     _update_auth_path(config_path, config, local_deps)
+    # Rewrite encryption path, so it points to the correct location in the Docker container
+    _update_encryption_path(config_path, config, local_deps)
     # Rewrite HTTP app path, so it points to the correct location in the Docker container
     _update_http_app_path(config_path, config, local_deps)
 
@@ -899,6 +953,9 @@ ADD {relpath} /deps/{name}
     if (auth_config := config.get("auth")) is not None:
         env_vars.append(f"ENV LANGGRAPH_AUTH='{json.dumps(auth_config)}'")
 
+    if (encryption_config := config.get("encryption")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_ENCRYPTION='{json.dumps(encryption_config)}'")
+
     if (http_config := config.get("http")) is not None:
         env_vars.append(f"ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'")
 
@@ -1022,6 +1079,9 @@ def node_config_to_docker(
     if (auth_config := config.get("auth")) is not None:
         env_vars.append(f"ENV LANGGRAPH_AUTH='{json.dumps(auth_config)}'")
 
+    if (encryption_config := config.get("encryption")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_ENCRYPTION='{json.dumps(encryption_config)}'")
+
     if (http_config := config.get("http")) is not None:
         env_vars.append(f"ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'")
 

libs/cli/langgraph_cli/schemas.py

@@ -302,6 +302,27 @@ class AuthConfig(TypedDict, total=False):
     """
 
 
+class EncryptionConfig(TypedDict, total=False):
+    """Configuration for custom at-rest encryption logic.
+
+    Allows you to implement custom encryption for sensitive data stored in the database,
+    including metadata fields and checkpoint blobs.
+    """
+
+    path: str
+    """Required. Path to an instance of the Encryption() class that implements custom encryption handlers.
+
+    Format: "path/to/file.py:my_encryption"
+
+    Example:
+        {
+            "encryption": {
+                "path": "./encryption.py:my_encryption"
+            }
+        }
+    """
+
+
 class CorsConfig(TypedDict, total=False):
     """Specifies Cross-Origin Resource Sharing (CORS) rules for your server.
 
@@ -577,10 +598,16 @@ class Config(TypedDict, total=False):
     """
 
     auth: AuthConfig | None
-    """Optional. Custom authentication config, including the path to your Python auth logic and 
+    """Optional. Custom authentication config, including the path to your Python auth logic and
     the OpenAPI security definitions it uses.
     """
 
+    encryption: EncryptionConfig | None
+    """Optional. Custom at-rest encryption config, including the path to your Python encryption logic.
+
+    Allows you to implement custom encryption for sensitive data stored in the database.
+    """
+
     http: HttpConfig | None
     """Optional. Configuration for the built-in HTTP server, controlling which custom routes are exposed
     and how cross-origin requests are handled.
@@ -603,6 +630,7 @@ __all__ = [
     "StoreConfig",
     "CheckpointerConfig",
     "AuthConfig",
+    "EncryptionConfig",
     "HttpConfig",
     "MiddlewareOrders",
     "Distros",