Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python
13.0 KB
Raw Blame
"""
API Key Service for managing user API keys for public API authentication.
"""

import hashlib
import hmac
import secrets
from datetime import UTC, datetime
from typing import Any

from config.settings import API_KEYS_INDEX_NAME
from utils.logging_config import get_logger

logger = get_logger(__name__)
API_KEY_HASH_PREFIX = "hmac-sha256:"


class APIKeyService:
    """Service for managing user API keys for public API authentication."""

    def __init__(self, session_manager=None):
        self.session_manager = session_manager

    def _generate_api_key(self) -> tuple[str, str, str]:
        """
        Generate a new API key.

        Returns:
            Tuple of (full_key, key_hash, key_prefix)
            - full_key: The complete API key to return to user (only shown once)
            - key_hash: keyed HMAC digest of the key for storage
            - key_prefix: First 12 chars for display (e.g., "orag_abc12345")
        """
        # Generate 32 bytes of random data, encode as base64url (no padding)
        random_bytes = secrets.token_urlsafe(32)

        # Create the full key with prefix
        full_key = f"orag_{random_bytes}"

        key_hash = self._hash_key(full_key)

        # Create prefix for display (orag_ + first 8 chars of random part)
        key_prefix = f"orag_{random_bytes[:8]}"

        return full_key, key_hash, key_prefix

    def _get_opensearch_client(self, jwt_token: str = None):
        """Get the appropriate OpenSearch client.

        Upstream-authenticated requests can use the user credential for scoped
        reads. Writes go through the backend client so the OpenSearch user role
        can stay read-only.
        """
        from config.settings import IBM_AUTH_ENABLED, clients

        if IBM_AUTH_ENABLED and jwt_token and self.session_manager:
            return clients.create_user_opensearch_client(jwt_token)
        return clients.opensearch

    def _get_write_opensearch_client(self):
        """Return the trusted backend OpenSearch client for API-key writes."""
        from config.settings import clients

        if clients.opensearch is None:
            raise RuntimeError("Backend OpenSearch write client is unavailable")
        return clients.opensearch

    def _hash_key(self, api_key: str) -> str:
        """Create the keyed lookup digest stored in OpenSearch."""
        from config.settings import SESSION_SECRET

        digest = hmac.digest(
            SESSION_SECRET.encode("utf-8"),
            api_key.encode("utf-8"),
            "sha256",
        ).hex()
        return f"{API_KEY_HASH_PREFIX}{digest}"

    def _legacy_hash_key(self, api_key: str) -> str:
        """Return the pre-HMAC lookup digest for backwards compatibility."""
        digest = hashlib.new("sha256", usedforsecurity=False)  # nosec B324
        digest.update(api_key.encode("utf-8"))
        return digest.hexdigest()

    def _candidate_hashes(self, api_key: str) -> list[str]:
        keyed_hash = self._hash_key(api_key)
        legacy_hash = self._legacy_hash_key(api_key)
        return [keyed_hash, legacy_hash]

    async def create_key(
        self,
        user_id: str,
        user_email: str,
        name: str,
        jwt_token: str = None,
    ) -> dict[str, Any]:
        """
        Create a new API key for a user.

        Args:
            user_id: The user's ID
            user_email: The user's email
            name: A friendly name for the key
            jwt_token: JWT token for OpenSearch authentication

        Returns:
            Dict with success status, key info, and the full key (only shown once)
        """
        try:
            # Generate the key
            full_key, key_hash, key_prefix = self._generate_api_key()

            # Create a unique key_id
            key_id = secrets.token_urlsafe(16)

            now = datetime.now(UTC).isoformat()

            # Create the document to store
            key_doc = {
                "key_id": key_id,
                "key_hash": key_hash,
                "key_prefix": key_prefix,
                "user_id": user_id,
                "user_email": user_email,
                "name": name,
                "created_at": now,
                "last_used_at": None,
                "revoked": False,
            }

            opensearch_client = self._get_write_opensearch_client()

            # Index the key document
            result = await opensearch_client.index(
                index=API_KEYS_INDEX_NAME,
                id=key_id,
                body=key_doc,
                refresh="wait_for",
            )

            if result.get("result") in ("created", "updated"):
                logger.info(
                    "Created API key",
                    user_id=user_id,
                    key_id=key_id,
                    key_prefix=key_prefix,
                )
                return {
                    "success": True,
                    "key_id": key_id,
                    "key_prefix": key_prefix,
                    "name": name,
                    "created_at": now,
                    "api_key": full_key,  # Only returned once!
                }
            else:
                return {"success": False, "error": "Failed to create API key"}

        except Exception as e:
            logger.error("Failed to create API key", error=str(e), user_id=user_id)
            return {"success": False, "error": str(e)}

    async def validate_key(self, api_key: str) -> dict[str, Any] | None:
        """
        Validate an API key and return user info if valid.

        Args:
            api_key: The full API key to validate

        Returns:
            Dict with user info if valid, None if invalid
        """
        try:
            # Check key format
            if not api_key or not api_key.startswith("orag_"):
                return None

            key_hash = self._hash_key(api_key)
            candidate_hashes = self._candidate_hashes(api_key)

            opensearch_client = self._get_opensearch_client()

            # Search for the key by hash
            search_body = {
                "query": {
                    "bool": {
                        "must": [
                            {"terms": {"key_hash": candidate_hashes}},
                            {"term": {"revoked": False}},
                        ]
                    }
                },
                "size": 1,
            }

            result = await opensearch_client.search(
                index=API_KEYS_INDEX_NAME,
                body=search_body,
            )

            hits = result.get("hits", {}).get("hits", [])
            if not hits:
                return None

            key_doc = hits[0]["_source"]

            matched_hash = key_doc.get("key_hash")

            # Update last_used_at and opportunistically migrate legacy hashes.
            try:
                write_client = self._get_write_opensearch_client()
                update_doc = {"last_used_at": datetime.now(UTC).isoformat()}
                if matched_hash != key_hash:
                    update_doc["key_hash"] = key_hash
                await write_client.update(
                    index=API_KEYS_INDEX_NAME,
                    id=key_doc["key_id"],
                    body={"doc": update_doc},
                )
            except Exception:
                pass  # Don't fail validation if update fails

            return {
                "key_id": key_doc["key_id"],
                "user_id": key_doc["user_id"],
                "user_email": key_doc["user_email"],
                "name": key_doc["name"],
            }

        except Exception as e:
            logger.error("Failed to validate API key", error=str(e))
            return None

    async def list_keys(
        self,
        user_id: str,
        jwt_token: str = None,
    ) -> dict[str, Any]:
        """
        List all active (non-revoked) API keys for a user (without the actual keys).

        Args:
            user_id: The user's ID
            jwt_token: JWT token for OpenSearch authentication

        Returns:
            Dict with list of key metadata
        """
        try:
            opensearch_client = self._get_opensearch_client(jwt_token)

            # Search for user's keys
            search_body = {
                "query": {
                    "bool": {
                        "must": [
                            {"term": {"user_id": user_id}},
                            {"term": {"revoked": False}},
                        ]
                    }
                },
                "sort": [{"created_at": {"order": "desc"}}],
                "_source": [
                    "key_id",
                    "key_prefix",
                    "name",
                    "created_at",
                    "last_used_at",
                    "revoked",
                ],
                "size": 100,
            }

            result = await opensearch_client.search(
                index=API_KEYS_INDEX_NAME,
                body=search_body,
            )

            keys = []
            for hit in result.get("hits", {}).get("hits", []):
                keys.append(hit["_source"])

            return {"success": True, "keys": keys}

        except Exception as e:
            logger.error("Failed to list API keys", error=str(e), user_id=user_id)
            return {"success": False, "error": str(e), "keys": []}

    async def revoke_key(
        self,
        user_id: str,
        key_id: str,
        jwt_token: str = None,
    ) -> dict[str, Any]:
        """
        Revoke an API key.

        Args:
            user_id: The user's ID (for authorization)
            key_id: The key ID to revoke
            jwt_token: JWT token for OpenSearch authentication

        Returns:
            Dict with success status
        """
        try:
            opensearch_client = self._get_opensearch_client(jwt_token)

            # First, verify the key belongs to this user
            try:
                doc = await opensearch_client.get(
                    index=API_KEYS_INDEX_NAME,
                    id=key_id,
                )

                if doc["_source"]["user_id"] != user_id:
                    return {"success": False, "error": "Not authorized to revoke this key"}

            except Exception:
                return {"success": False, "error": "Key not found"}

            # Update the key to mark as revoked with the trusted backend client.
            write_client = self._get_write_opensearch_client()
            result = await write_client.update(
                index=API_KEYS_INDEX_NAME,
                id=key_id,
                body={"doc": {"revoked": True}},
                refresh="wait_for",
            )

            if result.get("result") == "updated":
                logger.info(
                    "Revoked API key",
                    user_id=user_id,
                    key_id=key_id,
                )
                return {"success": True}
            else:
                return {"success": False, "error": "Failed to revoke key"}

        except Exception as e:
            logger.error(
                "Failed to revoke API key",
                error=str(e),
                user_id=user_id,
                key_id=key_id,
            )
            return {"success": False, "error": str(e)}

    async def delete_key(
        self,
        user_id: str,
        key_id: str,
        jwt_token: str = None,
    ) -> dict[str, Any]:
        """
        Permanently delete an API key.

        Args:
            user_id: The user's ID (for authorization)
            key_id: The key ID to delete
            jwt_token: JWT token for OpenSearch authentication

        Returns:
            Dict with success status
        """
        try:
            opensearch_client = self._get_opensearch_client(jwt_token)

            # First, verify the key belongs to this user
            try:
                doc = await opensearch_client.get(
                    index=API_KEYS_INDEX_NAME,
                    id=key_id,
                )

                if doc["_source"]["user_id"] != user_id:
                    return {"success": False, "error": "Not authorized to delete this key"}

            except Exception:
                return {"success": False, "error": "Key not found"}

            # Delete the key with the trusted backend client.
            write_client = self._get_write_opensearch_client()
            result = await write_client.delete(
                index=API_KEYS_INDEX_NAME,
                id=key_id,
                refresh="wait_for",
            )

            if result.get("result") == "deleted":
                logger.info(
                    "Deleted API key",
                    user_id=user_id,
                    key_id=key_id,
                )
                return {"success": True}
            else:
                return {"success": False, "error": "Failed to delete key"}

        except Exception as e:
            logger.error(
                "Failed to delete API key",
                error=str(e),
                user_id=user_id,
                key_id=key_id,
            )
            return {"success": False, "error": str(e)}