devora-python 0.1.0__tar.gz

devora_python-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+build/
+.turbo/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.env
+.env.*
+!.env.example
+core/src/constants/api-url.gen.ts
+python/src/devora_sdk/api_url_gen.py
+.DS_Store

devora_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devora_python-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: devora-python
+Version: 0.1.0
+Summary: Devora Python backend SDK for secure impersonation
+Project-URL: Documentation, https://docs.devora.sh
+Project-URL: Repository, https://github.com/getdevora/devora-sdks
+Project-URL: Issues, https://github.com/getdevora/devora-sdks/issues
+Author: Devora
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backend,devora,impersonation,sdk,security
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+
+# devora-python
+
+Recording, masking and activity preferences are configured in Devora Settings.
+SDK initialization overrides are ignored. New sessions retain the server's policy
+snapshot across exchange and resume. Developer privacy labels take effect only
+when selected in Settings; sensitive-field protection remains mandatory.
+See [migration details](https://github.com/getdevora/devora-sdks/blob/main/SETTINGS.md).
+
+Python backend core SDK for Devora customer integrations.
+
+## Requirements
+
+- Python `>=3.10,<4.0`
+
+## Install
+
+```bash
+pip install devora-python
+```
+
+## Quick Start
+
+```python
+from devora_sdk import DEVORA_ENDPOINTS, devora_sdk
+
+sdk = devora_sdk(
+    api_key="pk_server_live_...",
+    secret_key="sk_server_live_...",
+    org_id="org_...",
+)
+
+@sdk.register(DEVORA_ENDPOINTS.USER_SEARCH)
+def search_users(req):
+    return {"users": search_customer_users(req.query.get("term", ""))}
+
+@sdk.register(DEVORA_ENDPOINTS.IMPERSONATE)
+def impersonate(req):
+    context = req.devora_context
+    token = create_customer_token(context.target_user["id"], context)
+    return {"token": token}
+```
+
+Use `process_request()` for sync frameworks, `async_process_request()` for
+async frameworks, or use the Django and FastAPI adapter packages.
+
+### Production replay store
+
+Every signed request carries a single-use id. In production the SDK needs a
+shared, atomic `replay_store` so a captured request cannot be replayed against
+another worker or instance; the in-memory store is for
+`environment="development"` or `"test"` only, and any other environment refuses
+to start without one.
+
+```python
+import os
+
+import redis
+from devora_sdk import devora_sdk
+
+client = redis.Redis.from_url(os.environ["REDIS_URL"])
+
+
+class RedisReplayStore:
+    def consume(self, namespace: str, request_id: str, expires_at: int) -> bool:
+        # Atomic insert-if-absent that lives until expires_at (Unix ms).
+        # Exceptions propagate: the SDK then fails closed with a 503.
+        return bool(
+            client.set(f"devora:replay:{namespace}:{request_id}", b"1", nx=True, pxat=expires_at)
+        )
+
+
+sdk = devora_sdk(
+    api_key=os.environ["DEVORA_API_KEY"],
+    secret_key=os.environ["DEVORA_SECRET_KEY"],
+    org_id=os.environ["DEVORA_ORG_ID"],
+    replay_store=RedisReplayStore(),
+)
+```
+
+`consume` is called synchronously, including from `async_process_request`;
+keep it a single short round trip. Do not let the store evict these keys
+before they expire. A unique-key database insert with an expiry column works
+too.
+
+The guard's session-liveness checker caches at most 1,024 results and permits at
+most 64 distinct concurrent lookups per checker. Requests for the same session
+share a lookup. Live/ended results use the configured TTL (five seconds by
+default); unavailable results use at most one second. Cache hits never extend a
+verdict's lifetime. Capacity exhaustion follows the configured unavailable
+policy, which denies access by default.
+
+### Cold-start latency
+
+The impersonation guard's scope policy is fetched lazily on first use, so the
+first request handled by a freshly started worker process pays for that fetch
+synchronously (and any request racing it gets a `503
+IMPERSONATION_POLICY_UNAVAILABLE` rather than waiting). If your deployment
+runs multiple worker processes (gunicorn, uWSGI, etc.), pass
+`prefetch_scope_config=True` to warm the cache in the background as soon as
+`devora_sdk(...)` is constructed, before the process starts serving traffic:
+
+```python
+sdk = devora_sdk(
+    api_key="pk_server_live_...",
+    secret_key="sk_server_live_...",
+    org_id="org_...",
+    prefetch_scope_config=True,
+)
+```

devora_python-0.1.0/README.md

@@ -0,0 +1,109 @@
+# devora-python
+
+Recording, masking and activity preferences are configured in Devora Settings.
+SDK initialization overrides are ignored. New sessions retain the server's policy
+snapshot across exchange and resume. Developer privacy labels take effect only
+when selected in Settings; sensitive-field protection remains mandatory.
+See [migration details](https://github.com/getdevora/devora-sdks/blob/main/SETTINGS.md).
+
+Python backend core SDK for Devora customer integrations.
+
+## Requirements
+
+- Python `>=3.10,<4.0`
+
+## Install
+
+```bash
+pip install devora-python
+```
+
+## Quick Start
+
+```python
+from devora_sdk import DEVORA_ENDPOINTS, devora_sdk
+
+sdk = devora_sdk(
+    api_key="pk_server_live_...",
+    secret_key="sk_server_live_...",
+    org_id="org_...",
+)
+
+@sdk.register(DEVORA_ENDPOINTS.USER_SEARCH)
+def search_users(req):
+    return {"users": search_customer_users(req.query.get("term", ""))}
+
+@sdk.register(DEVORA_ENDPOINTS.IMPERSONATE)
+def impersonate(req):
+    context = req.devora_context
+    token = create_customer_token(context.target_user["id"], context)
+    return {"token": token}
+```
+
+Use `process_request()` for sync frameworks, `async_process_request()` for
+async frameworks, or use the Django and FastAPI adapter packages.
+
+### Production replay store
+
+Every signed request carries a single-use id. In production the SDK needs a
+shared, atomic `replay_store` so a captured request cannot be replayed against
+another worker or instance; the in-memory store is for
+`environment="development"` or `"test"` only, and any other environment refuses
+to start without one.
+
+```python
+import os
+
+import redis
+from devora_sdk import devora_sdk
+
+client = redis.Redis.from_url(os.environ["REDIS_URL"])
+
+
+class RedisReplayStore:
+    def consume(self, namespace: str, request_id: str, expires_at: int) -> bool:
+        # Atomic insert-if-absent that lives until expires_at (Unix ms).
+        # Exceptions propagate: the SDK then fails closed with a 503.
+        return bool(
+            client.set(f"devora:replay:{namespace}:{request_id}", b"1", nx=True, pxat=expires_at)
+        )
+
+
+sdk = devora_sdk(
+    api_key=os.environ["DEVORA_API_KEY"],
+    secret_key=os.environ["DEVORA_SECRET_KEY"],
+    org_id=os.environ["DEVORA_ORG_ID"],
+    replay_store=RedisReplayStore(),
+)
+```
+
+`consume` is called synchronously, including from `async_process_request`;
+keep it a single short round trip. Do not let the store evict these keys
+before they expire. A unique-key database insert with an expiry column works
+too.
+
+The guard's session-liveness checker caches at most 1,024 results and permits at
+most 64 distinct concurrent lookups per checker. Requests for the same session
+share a lookup. Live/ended results use the configured TTL (five seconds by
+default); unavailable results use at most one second. Cache hits never extend a
+verdict's lifetime. Capacity exhaustion follows the configured unavailable
+policy, which denies access by default.
+
+### Cold-start latency
+
+The impersonation guard's scope policy is fetched lazily on first use, so the
+first request handled by a freshly started worker process pays for that fetch
+synchronously (and any request racing it gets a `503
+IMPERSONATION_POLICY_UNAVAILABLE` rather than waiting). If your deployment
+runs multiple worker processes (gunicorn, uWSGI, etc.), pass
+`prefetch_scope_config=True` to warm the cache in the background as soon as
+`devora_sdk(...)` is constructed, before the process starts serving traffic:
+
+```python
+sdk = devora_sdk(
+    api_key="pk_server_live_...",
+    secret_key="sk_server_live_...",
+    org_id="org_...",
+    prefetch_scope_config=True,
+)
+```

devora_python-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "devora-python"
+version = "0.1.0"
+description = "Devora Python backend SDK for secure impersonation"
+readme = "README.md"
+requires-python = ">=3.10,<4.0"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Devora" }]
+keywords = ["devora", "sdk", "impersonation", "backend", "security"]
+classifiers = [
+	"Development Status :: 5 - Production/Stable",
+	"Intended Audience :: Developers",
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3.10",
+	"Programming Language :: Python :: 3.11",
+	"Programming Language :: Python :: 3.12",
+	"Programming Language :: Python :: 3.13",
+	"Programming Language :: Python :: 3.14",
+	"Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Documentation = "https://docs.devora.sh"
+Repository = "https://github.com/getdevora/devora-sdks"
+Issues = "https://github.com/getdevora/devora-sdks/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/devora_sdk"]
+# Generated at build time and git-ignored; included explicitly so a .gitignore
+# rule can never drop it from the distribution.
+artifacts = ["src/devora_sdk/api_url_gen.py"]
+
+[tool.hatch.build]
+artifacts = ["src/devora_sdk/api_url_gen.py"]
+
+[tool.hatch.build.targets.sdist]
+# Tests and local tooling stay in the repository; the sdist carries the package.
+include = ["src", "README.md", "LICENSE", "pyproject.toml"]

devora_python-0.1.0/src/devora_sdk/__init__.py

@@ -0,0 +1,92 @@
+from .security import validate_timestamp_tolerance
+from .constants import DEVORA_ENDPOINTS, ENDPOINT_METHODS, PROTECTED_ENDPOINTS, SECURITY_HEADERS
+from .guard import (
+	METHOD_OVERRIDE_HEADERS,
+	GuardDecision,
+	ImpersonationContext,
+	InvalidImpersonationContext,
+	ScopeEndpoint,
+	SessionLivenessChecker,
+	coerce_impersonation_context,
+	evaluate_impersonation_guard,
+	policy_methods,
+	validate_impersonation_context,
+)
+from .handler import (
+	AdapterRequest,
+	ProcessRequestOptions,
+	async_process_request,
+	create_generic_handler,
+	process_request,
+)
+from .hmac import sha256_hex, sign_request
+from .signing import (
+	CUSTOMER_TO_DEVORA,
+	DEVORA_TO_CUSTOMER,
+	build_canonical_string,
+	build_strict_query,
+	encode_path_param,
+	route_relative_path,
+	strict_encode,
+)
+from .transport import ControlPlaneError
+from .models import (
+	DevoraImpersonationContext,
+	DevoraRequest,
+	DevoraResponse,
+	SDKRoute,
+	SDKStats,
+	ValidationResult,
+)
+from .policy import ScopeConfig, ScopeConfigFetcher
+from .sdk import DevoraBackendSDK, devora_sdk
+from .replay import InMemoryReplayStore, ReplayStore
+from .browser_session import resolve_browser_session
+from .constants import BROWSER_SESSION_BRIDGE_PATH
+
+__all__ = [
+	"AdapterRequest",
+	"DEVORA_ENDPOINTS",
+	"ENDPOINT_METHODS",
+	"PROTECTED_ENDPOINTS",
+	"SECURITY_HEADERS",
+	"DevoraBackendSDK",
+	"DevoraImpersonationContext",
+	"DevoraRequest",
+	"DevoraResponse",
+	"GuardDecision",
+	"ImpersonationContext",
+	"InMemoryReplayStore",
+	"ProcessRequestOptions",
+	"ReplayStore",
+	"SDKRoute",
+	"SDKStats",
+	"ScopeConfig",
+	"ScopeEndpoint",
+	"ScopeConfigFetcher",
+	"SessionLivenessChecker",
+	"ValidationResult",
+	"async_process_request",
+	"resolve_browser_session",
+	"BROWSER_SESSION_BRIDGE_PATH",
+	"create_generic_handler",
+	"devora_sdk",
+	"evaluate_impersonation_guard",
+	"coerce_impersonation_context",
+	"InvalidImpersonationContext",
+	"METHOD_OVERRIDE_HEADERS",
+	"policy_methods",
+	"validate_timestamp_tolerance",
+	"process_request",
+	"sign_request",
+	"sha256_hex",
+	"build_canonical_string",
+	"build_strict_query",
+	"encode_path_param",
+	"route_relative_path",
+	"strict_encode",
+	"CUSTOMER_TO_DEVORA",
+	"DEVORA_TO_CUSTOMER",
+	"ControlPlaneError",
+	"validate_impersonation_context",
+]

devora_python-0.1.0/src/devora_sdk/api_url_gen.py

@@ -0,0 +1,2 @@
+# Generated by scripts/generate-api-url.mjs - do not edit
+DEVORA_API_ORIGIN = "https://beloved-bee-737.convex.site"

devora_python-0.1.0/src/devora_sdk/browser_session.py

@@ -0,0 +1,45 @@
+"""Browser-session bridge (server side). See @devorash/node browser-session.ts."""
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from .constants import TAB_REF_PATTERN
+from .guard import validate_impersonation_context
+
+
+def resolve_browser_session(
+	sdk: Any,
+	context: Any,
+	tab_ref: Any,
+	origin: Optional[str],
+	allowed_origins: Optional[list[str]] = None,
+) -> tuple[int, dict[str, Any]]:
+	"""Return ``(status_code, body)`` for the bridge route.
+
+	Ordinary customer sessions return ``{"status": "none"}`` without contacting
+	Devora. Impersonated sessions receive a one-time resume code, or ``blocked``
+	when Devora cannot safely restore them.
+	"""
+	if not isinstance(tab_ref, str) or not re.fullmatch(TAB_REF_PATTERN, tab_ref):
+		return 400, {"error": "Invalid tab reference"}
+	if context is None or getattr(context, "is_impersonation", None) is False:
+		return 200, {"status": "none"}
+	# Origin only matters once we're about to mint a resume code for a real
+	# impersonation session; ordinary traffic through this bridge is unaffected.
+	# An Origin header must be listed in allowed_origins (unconfigured fails
+	# closed). Devora binds every resume code to the origin that will redeem it,
+	# so a request without an Origin header cannot use one and gets none.
+	if origin and (allowed_origins is None or origin not in allowed_origins):
+		return 403, {"error": "Invalid request origin"}
+	# The same strict validation as the guard: malformed or expired contexts
+	# never mint a resume code.
+	if not origin or not validate_impersonation_context(context)["valid"]:
+		return 200, {"status": "blocked", "reason": "session_invalid"}
+	session_id = context.session_id
+	result = sdk.create_browser_resume_code(session_id, tab_ref, origin)
+	if result is None:
+		return 200, {"status": "blocked", "reason": "control_plane_unavailable"}
+	if "error" in result:
+		return 200, {"status": "blocked", "reason": "session_invalid"}
+	return 200, {"status": "resume", "code": result["code"]}

devora_python-0.1.0/src/devora_sdk/constants.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from .api_url_gen import DEVORA_API_ORIGIN
+
+
+class DEVORA_ENDPOINTS:
+	USER_SEARCH = "/user/search"
+	USER_BY_ID = "/user/:id"
+	IMPERSONATE = "/impersonate/:id"
+	TERMINATE = "/impersonate/:id/terminate"
+	TEST = "/test"
+	HEALTH = "/health"
+
+
+ENDPOINT_METHODS = {
+	DEVORA_ENDPOINTS.USER_SEARCH: "GET",
+	DEVORA_ENDPOINTS.USER_BY_ID: "GET",
+	DEVORA_ENDPOINTS.IMPERSONATE: "POST",
+	DEVORA_ENDPOINTS.TERMINATE: "DELETE",
+	DEVORA_ENDPOINTS.TEST: "GET",
+	DEVORA_ENDPOINTS.HEALTH: "GET",
+}
+
+PROTECTED_ENDPOINTS = (DEVORA_ENDPOINTS.TEST, DEVORA_ENDPOINTS.HEALTH)
+
+
+class SECURITY_HEADERS:
+	SIGNATURE = "x-devora-signature"
+	SENT_AT = "x-devora-sent-at"
+	KEY_ID = "x-devora-key-id"
+	ORG_ID = "x-devora-org-id"
+	REQUEST_ID = "x-devora-request-id"
+	SIGNATURE_VERSION = "x-devora-signature-version"
+	SESSION_ID = "x-devora-session-id"
+
+
+SDK_VERSION = "0.1.0"
+DEFAULT_API_URL = DEVORA_API_ORIGIN
+DEFAULT_TIMESTAMP_TOLERANCE_SECONDS = 300
+DEFAULT_MAX_BODY_SIZE_BYTES = 1024 * 1024
+WRITE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+
+
+# Browser-session bridge (see @devorash/core BROWSER_SESSION_BRIDGE).
+BROWSER_SESSION_BRIDGE_PATH = "/api/devora/browser-session"
+BROWSER_RESUME_CODE_ENDPOINT = "/api/sdk/browser-resume-code"
+BROWSER_RESUME_ENDPOINT = "/api/sdk/browser-resume"
+# \Z, not $: $ also matches before a trailing newline.
+TAB_REF_PATTERN = r"^[A-Za-z0-9_-]{4,96}\Z"