devora-python 0.1.0__tar.gz → 0.1.2__tar.gz

devora_python-0.1.2/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: devora-python
+Version: 0.1.2
+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 capture policy are configured in the Devora dashboard and
+authorized server-side for each session. This backend SDK takes no capture
+settings, and `devora_sdk()` ignores keyword arguments it does not recognize,
+so check option names carefully. See
+[capture settings](https://github.com/getdevora/devora-sdks/blob/main/SETTINGS.md).
+
+Python backend core SDK for Devora customer integrations.
+
+## Requirements
+
+- Python `>=3.10,<4.0`
+- Outbound HTTPS access from your backend to the Devora API
+
+## Install
+
+```bash
+pip install devora-python
+```
+
+## Quick Start
+
+```python
+import os
+from dataclasses import asdict
+
+from devora_sdk import DEVORA_ENDPOINTS, devora_sdk
+
+sdk = devora_sdk(
+    api_key=os.environ["DEVORA_API_KEY"],  # pk_server_live_...
+    secret_key=os.environ["DEVORA_SECRET_KEY"],  # sk_server_live_...
+    org_id=os.environ["DEVORA_ORG_ID"],
+)
+
+
+@sdk.register(DEVORA_ENDPOINTS.USER_SEARCH)
+def search_users(req):
+    # Match name, email and the exact user ID with a parameterised query.
+    term = req.query.get("term", "")
+    limit = int(req.query.get("limit", 10))
+    users = search_customer_users(term, limit)
+    return {
+        "users": [
+            {
+                "id": u.id,
+                "name": u.name,
+                "email": u.email,
+                "attributes": {"company": u.company, "role": u.role, "plan": u.plan},
+            }
+            for u in users
+        ]
+    }
+
+
+@sdk.register(DEVORA_ENDPOINTS.IMPERSONATE)
+def impersonate(req):
+    ctx = req.devora_context
+    if not ctx:
+        raise ValueError("Missing impersonation context")
+    # Store the whole verified context in the token: the scope guard reads every
+    # field of it back. Expire the token no later than ctx.expires_at.
+    devora = {**asdict(ctx), "is_impersonation": True}
+    token = create_customer_token(ctx.target_user["id"], devora)
+    return {"token": token}
+
+
+@sdk.register(DEVORA_ENDPOINTS.TERMINATE)
+def terminate(req):
+    session_id = req.params["id"]
+    reason = (req.body or {}).get("reason")
+    # YOU IMPLEMENT: mark this Devora session revoked so every credential issued for it
+    # is rejected, including one issued after this call. Must be idempotent: Devora
+    # retries with a new request id (up to 5 attempts over 6 hours).
+    auth.revoke_impersonation_session(session_id=session_id, reason=reason)
+    return {"success": True}
+```
+
+User search should match name, email and the exact user ID. `attributes` are optional display fields such as company, role or plan: up to 12 per user, lowercase keys like `last_login`, and string, number, boolean or `null` values. Devora drops invalid entries silently; see [Search results and templates](https://docs.devora.sh/guide/search-results) for the limits and how your team lays out results.
+
+Each verified request is claimed once from Devora before your handler runs, so
+replay protection needs no storage on your side; your backend only needs
+outbound HTTPS access to the Devora API. See [Replay protection](#replay-protection).
+
+Register every handler, then mount the SDK with the
+[Django](https://pypi.org/project/devora-django/) or
+[FastAPI](https://pypi.org/project/devora-fastapi/) adapter. For any other
+framework, pass the request exactly as received to `process_request` (sync) or
+`await async_process_request` (async):
+
+```python
+from devora_sdk import AdapterRequest, process_request
+from devora_sdk.utils import get_error_status_code
+
+
+def handle_devora(method: str, path: str, query: str, body: bytes, headers) -> tuple[int, dict]:
+    # path: still percent-encoded and relative to your Devora mount, e.g. "/user/search"
+    # query: the raw query string without "?"; body: the raw bytes (cap the read yourself)
+    # headers: a mapping, or (name, value) pairs so duplicate headers stay visible
+    result = process_request(sdk, sdk.get_routes(), AdapterRequest(method, path, query, body, headers))
+    status = 200 if result["success"] else get_error_status_code(result.get("errorCode"))
+    return status, result  # send as JSON with Cache-Control: private, no-store
+```
+
+`async_process_request` runs signature verification, the request claim and
+synchronous handlers in a worker thread, so it never blocks the event loop.
+`process_request` cannot run `async def` handlers.
+
+### Replay protection
+
+Every signed request carries a single-use id. After the signature verifies, the
+SDK claims that id from Devora with one signed call
+(`POST /api/sdk/request-claim`, `REQUEST_CLAIM_TIMEOUT_SECONDS = 3.0`); the
+handler runs only after a successful claim. Only requests whose signature
+verified are ever claimed, so unauthenticated traffic cannot use up request
+ids. The claim can fail with:
+
+| Status | `errorCode`                 | Cause                                                                    |
+| ------ | --------------------------- | ------------------------------------------------------------------------ |
+| 401    | `REPLAYED_REQUEST`          | Devora already claimed this request id (the request was already processed) |
+| 409    | `SESSION_NOT_STARTABLE`     | Start request for a session Devora is no longer starting                 |
+| 401    | `TIMESTAMP_EXPIRED`         | Devora says the request is too old to claim                              |
+| 503    | `REQUEST_CLAIM_UNAVAILABLE` | Devora could not be reached or gave no clear answer (fails closed)       |
+
+Devora's **Test connection** check is claimed too, so it also proves your
+backend can reach the Devora API. See
+[SIGNING.md](https://github.com/getdevora/devora-sdks/blob/main/SIGNING.md#request-claims).
+
+### Session termination
+
+Devora calls `DELETE /impersonate/:id/terminate` when a session ends. The
+session id is `req.params["id"]` (also `req.session_id`), and the body is
+`{"reason": ..., "terminatedBy": ...}`. `terminatedBy` is the external user id
+of the person who ended the session and is absent for automatic ends. `reason`
+is one of `user_ended`, `time_limit`, `admin_terminated`, `superseded`,
+`request_revoked`, `membership_revoked`, `role_downgraded`,
+`workos_session_revoked`, `principal_erased`, `organization_erased`,
+`start_failed` (Devora sent the start request, and your handler may have issued
+a token, but the session never started) or `not_started` (your handler issued a
+token but the impersonation link was never opened).
+
+Devora retries a failed terminate call (up to 5 attempts over 6 hours, with
+backoff), each as a new signed request with a new request id, so the handler
+must be idempotent; any 2xx counts as delivered. A 4xx other than 408, 425 or 429 is
+not retried; when overloaded, answer 429 or 503 with `Retry-After`. Store the
+Devora session id with the credential you mint and revoke by session, so a
+credential minted by a slow start handler after the terminate is still rejected. See
+[Session lifecycle & cleanup](https://docs.devora.sh/guide/session-lifecycle).
+
+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 start that fetch in a background thread as soon
+as `devora_sdk(...)` is constructed, so the cache is usually warm by the first
+request:
+
+```python
+sdk = devora_sdk(
+    api_key=os.environ["DEVORA_API_KEY"],
+    secret_key=os.environ["DEVORA_SECRET_KEY"],
+    org_id=os.environ["DEVORA_ORG_ID"],
+    prefetch_scope_config=True,
+)
+```
+
+Options, error codes and the guard are documented in the
+[Python reference](https://docs.devora.sh/reference/python).

devora_python-0.1.2/README.md

@@ -0,0 +1,178 @@
+# devora-python
+
+Recording, masking and capture policy are configured in the Devora dashboard and
+authorized server-side for each session. This backend SDK takes no capture
+settings, and `devora_sdk()` ignores keyword arguments it does not recognize,
+so check option names carefully. See
+[capture settings](https://github.com/getdevora/devora-sdks/blob/main/SETTINGS.md).
+
+Python backend core SDK for Devora customer integrations.
+
+## Requirements
+
+- Python `>=3.10,<4.0`
+- Outbound HTTPS access from your backend to the Devora API
+
+## Install
+
+```bash
+pip install devora-python
+```
+
+## Quick Start
+
+```python
+import os
+from dataclasses import asdict
+
+from devora_sdk import DEVORA_ENDPOINTS, devora_sdk
+
+sdk = devora_sdk(
+    api_key=os.environ["DEVORA_API_KEY"],  # pk_server_live_...
+    secret_key=os.environ["DEVORA_SECRET_KEY"],  # sk_server_live_...
+    org_id=os.environ["DEVORA_ORG_ID"],
+)
+
+
+@sdk.register(DEVORA_ENDPOINTS.USER_SEARCH)
+def search_users(req):
+    # Match name, email and the exact user ID with a parameterised query.
+    term = req.query.get("term", "")
+    limit = int(req.query.get("limit", 10))
+    users = search_customer_users(term, limit)
+    return {
+        "users": [
+            {
+                "id": u.id,
+                "name": u.name,
+                "email": u.email,
+                "attributes": {"company": u.company, "role": u.role, "plan": u.plan},
+            }
+            for u in users
+        ]
+    }
+
+
+@sdk.register(DEVORA_ENDPOINTS.IMPERSONATE)
+def impersonate(req):
+    ctx = req.devora_context
+    if not ctx:
+        raise ValueError("Missing impersonation context")
+    # Store the whole verified context in the token: the scope guard reads every
+    # field of it back. Expire the token no later than ctx.expires_at.
+    devora = {**asdict(ctx), "is_impersonation": True}
+    token = create_customer_token(ctx.target_user["id"], devora)
+    return {"token": token}
+
+
+@sdk.register(DEVORA_ENDPOINTS.TERMINATE)
+def terminate(req):
+    session_id = req.params["id"]
+    reason = (req.body or {}).get("reason")
+    # YOU IMPLEMENT: mark this Devora session revoked so every credential issued for it
+    # is rejected, including one issued after this call. Must be idempotent: Devora
+    # retries with a new request id (up to 5 attempts over 6 hours).
+    auth.revoke_impersonation_session(session_id=session_id, reason=reason)
+    return {"success": True}
+```
+
+User search should match name, email and the exact user ID. `attributes` are optional display fields such as company, role or plan: up to 12 per user, lowercase keys like `last_login`, and string, number, boolean or `null` values. Devora drops invalid entries silently; see [Search results and templates](https://docs.devora.sh/guide/search-results) for the limits and how your team lays out results.
+
+Each verified request is claimed once from Devora before your handler runs, so
+replay protection needs no storage on your side; your backend only needs
+outbound HTTPS access to the Devora API. See [Replay protection](#replay-protection).
+
+Register every handler, then mount the SDK with the
+[Django](https://pypi.org/project/devora-django/) or
+[FastAPI](https://pypi.org/project/devora-fastapi/) adapter. For any other
+framework, pass the request exactly as received to `process_request` (sync) or
+`await async_process_request` (async):
+
+```python
+from devora_sdk import AdapterRequest, process_request
+from devora_sdk.utils import get_error_status_code
+
+
+def handle_devora(method: str, path: str, query: str, body: bytes, headers) -> tuple[int, dict]:
+    # path: still percent-encoded and relative to your Devora mount, e.g. "/user/search"
+    # query: the raw query string without "?"; body: the raw bytes (cap the read yourself)
+    # headers: a mapping, or (name, value) pairs so duplicate headers stay visible
+    result = process_request(sdk, sdk.get_routes(), AdapterRequest(method, path, query, body, headers))
+    status = 200 if result["success"] else get_error_status_code(result.get("errorCode"))
+    return status, result  # send as JSON with Cache-Control: private, no-store
+```
+
+`async_process_request` runs signature verification, the request claim and
+synchronous handlers in a worker thread, so it never blocks the event loop.
+`process_request` cannot run `async def` handlers.
+
+### Replay protection
+
+Every signed request carries a single-use id. After the signature verifies, the
+SDK claims that id from Devora with one signed call
+(`POST /api/sdk/request-claim`, `REQUEST_CLAIM_TIMEOUT_SECONDS = 3.0`); the
+handler runs only after a successful claim. Only requests whose signature
+verified are ever claimed, so unauthenticated traffic cannot use up request
+ids. The claim can fail with:
+
+| Status | `errorCode`                 | Cause                                                                    |
+| ------ | --------------------------- | ------------------------------------------------------------------------ |
+| 401    | `REPLAYED_REQUEST`          | Devora already claimed this request id (the request was already processed) |
+| 409    | `SESSION_NOT_STARTABLE`     | Start request for a session Devora is no longer starting                 |
+| 401    | `TIMESTAMP_EXPIRED`         | Devora says the request is too old to claim                              |
+| 503    | `REQUEST_CLAIM_UNAVAILABLE` | Devora could not be reached or gave no clear answer (fails closed)       |
+
+Devora's **Test connection** check is claimed too, so it also proves your
+backend can reach the Devora API. See
+[SIGNING.md](https://github.com/getdevora/devora-sdks/blob/main/SIGNING.md#request-claims).
+
+### Session termination
+
+Devora calls `DELETE /impersonate/:id/terminate` when a session ends. The
+session id is `req.params["id"]` (also `req.session_id`), and the body is
+`{"reason": ..., "terminatedBy": ...}`. `terminatedBy` is the external user id
+of the person who ended the session and is absent for automatic ends. `reason`
+is one of `user_ended`, `time_limit`, `admin_terminated`, `superseded`,
+`request_revoked`, `membership_revoked`, `role_downgraded`,
+`workos_session_revoked`, `principal_erased`, `organization_erased`,
+`start_failed` (Devora sent the start request, and your handler may have issued
+a token, but the session never started) or `not_started` (your handler issued a
+token but the impersonation link was never opened).
+
+Devora retries a failed terminate call (up to 5 attempts over 6 hours, with
+backoff), each as a new signed request with a new request id, so the handler
+must be idempotent; any 2xx counts as delivered. A 4xx other than 408, 425 or 429 is
+not retried; when overloaded, answer 429 or 503 with `Retry-After`. Store the
+Devora session id with the credential you mint and revoke by session, so a
+credential minted by a slow start handler after the terminate is still rejected. See
+[Session lifecycle & cleanup](https://docs.devora.sh/guide/session-lifecycle).
+
+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 start that fetch in a background thread as soon
+as `devora_sdk(...)` is constructed, so the cache is usually warm by the first
+request:
+
+```python
+sdk = devora_sdk(
+    api_key=os.environ["DEVORA_API_KEY"],
+    secret_key=os.environ["DEVORA_SECRET_KEY"],
+    org_id=os.environ["DEVORA_ORG_ID"],
+    prefetch_scope_config=True,
+)
+```
+
+Options, error codes and the guard are documented in the
+[Python reference](https://docs.devora.sh/reference/python).

{devora_python-0.1.0 → devora_python-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devora-python"
-version = "0.1.0"
+version = "0.1.2"
 description = "Devora Python backend SDK for secure impersonation"
 readme = "README.md"
 requires-python = ">=3.10,<4.0"

{devora_python-0.1.0 → devora_python-0.1.2}/src/devora_sdk/__init__.py

@@ -34,13 +34,15 @@ from .models import (
 	DevoraImpersonationContext,
 	DevoraRequest,
 	DevoraResponse,
+	DevoraUser,
+	DevoraUserAttributeValue,
 	SDKRoute,
 	SDKStats,
+	UserSearchResponse,
 	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
 
@@ -54,13 +56,14 @@ __all__ = [
 	"DevoraImpersonationContext",
 	"DevoraRequest",
 	"DevoraResponse",
+	"DevoraUser",
+	"DevoraUserAttributeValue",
 	"GuardDecision",
 	"ImpersonationContext",
-	"InMemoryReplayStore",
 	"ProcessRequestOptions",
-	"ReplayStore",
 	"SDKRoute",
 	"SDKStats",
+	"UserSearchResponse",
 	"ScopeConfig",
 	"ScopeEndpoint",
 	"ScopeConfigFetcher",

{devora_python-0.1.0 → devora_python-0.1.2}/src/devora_sdk/constants.py

@@ -5,7 +5,6 @@ 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"
@@ -14,7 +13,6 @@ class DEVORA_ENDPOINTS:
 
 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",
@@ -34,7 +32,7 @@ class SECURITY_HEADERS:
 	SESSION_ID = "x-devora-session-id"
 
 
-SDK_VERSION = "0.1.0"
+SDK_VERSION = "0.1.2"
 DEFAULT_API_URL = DEVORA_API_ORIGIN
 DEFAULT_TIMESTAMP_TOLERANCE_SECONDS = 300
 DEFAULT_MAX_BODY_SIZE_BYTES = 1024 * 1024
@@ -45,5 +43,12 @@ WRITE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
 BROWSER_SESSION_BRIDGE_PATH = "/api/devora/browser-session"
 BROWSER_RESUME_CODE_ENDPOINT = "/api/sdk/browser-resume-code"
 BROWSER_RESUME_ENDPOINT = "/api/sdk/browser-resume"
+
+# Single use of signed Devora -> customer requests (see @devorash/core REQUEST_CLAIM):
+# after verifying a signature the SDK claims the request id from Devora, and the
+# handler runs only for the first claim. Customers need no storage of their own.
+REQUEST_CLAIM_ENDPOINT = "/api/sdk/request-claim"
+# Total deadline in seconds, leaving room for the handler within Devora's own deadline.
+REQUEST_CLAIM_TIMEOUT_SECONDS = 3.0
 # \Z, not $: $ also matches before a trailing newline.
 TAB_REF_PATTERN = r"^[A-Za-z0-9_-]{4,96}\Z"

{devora_python-0.1.0 → devora_python-0.1.2}/src/devora_sdk/handler.py

@@ -84,10 +84,10 @@ async def async_process_request(
 	import asyncio
 
 	loop = asyncio.get_running_loop()
-	# _prepare_request verifies the HMAC signature and consumes the replay
-	# nonce; in production the replay store is disk- or network-backed, so
-	# this can block. Run it off the event loop rather than stalling every
-	# other request this async server is handling. Using the stdlib executor
+	# _prepare_request verifies the HMAC signature and claims the request id
+	# from Devora over the network, so this can block. Run it off the event
+	# loop rather than stalling every other request this async server is
+	# handling. Using the stdlib executor
 	# (rather than anyio/Starlette's threadpool) keeps this module usable from
 	# any asyncio-based framework, not just FastAPI.
 	prepared = await loop.run_in_executor(None, _prepare_request, sdk, routes, request, options)

{devora_python-0.1.0 → devora_python-0.1.2}/src/devora_sdk/models.py

@@ -1,7 +1,30 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Callable, Mapping, MutableMapping, Optional
+from typing import Any, Callable, Mapping, MutableMapping, Optional, TypedDict, Union
+
+# An extra value shown in Devora's search results; None means "not set".
+DevoraUserAttributeValue = Optional[Union[str, int, float, bool]]
+
+
+class DevoraUser(TypedDict, total=False):
+	"""A user returned from your USER_SEARCH handler (``id`` is required).
+
+	``attributes`` holds extra display fields such as company, role or plan: keys
+	are lowercase letters, digits and underscores starting with a letter (e.g.
+	``last_login``); at most 12; strings up to 120 characters. Never include
+	secrets: keys that look like passwords, tokens, keys or card data are dropped.
+	"""
+
+	id: str
+	name: str
+	email: str
+	avatar: str
+	attributes: dict[str, DevoraUserAttributeValue]
+
+
+class UserSearchResponse(TypedDict):
+	users: list[DevoraUser]
 
 
 @dataclass(frozen=True)

{devora_python-0.1.0 → devora_python-0.1.2}/src/devora_sdk/sdk.py

@@ -1,10 +1,7 @@
 from __future__ import annotations
 
 import json
-import inspect
-import os
 import re
-import time
 from typing import Any, Callable, Optional
 
 from .constants import (
@@ -15,6 +12,8 @@ from .constants import (
 	PROTECTED_ENDPOINTS,
 	SDK_VERSION,
 	BROWSER_RESUME_CODE_ENDPOINT,
+	REQUEST_CLAIM_ENDPOINT,
+	REQUEST_CLAIM_TIMEOUT_SECONDS,
 	TAB_REF_PATTERN,
 )
 from .hmac import sha256_hex, sign_request, signature_matches
@@ -25,23 +24,18 @@ from .signing import (
 	CUSTOMER_TO_DEVORA,
 	DEVORA_TO_CUSTOMER,
 	build_canonical_string,
+	get_single_header,
 	has_identity_content_encoding,
 	is_valid_signed_path,
 	is_valid_signed_query,
 	matches,
 	parse_signature_headers,
-	replay_expires_at_ms,
-	replay_namespace,
+	parse_verified_json_body,
 )
 from .transport import ControlPlaneError, control_plane_request
-from .replay import InMemoryReplayStore, ReplayStore
 
-
-def resolve_environment(explicit: Optional[str] = None) -> str:
-	"""Explicit option first, then DEVORA_ENV / NODE_ENV as hints, else production."""
-	raw = (explicit or os.environ.get("DEVORA_ENV") or os.environ.get("NODE_ENV") or "production")
-	raw = str(raw).strip().lower()
-	return raw if raw in ("development", "test") else "production"
+# A start request: ``POST .../impersonate/:id`` (path is relative to the SDK mount).
+_START_REQUEST_PATH = re.compile(r"/impersonate/[^/]+\Z")
 
 
 class DevoraBackendSDK:
@@ -54,8 +48,6 @@ class DevoraBackendSDK:
 		collect_stats: bool = False,
 		debug: bool = False,
 		api_url: Optional[str] = None,
-		replay_store: Optional[ReplayStore] = None,
-		environment: Optional[str] = None,
 		prefetch_scope_config: bool = False,
 		**_ignored_options: Any,
 	) -> None:
@@ -77,17 +69,6 @@ class DevoraBackendSDK:
 		self.debug = debug
 		self.stats = SDKStats()
 		self._routes: list[SDKRoute] = []
-		# Fail closed: anything that is not explicitly a development/test runtime
-		# is production, and production must share replay protection across
-		# processes. Explicit option first, then DEVORA_ENV / NODE_ENV as hints.
-		self.environment = resolve_environment(environment)
-		if self.environment == "production" and replay_store is None:
-			raise ValueError(
-				"Devora SDK: replay_store is required in production. Pass a persistent "
-				"ReplayStore, or environment='development' (InMemoryReplayStore) for local "
-				"development only."
-			)
-		self._replay_store = replay_store or InMemoryReplayStore()
 		self._scope_config = ScopeConfigFetcher(
 			api_key=api_key,
 			api_url=self.api_url,
@@ -156,7 +137,8 @@ class DevoraBackendSDK:
 		``path`` is relative to the SDK mount and still percent-encoded; ``query``
 		is everything after the first ``?``; ``body`` is the raw bytes; ``headers``
 		is a mapping or a list of ``(name, value)`` pairs (duplicates are
-		rejected). Steps before the replay store never touch it.
+		rejected). A verified request is then claimed once from Devora; only a
+		request whose signature verified is ever claimed.
 		"""
 		tolerance = self.timestamp_tolerance if timestamp_tolerance is None else timestamp_tolerance
 		if not is_valid_timestamp_tolerance(tolerance):
@@ -198,24 +180,20 @@ class DevoraBackendSDK:
 		if not signature_matches(self._secret_key, canonical, parsed["signature"]):
 			return ValidationResult(valid=False, error="Invalid HMAC signature", error_code="INVALID_SIGNATURE")
 
-		try:
-			fresh = self._replay_store.consume(
-				replay_namespace(DEVORA_TO_CUSTOMER, parsed["key_id"]),
-				parsed["request_id"],
-				replay_expires_at_ms(sent_at, int(time.time()), tolerance),
-			)
-		except Exception:
-			return ValidationResult(
-				valid=False, error="Replay protection is unavailable", error_code="REPLAY_STORE_UNAVAILABLE"
+		# A start request names the session it starts; Devora lets it be claimed
+		# only while that session is still starting. (A start request without a
+		# valid session ID is claimed plainly; the handler then refuses it.)
+		session_id: Optional[str] = None
+		if method == "POST" and _START_REQUEST_PATH.search(path):
+			body_ok, parsed_body = parse_verified_json_body(
+				bytes(body), get_single_header(headers, "content-type") or None
 			)
-		if not isinstance(fresh, bool):
-			if inspect.iscoroutine(fresh):
-				fresh.close()
-			return ValidationResult(
-				valid=False, error="Replay store must return a boolean decision", error_code="REPLAY_STORE_UNAVAILABLE"
-			)
-		if not fresh:
-			return ValidationResult(valid=False, error="Request was already processed", error_code="REPLAYED_REQUEST")
+			value = parsed_body.get("sessionId") if body_ok and isinstance(parsed_body, dict) else None
+			if isinstance(value, str) and value and len(value) <= 128:
+				session_id = value
+		rejection = self._claim_request(parsed["request_id"], parsed["sent_at"], session_id)
+		if rejection is not None:
+			return rejection
 		return ValidationResult(
 			valid=True,
 			org_id=parsed["org_id"],
@@ -233,7 +211,41 @@ class DevoraBackendSDK:
 	def refresh_scope_config(self) -> Optional[ScopeConfig]:
 		return self._scope_config.refresh()
 
-	def _signed_devora_post(self, path: str, payload: dict[str, Any]) -> tuple[int, Optional[dict[str, Any]]]:
+	def _claim_request(
+		self, request_id: str, sent_at: str, session_id: Optional[str]
+	) -> Optional[ValidationResult]:
+		"""Claim a verified request id from Devora: ``None`` for the first claim,
+		otherwise the rejection. Anything but a clear answer fails closed."""
+		payload: dict[str, Any] = {"requestId": request_id, "sentAt": sent_at}
+		if session_id is not None:
+			payload["sessionId"] = session_id
+		try:
+			status, reply = self._signed_devora_post(
+				REQUEST_CLAIM_ENDPOINT, payload, timeout=REQUEST_CLAIM_TIMEOUT_SECONDS
+			)
+		except (ControlPlaneError, ValueError):
+			status, reply = 0, None
+		data = reply.get("data") if reply else None
+		if 200 <= status < 300 and reply and reply.get("success") is True and isinstance(data, dict) and data.get("claimed") is True:
+			return None
+		code = reply.get("errorCode") if reply and status == 409 else None
+		if code == "REPLAYED_REQUEST":
+			return ValidationResult(valid=False, error="Request was already processed", error_code="REPLAYED_REQUEST")
+		if code == "SESSION_NOT_STARTABLE":
+			return ValidationResult(
+				valid=False, error="Devora is no longer starting this session", error_code="SESSION_NOT_STARTABLE"
+			)
+		if code == "TIMESTAMP_EXPIRED":
+			return ValidationResult(valid=False, error="Request is too old", error_code="TIMESTAMP_EXPIRED")
+		return ValidationResult(
+			valid=False,
+			error="Devora could not confirm this request is new",
+			error_code="REQUEST_CLAIM_UNAVAILABLE",
+		)
+
+	def _signed_devora_post(
+		self, path: str, payload: dict[str, Any], timeout: float = 5.0
+	) -> tuple[int, Optional[dict[str, Any]]]:
 		"""POST a signed JSON body to a Devora SDK endpoint (customer-to-devora)."""
 		body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
 		headers = sign_request(
@@ -245,7 +257,7 @@ class DevoraBackendSDK:
 			path=path,
 			body=body,
 		)
-		status, json_body, _ = control_plane_request(f"{self.api_url}{path}", "POST", headers, body)
+		status, json_body, _ = control_plane_request(f"{self.api_url}{path}", "POST", headers, body, timeout=timeout)
 		return status, json_body
 
 	def get_session_status(self, session_id: str) -> Optional[dict[str, Any]]:
@@ -341,8 +353,6 @@ def devora_sdk(
 	collect_stats: bool = False,
 	debug: bool = False,
 	api_url: Optional[str] = None,
-	replay_store: Optional[ReplayStore] = None,
-	environment: Optional[str] = None,
 	prefetch_scope_config: bool = False,
 	**_ignored_options: Any,
 ) -> DevoraBackendSDK:
@@ -354,8 +364,6 @@ def devora_sdk(
 		collect_stats=collect_stats,
 		debug=debug,
 		api_url=api_url,
-		replay_store=replay_store,
-		environment=environment,
 		prefetch_scope_config=prefetch_scope_config,
 	)
 

{devora_python-0.1.0 → devora_python-0.1.2}/src/devora_sdk/signing.py

@@ -170,15 +170,6 @@ def has_identity_content_encoding(headers: HeaderInput) -> bool:
 	return value is None or value == "identity"
 
 
-def replay_namespace(direction: str, key_id: str) -> str:
-	return f"v{VERSION}:{direction}:{key_id}"
-
-
-def replay_expires_at_ms(sent_at: int, now_seconds: int, tolerance_seconds: int) -> int:
-	"""Covers the floor second of the timestamp check plus one second of jitter."""
-	return (max(now_seconds, sent_at) + tolerance_seconds + 2) * 1000
-
-
 def parse_verified_query(query: str) -> dict[str, Union[str, list[str]]]:
 	"""Parse a verified raw query. Repeated keys become lists in wire order."""
 	result: dict[str, Union[str, list[str]]] = {}

{devora_python-0.1.0 → devora_python-0.1.2}/src/devora_sdk/utils.py

@@ -64,10 +64,12 @@ def get_error_status_code(error_code: Optional[str]) -> int:
 		"IMPERSONATION_SESSION_ENDED",
 	):
 		return 401
-	if error_code in ("IMPERSONATION_POLICY_UNAVAILABLE", "REPLAY_STORE_UNAVAILABLE"):
+	if error_code in ("IMPERSONATION_POLICY_UNAVAILABLE", "REQUEST_CLAIM_UNAVAILABLE"):
 		return 503
 	if error_code == "REPLAYED_REQUEST":
 		return 401
+	if error_code == "SESSION_NOT_STARTABLE":
+		return 409
 	if error_code == "UNSUPPORTED_CONTENT_ENCODING":
 		return 415
 	if error_code in ("IMPERSONATION_ENDPOINT_BLOCKED", "IMPERSONATION_SCOPE_VIOLATION"):

devora_python-0.1.0/PKG-INFO

@@ -1,132 +0,0 @@
-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

@@ -1,109 +0,0 @@
-# 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/src/devora_sdk/replay.py

@@ -1,41 +0,0 @@
-from __future__ import annotations
-
-import math
-import time
-from threading import Lock
-from typing import Protocol
-
-
-class ReplayStore(Protocol):
-	"""Atomic replay protection shared by every application instance.
-
-	``consume`` must be an atomic insert-if-absent (for example Redis
-	``SET key 1 NX PXAT expires_at``, or a unique-key database insert) and must
-	never evict an entry before ``expires_at``. A store that cannot guarantee
-	this must raise; the SDK then fails closed with a 503.
-	"""
-
-	def consume(self, namespace: str, request_id: str, expires_at: int) -> bool:
-		"""Return True only for the first consumption of ``request_id`` within
-		``namespace`` before ``expires_at`` (Unix milliseconds)."""
-		...
-
-
-class InMemoryReplayStore:
-	"""Development-only replay store. Production must use persistent storage."""
-
-	def __init__(self) -> None:
-		self._entries: dict[str, int] = {}
-		self._lock = Lock()
-
-	def consume(self, namespace: str, request_id: str, expires_at: int) -> bool:
-		if isinstance(expires_at, bool) or not isinstance(expires_at, (int, float)) or not math.isfinite(expires_at):
-			raise ValueError("Invalid replay expiry")
-		now = int(time.time() * 1000)
-		key = f"{namespace}\n{request_id}"
-		with self._lock:
-			self._entries = {entry: expiry for entry, expiry in self._entries.items() if expiry > now}
-			if key in self._entries:
-				return False
-			self._entries[key] = int(expires_at)
-			return True