devora-python 0.1.0__py3-none-any.whl

devora_sdk/handler.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import inspect
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping, Optional, Union
+
+from .constants import DEFAULT_MAX_BODY_SIZE_BYTES, DEVORA_ENDPOINTS
+from .models import DevoraImpersonationContext, DevoraRequest, SDKRoute
+from .security import validate_timestamp_tolerance
+from .signing import get_single_header, parse_verified_json_body, parse_verified_query
+from .utils import (
+	create_error_response,
+	create_success_response,
+	match_path,
+)
+
+logger = logging.getLogger("devora_sdk")
+
+
+@dataclass(frozen=True)
+class AdapterRequest:
+	"""A request exactly as received. The signature covers these bytes.
+
+	``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 (so duplicates are visible).
+	"""
+
+	method: str
+	path: str
+	query: str
+	body: bytes
+	headers: Any
+
+
+@dataclass(frozen=True)
+class ProcessRequestOptions:
+	timestamp_tolerance: Optional[int] = None
+	max_body_size: int = DEFAULT_MAX_BODY_SIZE_BYTES
+
+	def __post_init__(self) -> None:
+		validate_timestamp_tolerance(self.timestamp_tolerance)
+
+
+@dataclass(frozen=True)
+class _PreparedRequest:
+	route: SDKRoute
+	devora_request: DevoraRequest
+	record: Callable[[str, Optional[str]], None]
+
+
+def process_request(
+	sdk: Any,
+	routes: list[SDKRoute],
+	request: AdapterRequest,
+	options: Optional[ProcessRequestOptions] = None,
+) -> dict[str, Any]:
+	prepared = _prepare_request(sdk, routes, request, options)
+	if isinstance(prepared, dict):
+		return prepared
+
+	try:
+		result = prepared.route.handler(prepared.devora_request)
+		if inspect.isawaitable(result):
+			close = getattr(result, "close", None)
+			if callable(close):
+				close()
+			raise TypeError("Async Devora handlers require async_process_request")
+		prepared.record("success", prepared.route.path)
+		return create_success_response(result)
+	except Exception:
+		logger.exception("Devora SDK: customer handler raised")
+		prepared.record("failure", prepared.route.path)
+		return create_error_response("Customer handler failed", "HANDLER_ERROR")
+
+
+async def async_process_request(
+	sdk: Any,
+	routes: list[SDKRoute],
+	request: AdapterRequest,
+	options: Optional[ProcessRequestOptions] = None,
+) -> dict[str, Any]:
+	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
+	# (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)
+	if isinstance(prepared, dict):
+		return prepared
+
+	try:
+		if inspect.iscoroutinefunction(prepared.route.handler):
+			result = await prepared.route.handler(prepared.devora_request)
+		else:
+			# A synchronous customer handler may itself block (a DB call, an
+			# HTTP request, ...) — never call it directly on the event loop.
+			# This also lets a sync Django ORM call run safely from Django's
+			# async view path, which otherwise raises SynchronousOnlyOperation.
+			result = await loop.run_in_executor(None, prepared.route.handler, prepared.devora_request)
+			if inspect.isawaitable(result):
+				result = await result
+		prepared.record("success", prepared.route.path)
+		return create_success_response(result)
+	except Exception:
+		logger.exception("Devora SDK: customer handler raised")
+		prepared.record("failure", prepared.route.path)
+		return create_error_response("Customer handler failed", "HANDLER_ERROR")
+
+
+def create_generic_handler(
+	sdk: Any,
+	routes: list[SDKRoute],
+	options: Optional[ProcessRequestOptions] = None,
+) -> Callable[[AdapterRequest], dict[str, Any]]:
+	def handler(request: AdapterRequest) -> dict[str, Any]:
+		return process_request(sdk, routes, request, options)
+
+	return handler
+
+
+def _prepare_request(
+	sdk: Any,
+	routes: list[SDKRoute],
+	request: AdapterRequest,
+	options: Optional[ProcessRequestOptions] = None,
+) -> Union[dict[str, Any], _PreparedRequest]:
+	options = options or ProcessRequestOptions()
+	method = request.method
+	path = request.path
+
+	def record(outcome: str, endpoint: Optional[str] = None) -> None:
+		if hasattr(sdk, "record_request"):
+			sdk.record_request(endpoint or "UNMATCHED", outcome)
+
+	if not isinstance(request.body, (bytes, bytearray)):
+		record("failure")
+		return create_error_response("Adapter must supply the raw request body bytes", "INVALID_BODY")
+	body = bytes(request.body)
+	if len(body) > options.max_body_size:
+		record("failure")
+		return create_error_response("Request body too large", "BODY_TOO_LARGE")
+	if method in ("GET", "HEAD") and body:
+		record("failure")
+		return create_error_response("GET and HEAD requests must not have a body", "INVALID_BODY")
+
+	# Signature v3 over the exact wire bytes, before any route lookup, so
+	# unauthenticated callers learn nothing about registered routes.
+	validation = sdk.verify_request(method, path, request.query, body, request.headers, options.timestamp_tolerance)
+	if not validation.valid:
+		record("security_error")
+		return create_error_response(
+			validation.error or "Security validation failed",
+			validation.error_code or "INVALID_SIGNATURE",
+		)
+
+	route = _find_matching_route(routes, method, path)
+	if not route:
+		record("failure")
+		return create_error_response("No handler found for this request", "NOT_FOUND")
+	_, params = match_path(route.path, path)
+
+	body_ok, parsed_body = parse_verified_json_body(body, get_single_header(request.headers, "content-type") or None)
+	if not body_ok:
+		record("failure", route.path)
+		return create_error_response(parsed_body, "INVALID_BODY")
+	try:
+		parsed_query = parse_verified_query(request.query)
+	except (UnicodeDecodeError, ValueError):
+		record("failure", route.path)
+		return create_error_response("Invalid query string", "INVALID_REQUEST_TARGET")
+
+	context_result = _build_devora_context(route, path, parsed_body, params)
+	if context_result.get("error"):
+		record("security_error", route.path)
+		return create_error_response(context_result["error"], "INVALID_IMPERSONATION_CONTEXT")
+
+	context = context_result.get("context")
+	session_id = context.session_id if context else _session_id_from_route(route, params, parsed_body)
+
+	devora_request = DevoraRequest(
+		method=method,
+		path=path,
+		params=params,
+		query=parsed_query,
+		body=parsed_body,
+		headers=request.headers,
+		org_id=validation.org_id or "",
+		key_id=validation.key_id or "",
+		session_id=session_id,
+		devora_context=context,
+	)
+
+	return _PreparedRequest(route=route, devora_request=devora_request, record=record)
+
+
+def _find_matching_route(routes: list[SDKRoute], method: str, path: str) -> Optional[SDKRoute]:
+	for route in routes:
+		matched, _ = match_path(route.path, path)
+		if route.method.upper() == method and matched:
+			return route
+	return None
+
+
+def _build_devora_context(
+	route: SDKRoute, path: str, body: Any, params: Mapping[str, str]
+) -> dict[str, Any]:
+	if route.path != DEVORA_ENDPOINTS.IMPERSONATE:
+		return {}
+	if not isinstance(body, dict):
+		return {"error": "Impersonation request body must be an object"}
+	session_id = _read_string(body.get("sessionId"))
+	scope = body.get("scope")
+	expires_at = _read_number(body.get("expiresAt"))
+	if not session_id or len(session_id) > 128:
+		return {"error": "Impersonation request is missing a valid session ID"}
+	if scope not in ("read", "write"):
+		return {"error": "Impersonation request is missing a valid scope"}
+	from .utils import now_ms
+
+	if not expires_at or expires_at <= now_ms():
+		return {"error": "Impersonation request is expired or missing expiration"}
+	target_user = _read_user(body.get("targetUser"), params.get("id"))
+	if not target_user:
+		_, matched_params = match_path(route.path, path)
+		target_user = _read_user(body.get("targetUser"), matched_params.get("id"))
+	if not target_user:
+		return {"error": "Impersonation request is missing target user context"}
+	impersonator = _read_user(body.get("impersonator"))
+	if not impersonator:
+		return {"error": "Impersonation request is missing impersonator context"}
+	auth_method = body.get("authMethod")
+	if auth_method != "devora_impersonation":
+		return {"error": "Impersonation request has an invalid authentication method"}
+	authorization_source = body.get("authorizationSource")
+	if authorization_source not in (
+		"standard",
+		"self_approved",
+		"self_approved_read",
+		"break_glass",
+	):
+		return {"error": "Impersonation request has an invalid authorization source"}
+	recording_allowed = body.get("recordingAllowed")
+	if not isinstance(recording_allowed, bool):
+		return {"error": "Impersonation request is missing recording authorization"}
+	return {
+		"context": DevoraImpersonationContext(
+			session_id=session_id,
+			scope=str(scope),
+			expires_at=int(expires_at),
+			impersonator=impersonator,
+			target_user=target_user,
+			auth_method=auth_method,
+			authorization_source=authorization_source,
+			recording_allowed=recording_allowed,
+		)
+	}
+
+
+def _session_id_from_route(route: SDKRoute, params: Mapping[str, str], body: Any) -> Optional[str]:
+	if route.path == DEVORA_ENDPOINTS.TERMINATE and params.get("id"):
+		return params["id"]
+	if isinstance(body, dict):
+		return _read_string(body.get("sessionId"))
+	return None
+
+
+def _read_string(value: Any) -> Optional[str]:
+	return value if isinstance(value, str) and value.strip() else None
+
+
+def _read_number(value: Any) -> Optional[int]:
+	if isinstance(value, (int, float)):
+		return int(value)
+	if isinstance(value, str) and value.strip():
+		try:
+			return int(float(value))
+		except ValueError:
+			return None
+	return None
+
+
+def _read_user(value: Any, fallback_id: Optional[str] = None) -> Optional[dict[str, Any]]:
+	source = value if isinstance(value, dict) else {}
+	user_id = _read_string(source.get("id")) or fallback_id
+	if not user_id:
+		return None
+	result = {"id": user_id}
+	if _read_string(source.get("email")):
+		result["email"] = source["email"]
+	if _read_string(source.get("name")):
+		result["name"] = source["name"]
+	return result

devora_sdk/hmac.py

@@ -0,0 +1,67 @@
+"""Request signing v3 primitives (hashlib/hmac)."""
+from __future__ import annotations
+
+import hashlib
+import hmac as _hmac
+import time
+import uuid
+from typing import Optional
+
+from .constants import SECURITY_HEADERS
+from .signing import VERSION, build_canonical_string, matches
+
+
+def sha256_hex(body: bytes) -> str:
+	return hashlib.sha256(body).hexdigest()
+
+
+def hmac_hex(secret_key: str, canonical: str) -> str:
+	"""Lowercase hex HMAC-SHA256 keyed by the secret's ASCII bytes."""
+	return _hmac.new(secret_key.encode("ascii"), canonical.encode("ascii"), hashlib.sha256).hexdigest()
+
+
+def signature_matches(secret_key: str, canonical: str, provided: object) -> bool:
+	"""Constant-time byte comparison. Never raises; lenient hex is rejected."""
+	if not matches("signature", provided):
+		return False
+	return _hmac.compare_digest(bytes.fromhex(hmac_hex(secret_key, canonical)), bytes.fromhex(provided))  # type: ignore[arg-type]
+
+
+def sign_request(
+	*,
+	secret_key: str,
+	direction: str,
+	key_id: str,
+	org_id: str,
+	method: str,
+	path: str,
+	query: str = "",
+	body: bytes = b"",
+	sent_at: Optional[int] = None,
+	request_id: Optional[str] = None,
+) -> dict[str, str]:
+	"""Headers for an outgoing signed request (the body is sent as given)."""
+	sent = str(int(time.time()) if sent_at is None else sent_at)
+	rid = request_id or str(uuid.uuid4())
+	canonical = build_canonical_string(
+		direction=direction,
+		key_id=key_id,
+		org_id=org_id,
+		sent_at=sent,
+		request_id=rid,
+		method=method,
+		path=path,
+		query=query,
+		body_sha256=sha256_hex(body),
+	)
+	headers = {
+		SECURITY_HEADERS.SIGNATURE_VERSION: VERSION,
+		SECURITY_HEADERS.KEY_ID: key_id,
+		SECURITY_HEADERS.ORG_ID: org_id,
+		SECURITY_HEADERS.SENT_AT: sent,
+		SECURITY_HEADERS.REQUEST_ID: rid,
+		SECURITY_HEADERS.SIGNATURE: hmac_hex(secret_key, canonical),
+	}
+	if body:
+		headers["Content-Type"] = "application/json"
+	return headers

devora_sdk/models.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, MutableMapping, Optional
+
+
+@dataclass(frozen=True)
+class DevoraImpersonationContext:
+	session_id: str
+	scope: str
+	expires_at: int
+	impersonator: dict[str, Any]
+	target_user: dict[str, Any]
+	auth_method: str
+	authorization_source: str
+	recording_allowed: bool
+
+	@property
+	def actor(self) -> dict[str, Any]:
+		return self.impersonator
+
+	@property
+	def subject(self) -> dict[str, Any]:
+		return self.target_user
+
+
+@dataclass(frozen=True)
+class DevoraRequest:
+	method: str
+	path: str
+	params: Mapping[str, str]
+	query: Mapping[str, Any]
+	body: Any
+	headers: Mapping[str, Any]
+	org_id: str
+	key_id: str
+	session_id: Optional[str] = None
+	devora_context: Optional[DevoraImpersonationContext] = None
+
+
+DevoraResponse = dict[str, Any]
+RouteHandler = Callable[[DevoraRequest], Any]
+
+
+@dataclass(frozen=True)
+class SDKRoute:
+	path: str
+	method: str
+	handler: RouteHandler
+	is_built_in: bool = False
+
+
+@dataclass
+class SDKStats:
+	total_requests: int = 0
+	successful_requests: int = 0
+	failed_requests: int = 0
+	security_errors: int = 0
+	requests_by_endpoint: MutableMapping[str, int] = field(default_factory=dict)
+
+	def to_dict(self) -> dict[str, Any]:
+		return {
+			"totalRequests": self.total_requests,
+			"successfulRequests": self.successful_requests,
+			"failedRequests": self.failed_requests,
+			"securityErrors": self.security_errors,
+			"requestsByEndpoint": dict(self.requests_by_endpoint),
+		}
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+	valid: bool
+	error: Optional[str] = None
+	error_code: Optional[str] = None
+	org_id: Optional[str] = None
+	key_id: Optional[str] = None
+	timestamp: Optional[int] = None
+	request_id: Optional[str] = None

devora_sdk/policy.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import re
+import math
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from .constants import DEFAULT_API_URL
+from .transport import ControlPlaneError, control_plane_request
+
+# How long a cached policy may be served past its window during an outage.
+STALE_GRACE_MS = 5 * 60 * 1000
+# Largest accepted policy, and the longest server-sent cache horizon trusted.
+MAX_POLICY_ENTRIES = 1000
+MAX_PATTERN_LENGTH = 500
+MAX_POLICY_TTL_MS = 60 * 60 * 1000
+_METHOD = re.compile(r"\*|[A-Z]{3,7}")
+
+
+def _read_endpoints(value: Any) -> Optional[list[dict[str, str]]]:
+	if not isinstance(value, list) or len(value) > MAX_POLICY_ENTRIES:
+		return None
+	endpoints = []
+	for entry in value:
+		method = entry.get("method") if isinstance(entry, dict) else None
+		pattern = entry.get("pattern") if isinstance(entry, dict) else None
+		if (
+			not isinstance(method, str)
+			or not _METHOD.fullmatch(method)
+			or not isinstance(pattern, str)
+			or not pattern
+			or len(pattern) > MAX_PATTERN_LENGTH
+		):
+			return None
+		endpoints.append({"method": method, "pattern": pattern})
+	return endpoints
+
+
+def _read_policy(data: Any, now: int) -> Optional["ScopeConfig"]:
+	"""Validate a policy response; ``None`` when any part is malformed (fail closed)."""
+	if not isinstance(data, dict):
+		return None
+	safe = _read_endpoints(data.get("safeReadEndpoints"))
+	blocked = _read_endpoints(data.get("blockedEndpoints"))
+	version = _safe_integer(data.get("version"), 0)
+	requested = _safe_integer(data.get("cachedUntil"), 1)
+	# Mirror JavaScript safe integers, including rejection of booleans. A
+	# missing deny list/version/cache horizon cannot mean an empty valid policy.
+	if safe is None or blocked is None or version is None or requested is None:
+		return None
+	return ScopeConfig(
+		safe_read_endpoints=safe,
+		blocked_endpoints=blocked,
+		version=version,
+		cached_until=int(min(max(requested, now), now + MAX_POLICY_TTL_MS)),
+	)
+
+
+def _safe_integer(value: Any, minimum: int) -> Optional[int]:
+	if isinstance(value, bool):
+		return None
+	if isinstance(value, float):
+		if not math.isfinite(value) or not value.is_integer():
+			return None
+		value = int(value)
+	return value if isinstance(value, int) and minimum <= value <= 2**53 - 1 else None
+
+
+@dataclass(frozen=True)
+class ScopeConfig:
+	safe_read_endpoints: list[dict[str, str]]
+	blocked_endpoints: list[dict[str, str]]
+	version: int
+	cached_until: int
+
+	def to_dict(self) -> dict[str, Any]:
+		return {
+			"safeReadEndpoints": self.safe_read_endpoints,
+			"blockedEndpoints": self.blocked_endpoints,
+			"version": self.version,
+			"cachedUntil": self.cached_until,
+		}
+
+
+class ScopeConfigFetcher:
+	def __init__(
+		self,
+		api_key: str,
+		cache_ttl_ms: int = 5 * 60 * 1000,
+		api_url: Optional[str] = None,
+		prefetch: bool = False,
+		sign_request: Optional[Callable[[], dict[str, str]]] = None,
+	) -> None:
+		"""``sign_request`` returns fresh v3 signature headers for
+		``GET /api/sdk/scope-config`` (the policy is not public);
+		``DevoraBackendSDK`` supplies it from the server secret."""
+		if isinstance(cache_ttl_ms, bool) or not isinstance(cache_ttl_ms, int) or not 0 < cache_ttl_ms <= MAX_POLICY_TTL_MS:
+			raise ValueError("cache_ttl_ms must be an integer between 1 and 3600000")
+		self.api_key = api_key
+		self._sign_request = sign_request
+		self.api_url = api_url or DEFAULT_API_URL
+		self.cache_ttl_ms = cache_ttl_ms
+		self.cached_config: Optional[ScopeConfig] = None
+		self.etag: Optional[str] = None
+		self.stale_until = 0
+		self._timer: Optional[threading.Timer] = None
+		self._lock = threading.Lock()
+		if prefetch:
+			# Warm the cache in the background at construction time instead of
+			# leaving the first request(s) to pay for it. Without this, every
+			# worker process that just started serves its first request (and any
+			# request racing it) a synchronous fetch or a 503
+			# IMPERSONATION_POLICY_UNAVAILABLE, since get_config() only fetches
+			# lazily and a concurrent caller during that first fetch gets None
+			# rather than waiting (see refresh()'s single-flight comment).
+			# Fire-and-forget: refresh() already handles its own errors.
+			threading.Thread(target=self.refresh, daemon=True).start()
+
+	def get_config(self) -> Optional[ScopeConfig]:
+		if self.cached_config and _now_ms() < self.cached_config.cached_until:
+			return self.cached_config
+		config = self.refresh()
+		if config and not self._timer:
+			self._schedule_refresh()
+		return config
+
+	def get_cached_config(self) -> Optional[ScopeConfig]:
+		return self.cached_config
+
+	def refresh(self) -> Optional[ScopeConfig]:
+		# Single-flight without blocking: a second caller during an in-progress
+		# refresh gets the cached/stale policy immediately instead of queueing a
+		# worker thread behind a 5-second network call.
+		if not self._lock.acquire(blocking=False):
+			return self._stale_or_none()
+		try:
+			return self._refresh_locked()
+		finally:
+			self._lock.release()
+
+	def _refresh_locked(self) -> Optional[ScopeConfig]:
+		if self._sign_request is None:
+			return self._stale_or_none()
+		headers = dict(self._sign_request())
+		if self.etag:
+			headers["If-None-Match"] = self.etag
+		try:
+			status, payload, response_headers = control_plane_request(
+				f"{self.api_url}/api/sdk/scope-config", "GET", headers
+			)
+		except ControlPlaneError:
+			return self._stale_or_none()
+		if status == 304 and self.cached_config:
+			return self._extend_cached_config()
+		config = (
+			_read_policy(payload.get("data"), _now_ms())
+			if 200 <= status < 300 and payload and payload.get("success") is True
+			else None
+		)
+		if config is None:
+			return self._stale_or_none()
+		self.etag = response_headers.get("etag")
+		self.cached_config = config
+		self.stale_until = config.cached_until + STALE_GRACE_MS
+		self._schedule_refresh()
+		return config
+
+	def stop(self) -> None:
+		if self._timer:
+			self._timer.cancel()
+			self._timer = None
+
+	def _stale_or_none(self) -> Optional[ScopeConfig]:
+		if self.cached_config and _now_ms() < self.stale_until:
+			return self.cached_config
+		return None
+
+	def _extend_cached_config(self) -> ScopeConfig:
+		self.cached_config = ScopeConfig(
+			safe_read_endpoints=self.cached_config.safe_read_endpoints,
+			blocked_endpoints=self.cached_config.blocked_endpoints,
+			version=self.cached_config.version,
+			cached_until=_now_ms() + self.cache_ttl_ms,
+		)
+		self.stale_until = self.cached_config.cached_until + STALE_GRACE_MS
+		self._schedule_refresh()
+		return self.cached_config
+
+	def _schedule_refresh(self) -> None:
+		self.stop()
+		refresh_in_ms = self.cache_ttl_ms
+		if self.cached_config:
+			refresh_in_ms = max(
+				self.cached_config.cached_until - _now_ms() - 30_000,
+				min(self.cache_ttl_ms // 2, 60_000),
+			)
+		self._timer = threading.Timer(refresh_in_ms / 1000, self._refresh_from_timer)
+		self._timer.daemon = True
+		self._timer.start()
+
+	def _refresh_from_timer(self) -> None:
+		self.refresh()
+
+
+def _now_ms() -> int:
+	return int(time.time() * 1000)

devora_sdk/py.typed

@@ -0,0 +1 @@
+

devora_sdk/replay.py

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