svc-infra 0.1.595__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/utils.py

@@ -1,15 +1,43 @@
+"""svc-infra utilities module.
+
+This module provides utility functions and helpers for svc-infra, including:
+- Template rendering and file writing utilities
+- Deprecation decorators and warnings
+"""
+
+from __future__ import annotations
+
+import functools
 import importlib.resources as pkg
+import warnings
+from collections.abc import Callable
 from pathlib import Path
 from string import Template as _T
-from typing import Any, Dict
+from typing import Any, TypeVar
+
+__all__ = [
+    # Template utilities
+    "render_template",
+    "write",
+    "ensure_init_py",
+    # Deprecation utilities
+    "deprecated",
+    "deprecated_parameter",
+    "DeprecatedWarning",
+]
+
 
+# =============================================================================
+# Template Utilities
+# =============================================================================
 
-def render_template(tmpl_dir: str, name: str, subs: dict[str, Any] = None) -> str:
+
+def render_template(tmpl_dir: str, name: str, subs: dict[str, Any] | None = None) -> str:
     txt = pkg.files(tmpl_dir).joinpath(name).read_text(encoding="utf-8")
-    return _T(txt).safe_substitute(subs)
+    return _T(txt).safe_substitute(subs or {})
 
 
-def write(dest: Path, content: str, overwrite: bool = False) -> Dict[str, Any]:
+def write(dest: Path, content: str, overwrite: bool = False) -> dict[str, Any]:
     dest = dest.resolve()
     dest.parent.mkdir(parents=True, exist_ok=True)
     if dest.exists() and not overwrite:
@@ -18,6 +46,143 @@ def write(dest: Path, content: str, overwrite: bool = False) -> Dict[str, Any]:
     return {"path": str(dest), "action": "wrote"}
 
 
-def ensure_init_py(dir_path: Path, overwrite: bool, paired: bool, content: str) -> Dict[str, Any]:
+def ensure_init_py(dir_path: Path, overwrite: bool, paired: bool, content: str) -> dict[str, Any]:
     """Create __init__.py; paired=True writes models/schemas re-exports, otherwise minimal."""
     return write(dir_path / "__init__.py", content, overwrite)
+
+
+# =============================================================================
+# Deprecation Utilities
+# =============================================================================
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class DeprecatedWarning(DeprecationWarning):
+    """Custom deprecation warning for svc-infra.
+
+    This warning is used to distinguish svc-infra deprecations from
+    Python's built-in DeprecationWarning.
+    """
+
+    pass
+
+
+def deprecated(
+    version: str,
+    reason: str,
+    removal_version: str | None = None,
+    *,
+    stacklevel: int = 2,
+) -> Callable[[F], F]:
+    """Decorator to mark a function or class as deprecated.
+
+    The decorated function/class will emit a DeprecationWarning when called/instantiated.
+
+    Args:
+        version: The version in which the feature was deprecated (e.g., "1.2.0").
+        reason: The reason for deprecation and recommended alternative.
+        removal_version: The version in which the feature will be removed (e.g., "1.4.0").
+        stacklevel: Stack level for the warning (default 2 for immediate caller).
+
+    Returns:
+        A decorator that wraps the function/class with deprecation warning.
+
+    Example:
+        >>> @deprecated(
+        ...     version="1.2.0",
+        ...     reason="Use new_function() instead",
+        ...     removal_version="1.4.0"
+        ... )
+        ... def old_function():
+        ...     return "result"
+        >>>
+        >>> old_function()  # Emits DeprecationWarning
+        'result'
+    """
+
+    def decorator(func: F) -> F:
+        # Build the warning message
+        name = getattr(func, "__qualname__", getattr(func, "__name__", str(func)))
+        message = f"{name} is deprecated since version {version}."
+
+        if removal_version:
+            message += f" It will be removed in version {removal_version}."
+
+        message += f" {reason}"
+
+        if isinstance(func, type):
+            # Handle class deprecation
+            original_init = func.__init__  # type: ignore[misc]
+
+            @functools.wraps(original_init)
+            def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+                warnings.warn(message, DeprecatedWarning, stacklevel=stacklevel)
+                original_init(self, *args, **kwargs)
+
+            func.__init__ = new_init  # type: ignore[misc]
+
+            # Add deprecation info to docstring
+            if func.__doc__:
+                func.__doc__ = f".. deprecated:: {version}\n   {reason}\n\n{func.__doc__}"
+            else:
+                func.__doc__ = f".. deprecated:: {version}\n   {reason}"
+
+            return func  # type: ignore[return-value]
+        else:
+            # Handle function deprecation
+            @functools.wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                warnings.warn(message, DeprecatedWarning, stacklevel=stacklevel)
+                return func(*args, **kwargs)
+
+            # Add deprecation info to docstring
+            if wrapper.__doc__:
+                wrapper.__doc__ = f".. deprecated:: {version}\n   {reason}\n\n{wrapper.__doc__}"
+            else:
+                wrapper.__doc__ = f".. deprecated:: {version}\n   {reason}"
+
+            return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def deprecated_parameter(
+    name: str,
+    version: str,
+    reason: str,
+    removal_version: str | None = None,
+    *,
+    stacklevel: int = 2,
+) -> None:
+    """Emit a deprecation warning for a deprecated parameter.
+
+    Call this function when a deprecated parameter is used. This should be
+    called at the beginning of a function that has deprecated parameters.
+
+    Args:
+        name: The name of the deprecated parameter.
+        version: The version in which the parameter was deprecated.
+        reason: The reason for deprecation and recommended alternative.
+        removal_version: The version in which the parameter will be removed.
+        stacklevel: Stack level for the warning (default 2 for immediate caller).
+
+    Example:
+        >>> def my_function(new_param: str, old_param: str | None = None):
+        ...     if old_param is not None:
+        ...         deprecated_parameter(
+        ...             name="old_param",
+        ...             version="1.2.0",
+        ...             reason="Use new_param instead"
+        ...         )
+        ...         new_param = old_param
+        ...     return new_param
+    """
+    message = f"Parameter '{name}' is deprecated since version {version}."
+
+    if removal_version:
+        message += f" It will be removed in version {removal_version}."
+
+    message += f" {reason}"
+
+    warnings.warn(message, DeprecatedWarning, stacklevel=stacklevel + 1)

svc_infra/webhooks/__init__.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, cast
+
+from .add import add_webhooks
+from .encryption import decrypt_secret, encrypt_secret, is_encrypted
+
+__all__ = [
+    "add_webhooks",
+    "encrypt_secret",
+    "decrypt_secret",
+    "is_encrypted",
+    "trigger_webhook",
+]
+
+_logger = logging.getLogger(__name__)
+
+
+async def trigger_webhook(
+    event: str,
+    data: dict[str, Any],
+    *,
+    webhook_service: Any | None = None,
+) -> int | None:
+    """
+    Trigger a webhook event.
+
+    This is a convenience function for sending webhook events. It requires
+    that webhooks have been configured via add_webhooks() first.
+
+    Args:
+        event: The event/topic name (e.g., "goal.milestone_reached")
+        data: The event payload data
+        webhook_service: Optional WebhookService instance. If not provided,
+                         attempts to use the global service from add_webhooks.
+
+    Returns:
+        The outbox message ID if successful, None if no webhook service configured.
+
+    Example:
+        from svc_infra.webhooks import trigger_webhook
+
+        await trigger_webhook(
+            event="user.created",
+            data={"user_id": "123", "email": "user@example.com"}
+        )
+
+    Note:
+        For this to work, you must first configure webhooks:
+
+        from svc_infra.webhooks import add_webhooks
+        add_webhooks(app)
+    """
+    if webhook_service is None:
+        # Try to get the global webhook service from app state
+        _logger.warning(
+            "No webhook_service provided and no global service configured. "
+            "Call add_webhooks(app) first to enable webhook delivery."
+        )
+        return None
+
+    try:
+        msg_id = cast("int", webhook_service.publish(event, data))
+        _logger.info(f"Triggered webhook event '{event}' with message ID {msg_id}")
+        return msg_id
+    except Exception as e:
+        _logger.error(f"Failed to trigger webhook event '{event}': {e}")
+        return None

svc_infra/webhooks/add.py

@@ -0,0 +1,327 @@
+"""FastAPI integration helpers for the webhooks router.
+
+The :func:`add_webhooks` helper wires the public router into an app and makes
+sure dependency overrides share a single set of stores instead of the in-file
+defaults that create a new in-memory object per request.  Callers can:
+
+* rely on the in-memory defaults (suitable for tests / local usage);
+* configure persistent stores through environment variables; or
+* provide concrete instances / factories explicitly via keyword arguments.
+
+When queue / scheduler objects are provided the helper also wires up the
+standard outbox tick task and webhook delivery job handler so the caller only
+needs to start their existing worker loop.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from collections.abc import Callable, Iterable, Mapping
+from datetime import UTC, datetime
+from typing import Any, Protocol, TypeGuard, TypeVar, cast
+
+from fastapi import FastAPI
+
+from svc_infra.db.inbox import InboxStore, InMemoryInboxStore
+from svc_infra.db.outbox import InMemoryOutboxStore, OutboxMessage, OutboxStore
+from svc_infra.jobs.builtins.outbox_processor import make_outbox_tick
+from svc_infra.jobs.builtins.webhook_delivery import make_webhook_handler
+from svc_infra.jobs.queue import JobQueue
+from svc_infra.jobs.scheduler import InMemoryScheduler
+
+from . import router as router_module
+from .service import InMemoryWebhookSubscriptions
+
+try:  # Optional dependency – only required when redis backends are selected.
+    from redis import Redis
+except Exception:  # pragma: no cover - redis is optional in most test runs.
+    Redis = None  # type: ignore[misc,assignment]
+
+logger = logging.getLogger(__name__)
+
+
+T_co = TypeVar("T_co", covariant=True)
+
+
+class _Factory(Protocol[T_co]):
+    def __call__(self) -> T_co:
+        pass
+
+
+class RedisOutboxStore(OutboxStore):
+    """Minimal Redis-backed outbox implementation used by :func:`add_webhooks`.
+
+    The implementation is intentionally lightweight – it keeps message payloads
+    in Redis hashes and a FIFO list of message identifiers.  It fulfils the
+    contract expected by :func:`make_outbox_tick` while remaining simple enough
+    for environments where a fully fledged SQL implementation is unavailable.
+    """
+
+    def __init__(self, client: Redis, *, prefix: str = "webhooks:outbox"):
+        if Redis is None:  # pragma: no cover - defensive guard
+            raise RuntimeError("redis-py is required for RedisOutboxStore")
+        self._client = client
+        self._prefix = prefix.rstrip(":")
+
+    # Redis key helpers -------------------------------------------------
+    @property
+    def _seq_key(self) -> str:
+        return f"{self._prefix}:seq"
+
+    @property
+    def _queue_key(self) -> str:
+        return f"{self._prefix}:queue"
+
+    def _msg_key(self, msg_id: int) -> str:
+        return f"{self._prefix}:msg:{msg_id}"
+
+    # Protocol methods --------------------------------------------------
+    def enqueue(self, topic: str, payload: dict[str, Any]) -> OutboxMessage:
+        incr_result = cast("Any", self._client.incr(self._seq_key))
+        # Redis incr always returns an int for the sync client. Be defensive for mocks.
+        try:
+            msg_id = int(incr_result)
+        except (TypeError, ValueError):
+            msg_id = 0
+        created_at = datetime.now(UTC)
+        record: dict[str, str] = {
+            "id": str(msg_id),
+            "topic": topic,
+            "payload": json.dumps(payload),
+            "created_at": created_at.isoformat(),
+            "attempts": "0",
+            "processed_at": "",
+        }
+        self._client.hset(self._msg_key(msg_id), mapping=record)
+        self._client.rpush(self._queue_key, msg_id)
+        return OutboxMessage(id=msg_id, topic=topic, payload=payload, created_at=created_at)
+
+    def fetch_next(self, topics: Iterable[str] | None = None) -> OutboxMessage | None:
+        allowed = set(topics) if topics else None
+        ids = cast("list[Any]", self._client.lrange(self._queue_key, 0, -1))
+        for raw_id in ids:
+            raw_id_str = raw_id.decode() if isinstance(raw_id, (bytes, bytearray)) else str(raw_id)
+            msg_id = int(raw_id_str)
+            msg = cast("dict[Any, Any]", self._client.hgetall(self._msg_key(msg_id)))
+            if not msg:
+                continue
+            topic = msg.get(b"topic")
+            if topic is None:
+                continue
+            topic_str = topic.decode() if isinstance(topic, (bytes, bytearray)) else str(topic)
+            if allowed is not None and topic_str not in allowed:
+                continue
+            attempts = int(msg.get(b"attempts", 0))
+            processed_raw = msg.get(b"processed_at") or b""
+            if processed_raw:
+                continue
+            if attempts > 0:
+                continue
+            payload_raw = msg.get(b"payload") or b"{}"
+            payload_txt = (
+                payload_raw.decode()
+                if isinstance(payload_raw, (bytes, bytearray))
+                else str(payload_raw)
+            )
+            payload = json.loads(payload_txt)
+            created_raw = msg.get(b"created_at") or b""
+            created_at = (
+                datetime.fromisoformat(
+                    created_raw.decode()
+                    if isinstance(created_raw, (bytes, bytearray))
+                    else str(created_raw)
+                )
+                if created_raw
+                else datetime.now(UTC)
+            )
+            return OutboxMessage(
+                id=msg_id,
+                topic=topic_str,
+                payload=payload,
+                created_at=created_at,
+                attempts=attempts,
+            )
+        return None
+
+    def mark_processed(self, msg_id: int) -> None:
+        key = self._msg_key(msg_id)
+        if not self._client.exists(key):
+            return
+        self._client.hset(key, "processed_at", datetime.now(UTC).isoformat())
+
+    def mark_failed(self, msg_id: int) -> None:
+        key = self._msg_key(msg_id)
+        self._client.hincrby(key, "attempts", 1)
+
+
+class RedisInboxStore(InboxStore):
+    """Lightweight Redis dedupe store for webhook deliveries."""
+
+    def __init__(self, client: Redis, *, prefix: str = "webhooks:inbox"):
+        if Redis is None:  # pragma: no cover - defensive guard
+            raise RuntimeError("redis-py is required for RedisInboxStore")
+        self._client = client
+        self._prefix = prefix.rstrip(":")
+
+    def _key(self, key: str) -> str:
+        return f"{self._prefix}:{key}"
+
+    def mark_if_new(self, key: str, ttl_seconds: int = 24 * 3600) -> bool:
+        return bool(self._client.set(self._key(key), 1, nx=True, ex=ttl_seconds))
+
+    def purge_expired(self) -> int:
+        # Redis takes care of expirations. We return 0 to satisfy the interface.
+        return 0
+
+    def is_marked(self, key: str) -> bool:
+        return bool(self._client.exists(self._key(key)))
+
+
+def _is_factory(obj: Any) -> TypeGuard[Callable[[], Any]]:
+    return callable(obj) and not isinstance(obj, (str, bytes, bytearray))
+
+
+def _resolve_value(value: T_co | _Factory[T_co] | None, default_factory: _Factory[T_co]) -> T_co:
+    if value is None:
+        return default_factory()
+    if _is_factory(value):
+        return cast("T_co", value())
+    return cast("T_co", value)
+
+
+def _build_redis_client(env: Mapping[str, str]) -> Redis | None:
+    if Redis is None:
+        logger.warning(
+            "Redis backend requested but redis-py is not installed; falling back to in-memory stores"
+        )
+        return None
+    url = env.get("REDIS_URL", "redis://localhost:6379/0")
+    return Redis.from_url(url)
+
+
+def _default_outbox(env: Mapping[str, str]) -> OutboxStore:
+    backend = (env.get("WEBHOOKS_OUTBOX") or "memory").lower()
+    if backend == "redis":
+        client = _build_redis_client(env)
+        if client is not None:
+            logger.info("Using Redis outbox store for webhooks")
+            return RedisOutboxStore(client)
+    elif backend == "sql":  # pragma: no cover - SQL backend is currently a placeholder
+        logger.warning(
+            "WEBHOOKS_OUTBOX=sql specified but SQL backend is not implemented; falling back to in-memory store"
+        )
+    return InMemoryOutboxStore()
+
+
+def _default_inbox(env: Mapping[str, str]) -> InboxStore:
+    backend = (env.get("WEBHOOKS_INBOX") or "memory").lower()
+    if backend == "redis":
+        client = _build_redis_client(env)
+        if client is not None:
+            logger.info("Using Redis inbox store for webhooks")
+            return RedisInboxStore(client)
+    return InMemoryInboxStore()
+
+
+def _default_subscriptions() -> InMemoryWebhookSubscriptions:
+    return InMemoryWebhookSubscriptions()
+
+
+def _subscription_lookup(
+    subs: InMemoryWebhookSubscriptions,
+) -> tuple[Callable[[str], str], Callable[[str], str]]:
+    def _get_url(topic: str) -> str:
+        items = subs.get_for_topic(topic)
+        if not items:
+            raise LookupError(f"No webhook subscription for topic '{topic}'")
+        return items[0].url
+
+    def _get_secret(topic: str) -> str:
+        items = subs.get_for_topic(topic)
+        if not items:
+            raise LookupError(f"No webhook subscription for topic '{topic}'")
+        return items[0].secret
+
+    return _get_url, _get_secret
+
+
+def add_webhooks(
+    app: FastAPI,
+    *,
+    outbox: OutboxStore | _Factory[OutboxStore] | None = None,
+    inbox: InboxStore | _Factory[InboxStore] | None = None,
+    subscriptions: (
+        InMemoryWebhookSubscriptions | _Factory[InMemoryWebhookSubscriptions] | None
+    ) = None,
+    queue: JobQueue | None = None,
+    scheduler: InMemoryScheduler | None = None,
+    schedule_tick: bool = True,
+    env: Mapping[str, str] = os.environ,
+) -> None:
+    """Attach the shared webhooks router and stores to a FastAPI app.
+
+    Parameters
+    ----------
+    app:
+        The FastAPI application to configure.
+    outbox / inbox / subscriptions:
+        Optional instances or callables returning instances to use.  When left
+        as ``None`` the helper chooses sensible defaults: in-memory stores for
+        local runs or Redis-backed stores when ``WEBHOOKS_OUTBOX`` /
+        ``WEBHOOKS_INBOX`` are set to ``"redis"`` and ``REDIS_URL`` is
+        available.
+    queue / scheduler:
+        Provide these when you want :func:`make_outbox_tick` and the webhook
+        delivery handler registered for you.  The tick task is scheduled every
+        second by default; disable that registration by passing
+        ``schedule_tick=False``.
+    env:
+        Mapping used to resolve environment-driven defaults.  Defaults to
+        :data:`os.environ` so standard environment variables Just Work.
+
+    Side effects
+    ------------
+    * ``app.include_router`` is invoked for :mod:`svc_infra.webhooks.router`.
+    * ``app.dependency_overrides`` is populated so router dependencies reuse the
+      shared stores.
+    * References are stored on ``app.state`` for further customisation:
+      ``webhooks_outbox``, ``webhooks_inbox``, ``webhooks_subscriptions``,
+      ``webhooks_outbox_tick`` (when a queue is present) and
+      ``webhooks_delivery_handler`` (when queue+inbox are present).
+    """
+
+    resolved_outbox = _resolve_value(outbox, lambda: _default_outbox(env))
+    resolved_inbox = _resolve_value(inbox, lambda: _default_inbox(env))
+    resolved_subs = _resolve_value(subscriptions, _default_subscriptions)
+
+    app.state.webhooks_outbox = resolved_outbox
+    app.state.webhooks_inbox = resolved_inbox
+    app.state.webhooks_subscriptions = resolved_subs
+
+    app.include_router(router_module.router)
+
+    app.dependency_overrides[router_module.get_outbox] = lambda: resolved_outbox
+    app.dependency_overrides[router_module.get_subs] = lambda: resolved_subs
+
+    outbox_tick = None
+    if queue is not None:
+        outbox_tick = make_outbox_tick(resolved_outbox, queue)
+        app.state.webhooks_outbox_tick = outbox_tick
+        if scheduler is not None and schedule_tick:
+            scheduler.add_task("webhooks.outbox", 1, outbox_tick)
+
+        url_lookup, secret_lookup = _subscription_lookup(resolved_subs)
+        handler = make_webhook_handler(
+            outbox=resolved_outbox,
+            inbox=resolved_inbox,
+            get_webhook_url_for_topic=url_lookup,
+            get_secret_for_topic=secret_lookup,
+        )
+        app.state.webhooks_delivery_handler = handler
+    elif scheduler is not None and schedule_tick:
+        logger.warning("Scheduler provided without queue; skipping outbox tick registration")
+
+
+__all__ = ["add_webhooks"]

svc_infra/webhooks/encryption.py

@@ -0,0 +1,115 @@
+"""Encryption utilities for webhook secrets.
+
+Provides symmetric encryption for webhook secrets stored in the outbox.
+Uses Fernet (AES-128-CBC with HMAC-SHA256) for authenticated encryption.
+
+The encryption key is derived from WEBHOOK_ENCRYPTION_KEY environment variable.
+In production, this MUST be set to a securely generated 32-byte base64 key.
+
+Generate a key:
+    python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+from functools import lru_cache
+from typing import cast
+
+from svc_infra.app.env import require_secret
+
+# Marker prefix for encrypted values
+_ENCRYPTED_PREFIX = "enc:v1:"
+
+
+def _get_encryption_key() -> bytes:
+    """Get the webhook encryption key, requiring it in production."""
+    key_str = require_secret(
+        os.getenv("WEBHOOK_ENCRYPTION_KEY"),
+        "WEBHOOK_ENCRYPTION_KEY",
+        dev_default="dev-only-webhook-encryption-key-not-for-production",
+    )
+    # If it's a Fernet key (44 chars base64), use it directly
+    # Otherwise derive a key from it using SHA256
+    if len(key_str) == 44 and key_str.endswith("="):
+        return base64.urlsafe_b64decode(key_str)
+    # Derive a 32-byte key from arbitrary string
+    return hashlib.sha256(key_str.encode()).digest()
+
+
+@lru_cache(maxsize=1)
+def _get_fernet():
+    """Get or create the Fernet cipher for encryption/decryption."""
+    try:
+        from cryptography.fernet import Fernet
+    except ImportError:
+        # If cryptography is not installed, fall back to no encryption
+        # but log a warning
+        import logging
+
+        logging.getLogger(__name__).warning(
+            "cryptography package not installed - webhook secrets will NOT be encrypted. "
+            "Install with: pip install cryptography"
+        )
+        return None
+
+    key = _get_encryption_key()
+    # Fernet requires a 32-byte key encoded as base64
+    fernet_key = base64.urlsafe_b64encode(key)
+    return Fernet(fernet_key)
+
+
+def encrypt_secret(plaintext: str) -> str:
+    """Encrypt a webhook secret for storage.
+
+    Args:
+        plaintext: The secret to encrypt
+
+    Returns:
+        Encrypted string with "enc:v1:" prefix, or original if encryption unavailable
+    """
+    fernet = _get_fernet()
+    if fernet is None:
+        return plaintext
+
+    encrypted = fernet.encrypt(plaintext.encode())
+    return _ENCRYPTED_PREFIX + cast("str", encrypted.decode())
+
+
+def decrypt_secret(ciphertext: str) -> str:
+    """Decrypt a webhook secret from storage.
+
+    Args:
+        ciphertext: The encrypted secret (with "enc:v1:" prefix)
+
+    Returns:
+        Decrypted plaintext secret
+
+    Note:
+        If the value doesn't have the encryption prefix, it's returned as-is
+        for backwards compatibility with existing unencrypted secrets.
+    """
+    # If not encrypted, return as-is (backwards compatibility)
+    if not ciphertext.startswith(_ENCRYPTED_PREFIX):
+        return ciphertext
+
+    fernet = _get_fernet()
+    if fernet is None:
+        # Can't decrypt without cryptography - return as-is
+        # This shouldn't happen in practice if encrypt_secret was used
+        import logging
+
+        logging.getLogger(__name__).error(
+            "Cannot decrypt webhook secret - cryptography package not installed"
+        )
+        return ciphertext
+
+    encrypted = ciphertext[len(_ENCRYPTED_PREFIX) :].encode()
+    return cast("str", fernet.decrypt(encrypted).decode())
+
+
+def is_encrypted(value: str) -> bool:
+    """Check if a value is encrypted."""
+    return value.startswith(_ENCRYPTED_PREFIX)