iatoolkit 0.11.0__py3-none-any.whl → 0.66.2__py3-none-any.whl

iatoolkit/infra/redis_session_manager.py

@@ -37,9 +37,14 @@ class RedisSessionManager:
         return cls._client
 
     @classmethod
-    def set(cls, key: str, value: str, ex: int = None):
+    def set(cls, key: str, value: str, **kwargs):
+        """
+        Método set flexible que pasa argumentos opcionales (como ex, nx)
+        directamente al cliente de redis.
+        """
         client = cls._get_client()
-        result = client.set(key, value, ex=ex)
+        # Pasa todos los argumentos de palabra clave adicionales al cliente real
+        result = client.set(key, value, **kwargs)
         return result
 
     @classmethod
@@ -49,12 +54,53 @@ class RedisSessionManager:
         result = value if value is not None else default
         return result
 
+    @classmethod
+    def hset(cls, key: str, field: str, value: str):
+        """
+        Establece un campo en un Hash de Redis.
+        """
+        client = cls._get_client()
+        return client.hset(key, field, value)
+
+    @classmethod
+    def hget(cls, key: str, field: str):
+        """
+        Obtiene el valor de un campo de un Hash de Redis.
+        Devuelve None si la clave o el campo no existen.
+        """
+        client = cls._get_client()
+        return client.hget(key, field)
+
+    @classmethod
+    def hdel(cls, key: str, *fields):
+        """
+        Elimina uno o más campos de un Hash de Redis.
+        """
+        client = cls._get_client()
+        return client.hdel(key, *fields)
+
+    @classmethod
+    def pipeline(cls):
+        """
+        Inicia una transacción (pipeline) de Redis.
+        """
+        client = cls._get_client()
+        return client.pipeline()
+
+
     @classmethod
     def remove(cls, key: str):
         client = cls._get_client()
         result = client.delete(key)
         return result
 
+    @classmethod
+    def exists(cls, key: str) -> bool:
+        """Verifica si una clave existe en Redis."""
+        client = cls._get_client()
+        # El comando EXISTS de Redis devuelve un entero (0 o 1). Lo convertimos a booleano.
+        return bool(client.exists(key))
+
     @classmethod
     def set_json(cls, key: str, value: dict, ex: int = None):
         json_str = json.dumps(value)

iatoolkit/locales/en.yaml

@@ -0,0 +1,144 @@
+# Language: English
+ui:
+  login_widget:
+    title: "Sign In"
+    welcome_message: "Enter your credentials or register to access Sample Company’s AI platform."
+    email_placeholder: "Email address"
+    password_placeholder: "Password"
+    login_button: "Login"
+    forgot_password_link: "Forgot your password?"
+    no_account_prompt: "Don't have an account?"
+    signup_link: "Sign Up"
+
+  signup:
+    title: "Create an Account"
+    subtitle: "Start your journey with us today."
+    first_name_label: "First Name"
+    last_name_label: "Last Name"
+    email_label: "Email Address"
+    password_label: "Password"
+    confirm_password_label: "Confirm Password"
+    signup_button: "Create Account"
+    already_have_account: "Already have an account?"
+    login_link: "Log In"
+    disclaimer: "🔒We value your privacy. Your data will be used exclusively for the operation of the platform."
+
+  forgot_password:
+    title: "Recover Password"
+    subtitle: "Enter your email address and we will send you a link to reset your password."
+    submit_button: "Send Recovery Link"
+    back_to_login: "Back to Login"
+
+  change_password:
+    title: "Create New Password"
+    subtitle: "You are changing the password for <strong>{email}</strong>."
+    temp_code_label: "Temporary Code"
+    temp_code_placeholder: "Check your email"
+    new_password_label: "New Password"
+    password_instructions: "Must contain at least 8 characters, an uppercase letter, a lowercase letter, a number, and a special character."
+    confirm_password_label: "Confirm New Password"
+    save_button: "Save Password"
+    back_to_home: "Back to home"
+
+  chat:
+    welcome_message: "Hello! How can I help you today?"
+    input_placeholder: "Type your query here..."
+    prompts_available: "Available prompts"
+
+  tooltips:
+    history: "History of my queries"
+    reload_context: "Force Context Reload"
+    feedback: "Your feedback is very important"
+    usage_guide: "Usage Guide"
+    onboarding: "How to ask better questions"
+    logout: "Log out"
+    use_prompt_assistant: "Use Prompt Assistant"
+    attach_files: "Attach files"
+    view_attached_files: "View attached files"
+    send: "Send"
+    stop: "Stop"
+
+  modals:
+    files_title: "Uploaded Files"
+    feedback_title: "Your Opinion is Important"
+    feedback_prompt: "How useful was the assistant's response?"
+    feedback_comment_label: "Your feedback helps us improve:"
+    feedback_comment_placeholder: "Write your opinion, suggestions, or comments here..."
+    history_title: "Query History"
+    history_table_date: "Date"
+    history_table_query: "Query"
+    loading_history: "Loading history..."
+    no_history_found: "No query history found."
+    help_title: "AI Assistant User Guide"
+
+  buttons:
+    cancel: "Close"
+    send: "Send"
+    stop: "Stop"
+
+errors:
+  auth:
+    invalid_password: "The provided password is incorrect."
+    user_not_found: "A user with that email address was not found."
+    invalid_or_expired_token: "Invalid or expired token."
+    session_creation_failed: "Could not create user session."
+    authentication_required: "Authentication required. No session cookie or API Key provided."
+    invalid_api_key: "Invalid or inactive API Key."
+    no_user_identifier_api: "No user_identifier provided for API call."
+  templates:
+    company_not_found: "Company not found."
+    home_template_not_found: "The home page template for the company '{company_name}' is not configured."
+    template_not_found: "Template not found: '{template_name}'."
+
+    processing_error: "An error occurred while processing the custom home page template: {error}"
+  general:
+    unexpected_error: "An unexpected error has occurred. Please contact support."
+    unsupported_language: "The selected language is not supported."
+  signup:
+    company_not_found: "The company {company_name} does not exist."
+    incorrect_password_for_existing_user: "The password for the user {email} is incorrect."
+    user_already_registered: "The user with email '{email}' already exists in this company."
+    password_mismatch: "The passwords do not match. Please try again."
+  change_password:
+    token_expired: "The password change link has expired. Please request a new one."
+    password_mismatch: "The passwords do not match. Please try again."
+    invalid_temp_code: "The temporary code is not valid. Please check it or request a new one."
+  forgot_password:
+    user_not_registered: "The user with email {email} is not registered."
+  verification:
+    token_expired: "The verification link has expired. Please contact support if you need a new one."
+    user_not_found: "The user you are trying to verify does not exist."
+  validation:
+    password_too_short: "Password must be at least 8 characters long."
+    password_no_uppercase: "Password must contain at least one uppercase letter."
+    password_no_lowercase: "Password must contain at least one lowercase letter."
+    password_no_digit: "Password must contain at least one number."
+    password_no_special_char: "Password must contain at least one special character."
+
+api_responses:
+  context_reloaded_success: "The context has been successfully reloaded."
+
+flash_messages:
+  password_changed_success: "Your password has been successfully reset. You can now log in."
+  login_required: "Please log in to continue."
+  signup_success: "Registration successful. Please check your email to verify your account."
+  user_associated_success: "Existing user successfully associated with the new company."
+  account_verified_success: "Your account has been successfully verified. Welcome!"
+  forgot_password_success: "If your email is registered, you will receive a link to reset your password."
+
+# Keys specifically for JavaScript
+js_messages:
+  feedback_sent_success_title: "Feedback Sent"
+  feedback_sent_success_body: "Thank you for your feedback!"
+  feedback_sent_error: "Could not send feedback, please try again."
+  feedback_rating_error: "Please rate the assistant using the stars."
+  feedback_comment_error: "Please write your comment before sending."
+  context_reloaded: "Context has been reloaded."
+  error_loading_history: "An error occurred while loading the history."
+  request_aborted: "The response generation has been stopped."
+  processing_error: "An error occurred while processing the request."
+  server_comm_error: "Server communication error ({status}). Please try again later."
+  network_error: "A network error occurred. Please try again in a few moments."
+  unknown_server_error: "Unknown server error."
+  loading: "Loading..."
+  reload_init: "init reloading context in background..."

iatoolkit/locales/es.yaml

@@ -0,0 +1,140 @@
+    # locales/es.yaml
+    ui:
+      login_widget:
+        title: "Iniciar Sesión"
+        welcome_message: "Ingresa tus credenciales o registrate para acceder a la plataforma IA de Sample Company."
+        email_placeholder: "Correo electrónico"
+        login_button: "Acceder"
+        forgot_password_link: "¿Olvidaste tu contraseña?"
+        no_account_prompt: "¿No tienes una cuenta?"
+        signup_link: "Regístrate"
+
+      signup:
+        title: "Crear una Cuenta"
+        subtitle: "Comienza tu viaje con nosotros hoy."
+        first_name_label: "Nombre"
+        last_name_label: "Apellido"
+        email_label: "Correo Electrónico"
+        password_label: "Contraseña"
+        confirm_password_label: "Confirmar Contraseña"
+        signup_button: "Crear Cuenta"
+        already_have_account: "¿Ya tienes una cuenta?"
+        login_link: "Inicia Sesión"
+        disclaimer: "🔒 Valoramos tu privacidad. Tus datos se usarán exclusivamente para el funcionamiento de la plataforma."
+
+      forgot_password:
+        title: "Recuperar Contraseña"
+        subtitle: "Ingresa tu correo electrónico y te enviaremos un enlace para restablecer tu contraseña."
+        submit_button: "Enviar Enlace de Recuperación"
+        back_to_login: "Volver a Iniciar Sesión"
+
+      change_password:
+        title: "Crear Nueva Contraseña"
+        subtitle: "Estás cambiando la contraseña para <strong>{email}</strong>."
+        temp_code_label: "Código Temporal"
+        temp_code_placeholder: "Revisa tu correo electrónico"
+        new_password_label: "Nueva Contraseña"
+        password_instructions: "Debe contener al menos 8 caracteres, mayúscula, minúscula, número y un carácter especial."
+        confirm_password_label: "Confirmar Nueva Contraseña"
+        save_button: "Guardar Contraseña"
+        back_to_home: "Volver al inicio"
+
+      chat:
+        welcome_message: "¡Hola! ¿En qué te puedo ayudar hoy?"
+        input_placeholder: "Escribe tu consulta aquí..."
+        prompts_available: "Prompts disponibles"
+
+      tooltips:
+        history: "Historial con mis consultas"
+        reload_context: "Forzar Recarga de Contexto"
+        feedback: "Tu feedback es muy importante"
+        usage_guide: "Guía de Uso"
+        onboarding: "Cómo preguntar mejor"
+        logout: "Cerrar sesión"
+        use_prompt_assistant: "Usar Asistente de Prompts"
+        attach_files: "Adjuntar archivos"
+        view_attached_files: "Ver archivos adjuntos"
+      modals:
+        files_title: "Archivos Cargados"
+        feedback_title: "Tu Opinión es Importante"
+        feedback_prompt: "¿Qué tan útil fue la respuesta del asistente?"
+        feedback_comment_label: "Tu comentario nos ayuda a mejorar:"
+        feedback_comment_placeholder: "Escribe aquí tu opinión, sugerencias o comentarios..."
+        history_title: "Historial de Consultas"
+        history_table_date: "Fecha"
+        history_table_query: "Consulta"
+        loading_history: "Cargando historial..."
+        no_history_found: "No se encontró historial de consultas."
+        help_title: "Guía de uso del Asistente IA"
+
+      buttons:
+        cancel: "Cerrar"
+        send: "Enviar"
+        stop: "Detener"
+
+    errors:
+      auth:
+        invalid_password: "La contraseña proporcionada es incorrecta."
+        user_not_found: "No se encontró un usuario con ese correo."
+        invalid_or_expired_token: "Token inválido o expirado."
+        session_creation_failed: "No se pudo crear la sesión del usuario."
+        authentication_required: "Autenticación requerida. No se proporcionó cookie de sesión o clave de API."
+        invalid_api_key: "Clave de API inválida o inactiva."
+        no_user_identifier_api: "No se proporcionó user_identifier para la llamada a la API."
+      templates:
+        company_not_found: "Empresa no encontrada."
+        home_template_not_found: "La plantilla de la página de inicio para la empresa '{company_name}' no está configurada."
+        template_not_found: "No se encontro el template: '{template_name}'."
+        processing_error: "Ocurrió un error al procesar la plantilla personalizada de la página de inicio: {error}"
+
+      general:
+        unexpected_error: "Ha ocurrido un error inesperado. Por favor, contacta a soporte."
+        unsupported_language: "El idioma seleccionado no es válido."
+      signup:
+        company_not_found: "La empresa {company_name} no existe."
+        incorrect_password_for_existing_user: "La contraseña para el usuario {email} es incorrecta."
+        user_already_registered: "El usuario con email '{email}' ya existe en esta empresa."
+        password_mismatch: "Las contraseñas no coinciden. Por favor, inténtalo de nuevo."
+      change_password:
+        token_expired: "El enlace de cambio de contraseña ha expirado. Por favor, solicita uno nuevo."
+        password_mismatch: "Las contraseñas no coinciden. Por favor, inténtalo nuevamente."
+        invalid_temp_code: "El código temporal no es válido. Por favor, verifica o solicita uno nuevo."
+      forgot_password:
+        user_not_registered: "El usuario con correo {email} no está registrado."
+      verification:
+        token_expired: "El enlace de verificación ha expirado. Por favor, contacta a soporte si necesitas uno nuevo."
+        user_not_found: "El usuario que intentas verificar no existe."
+      validation:
+        password_too_short: "La contraseña debe tener al menos 8 caracteres."
+        password_no_uppercase: "La contraseña debe tener al menos una letra mayúscula."
+        password_no_lowercase: "La contraseña debe tener al menos una letra minúscula."
+        password_no_digit: "La contraseña debe tener al menos un número."
+        password_no_special_char: "La contraseña debe tener al menos un carácter especial."
+
+    api_responses:
+      context_reloaded_success: "El contexto se ha recargado con éxito."
+
+    flash_messages:
+      password_changed_success: "Tu contraseña ha sido restablecida exitosamente. Ahora puedes iniciar sesión."
+      signup_success: "Registro exitoso. Por favor, revisa tu correo para verificar tu cuenta."
+      user_associated_success: "Usuario existente asociado exitosamente a la nueva empresa."
+      account_verified_success: "Tu cuenta ha sido verificada exitosamente. ¡Bienvenido!"
+      forgot_password_success: "Si tu correo está registrado, recibirás un enlace para restablecer tu contraseña."
+
+    # Claves específicas para JavaScript
+    js_messages:
+      feedback_sent_success_title: "Feedback Enviado"
+      feedback_sent_success_body: "¡Gracias por tu comentario!"
+      feedback_sent_error: "No se pudo enviar el feedback, por favor intente nuevamente."
+      feedback_rating_error: "Por favor, califica al asistente con las estrellas."
+      feedback_comment_error: "Por favor, escribe tu comentario antes de enviar."
+      context_reloaded: "El contexto ha sido recargado."
+      error_loading_history: "Ocurrió un error al cargar el historial."
+      request_aborted: "La generación de la respuesta ha sido detenida."
+      processing_error: "Ocurrió un error al procesar la solicitud."
+      server_comm_error: "Error de comunicación con el servidor ({status}). Por favor, intente de nuevo más tarde."
+      network_error: "Ocurrió un error de red. Por favor, inténtalo de nuevo en unos momentos."
+      unknown_server_error: "Error desconocido del servidor."
+      loading: "Cargando..."
+      reload_init: "Iniciando recarga de contexto en segundo plano..."
+

iatoolkit/repositories/database_manager.py

@@ -21,8 +21,23 @@ class DatabaseManager:
         :param echo: Si True, habilita logs de SQL.
         """
         self.url = make_url(database_url)
-        self._engine = create_engine(database_url, echo=False)
-        self.SessionFactory = sessionmaker(bind=self._engine)
+        if database_url.startswith('sqlite'):       # for tests
+            self._engine = create_engine(database_url, echo=False)
+        else:
+            self._engine = create_engine(
+                database_url,
+                echo=False,
+                pool_size=2,  # per worker
+                max_overflow=3,
+                pool_timeout=30,
+                pool_recycle=1800,
+                pool_pre_ping=True,
+                future=True,
+            )
+        self.SessionFactory = sessionmaker(bind=self._engine,
+                                           autoflush=False,
+                                           autocommit=False,
+                                           expire_on_commit=False)
         self.scoped_session = scoped_session(self.SessionFactory)
 
         # REGISTRAR pgvector para cada nueva conexión solo en postgres

iatoolkit/repositories/models.py

@@ -3,9 +3,10 @@
 #
 # IAToolkit is open source software.
 
-from sqlalchemy import Column, Integer, String, DateTime, Enum, Text, JSON, Boolean, ForeignKey, Table
+from sqlalchemy import Column, Integer, BigInteger, String, DateTime, Enum, Text, JSON, Boolean, ForeignKey, Table
 from sqlalchemy.orm import DeclarativeBase
 from sqlalchemy.orm import relationship, class_mapper, declarative_base
+from sqlalchemy.sql import func
 from datetime import datetime
 from pgvector.sqlalchemy import Vector
 from enum import Enum as PyEnum
@@ -52,13 +53,15 @@ class Company(Base):
     id = Column(Integer, primary_key=True)
     short_name = Column(String(20), nullable=False, unique=True, index=True)
     name = Column(String(256), nullable=False)
+    default_language = Column(String(5), nullable=False, default='es')
 
     # encrypted api-key
     openai_api_key = Column(String, nullable=True)
     gemini_api_key = Column(String, nullable=True)
 
     branding = Column(JSON, nullable=True)
-    parameters = Column(JSON, nullable=True, default={})
+    onboarding_cards = Column(JSON, nullable=True)
+    parameters = Column(JSON, nullable=True)
     created_at = Column(DateTime, default=datetime.now)
     allow_jwt = Column(Boolean, default=True, nullable=True)
 
@@ -105,6 +108,7 @@ class User(Base):
     created_at = Column(DateTime, default=datetime.now)
     password = Column(String, nullable=False)
     verified = Column(Boolean, nullable=False, default=False)
+    preferred_language = Column(String(5), nullable=True)
     verification_url = Column(String, nullable=True)
     temp_code = Column(String, nullable=True)
 
@@ -264,8 +268,7 @@ class UserFeedback(Base):
     id = Column(Integer, primary_key=True)
     company_id = Column(Integer, ForeignKey('iat_companies.id',
                                             ondelete='CASCADE'), nullable=False)
-    local_user_id = Column(Integer, default=0, nullable=True)
-    external_user_id = Column(String(128), default='', nullable=True)
+    user_identifier = Column(String(128), default='', nullable=True)
     message = Column(Text, nullable=False)
     rating = Column(Integer, nullable=False)
     created_at = Column(DateTime, default=datetime.now)
@@ -307,3 +310,27 @@ class Prompt(Base):
 
     company = relationship("Company", back_populates="prompts")
     category = relationship("PromptCategory", back_populates="prompts")
+
+class AccessLog(Base):
+    # Modelo ORM para registrar cada intento de acceso a la plataforma.
+    __tablename__ = 'iat_access_log'
+
+    id = Column(BigInteger, primary_key=True)
+
+    timestamp = Column(DateTime(timezone=True), server_default=func.now(), nullable=False, index=True)
+    company_short_name = Column(String(100), nullable=False, index=True)
+    user_identifier = Column(String(255), index=True)
+
+    # Cómo y el Resultado
+    auth_type = Column(String(20), nullable=False) # 'local', 'external_api', 'redeem_token', etc.
+    outcome = Column(String(10), nullable=False)   # 'success' o 'failure'
+    reason_code = Column(String(50))               # Causa de fallo, ej: 'INVALID_CREDENTIALS'
+
+    # Contexto de la Petición
+    source_ip = Column(String(45), nullable=False)
+    user_agent_hash = Column(String(16))           # Hash corto del User-Agent
+    request_path = Column(String(255), nullable=False)
+
+    def __repr__(self):
+        return (f"<AccessLog(id={self.id}, company='{self.company_short_name}', "
+                f"user='{self.user_identifier}', outcome='{self.outcome}')>")

iatoolkit/repositories/profile_repo.py

@@ -72,9 +72,14 @@ class ProfileRepo:
     def create_company(self, new_company: Company):
         company = self.session.query(Company).filter_by(name=new_company.name).first()
         if company:
-            company.parameters = new_company.parameters
-            company.branding = new_company.branding
+            if company.parameters != new_company.parameters:
+                company.parameters = new_company.parameters
+            if company.branding != new_company.branding:
+                company.branding = new_company.branding
+            if company.onboarding_cards != new_company.onboarding_cards:
+                company.onboarding_cards = new_company.onboarding_cards
         else:
+            # Si la compañía no existe, la añade a la sesión.
             self.session.add(new_company)
             company = new_company
 

iatoolkit/services/auth_service.py

@@ -0,0 +1,193 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+from flask import request
+from injector import inject
+from iatoolkit.services.profile_service import ProfileService
+from iatoolkit.services.jwt_service import JWTService
+from iatoolkit.services.i18n_service import I18nService
+from iatoolkit.repositories.database_manager import DatabaseManager
+from iatoolkit.repositories.models import AccessLog
+from flask import request
+import logging
+import hashlib
+
+
+class AuthService:
+    """
+    Centralized service for handling authentication for all incoming requests.
+    It determines the user's identity based on either a Flask session cookie or an API Key.
+    """
+
+    @inject
+    def __init__(self, profile_service: ProfileService,
+                 jwt_service: JWTService,
+                 db_manager: DatabaseManager,
+                 i18n_service: I18nService
+                 ):
+        self.profile_service = profile_service
+        self.jwt_service = jwt_service
+        self.db_manager = db_manager
+        self.i18n_service = i18n_service
+
+    def login_local_user(self, company_short_name: str, email: str, password: str) -> dict:
+        # try to autenticate a local user, register the event and return the result
+        auth_response = self.profile_service.login(
+            company_short_name=company_short_name,
+            email=email,
+            password=password,
+        )
+
+        if not auth_response.get('success'):
+            self.log_access(
+                company_short_name=company_short_name,
+                user_identifier=email,
+                auth_type='local',
+                outcome='failure',
+                reason_code='INVALID_CREDENTIALS',
+            )
+        else:
+            self.log_access(
+                company_short_name=company_short_name,
+                auth_type='local',
+                outcome='success',
+                user_identifier=auth_response.get('user_identifier')
+            )
+
+        return auth_response
+
+    def redeem_token_for_session(self, company_short_name: str, token: str) -> dict:
+        # redeem a token for a session, register the event and return the result
+        payload = self.jwt_service.validate_chat_jwt(token)
+
+        if not payload:
+            self.log_access(
+                company_short_name=company_short_name,
+                auth_type='redeem_token',
+                outcome='failure',
+                reason_code='JWT_INVALID'
+            )
+            return {'success': False, 'error': self.i18n_service.t('errors.auth.invalid_or_expired_token')}
+
+        # 2. if token is valid, extract the user_identifier
+        user_identifier = payload.get('user_identifier')
+        try:
+            # create the Flask session
+            self.profile_service.set_session_for_user(company_short_name, user_identifier)
+            self.log_access(
+                company_short_name=company_short_name,
+                auth_type='redeem_token',
+                outcome='success',
+                user_identifier=user_identifier
+            )
+            return {'success': True, 'user_identifier': user_identifier}
+        except Exception as e:
+            logging.error(f"Error al crear la sesión desde token para {user_identifier}: {e}")
+            self.log_access(
+                company_short_name=company_short_name,
+                auth_type='redeem_token',
+                outcome='failure',
+                reason_code='SESSION_CREATION_FAILED',
+                user_identifier=user_identifier
+            )
+            return {'success': False, 'error': self.i18n_service.t('errors.auth.session_creation_failed')}
+
+    def verify(self, anonymous: bool = False) -> dict:
+        """
+        Verifies the current request and identifies the user.
+        If anonymous is True the non-presence of use_identifier is ignored
+
+        Returns a dictionary with:
+        - success: bool
+        - user_identifier: str (if successful)
+        - company_short_name: str (if successful)
+        - error_message: str (on failure)
+        - status_code: int (on failure)
+        """
+        # --- Priority 1: Check for a valid Flask web session ---
+        session_info = self.profile_service.get_current_session_info()
+        if session_info and session_info.get('user_identifier'):
+            # User is authenticated via a web session cookie.
+            return {
+                "success": True,
+                "company_short_name": session_info['company_short_name'],
+                "user_identifier": session_info['user_identifier'],
+            }
+
+        # --- Priority 2: Check for a valid API Key in headers ---
+        api_key = None
+        auth = request.headers.get('Authorization', '')
+        if isinstance(auth, str) and auth.lower().startswith('bearer '):
+            api_key =  auth.split(' ', 1)[1].strip()
+
+        if not api_key:
+            # --- Failure: No valid credentials found ---
+            logging.info(f"Authentication required. No session cookie or API Key provided.")
+            return {"success": False,
+                    "error_message": self.i18n_service.t('errors.auth.authentication_required'),
+                    "status_code": 401}
+
+        # check if the api-key is valid and active
+        api_key_entry = self.profile_service.get_active_api_key_entry(api_key)
+        if not api_key_entry:
+            logging.info(f"Invalid or inactive API Key {api_key}")
+            return {"success": False,
+                    "error_message": self.i18n_service.t('errors.auth.invalid_api_key'),
+                    "status_code": 402}
+
+        # get the company from the api_key_entry
+        company = api_key_entry.company
+
+        # For API calls, the external_user_id must be provided in the request.
+        data = request.get_json(silent=True) or {}
+        user_identifier = data.get('user_identifier', '')
+        if not anonymous and not user_identifier:
+            logging.info(f"No user_identifier provided for API call.")
+            return {"success": False,
+                    "error_message": self.i18n_service.t('errors.auth.no_user_identifier_api'),
+                    "status_code": 403}
+
+        return {
+            "success": True,
+            "company_short_name": company.short_name,
+            "user_identifier": user_identifier
+        }
+
+
+    def log_access(self,
+                   company_short_name: str,
+                   auth_type: str,
+                   outcome: str,
+                   user_identifier: str = None,
+                   reason_code: str = None):
+        """
+        Registra un intento de acceso en la base de datos.
+        Es "best-effort" y no debe interrumpir el flujo de autenticación.
+        """
+        session = self.db_manager.scoped_session()
+        try:
+            # Capturar datos del contexto de la petición de Flask
+            source_ip = request.headers.get('X-Forwarded-For', request.remote_addr)
+            path = request.path
+            ua = request.headers.get('User-Agent', '')
+            ua_hash = hashlib.sha256(ua.encode()).hexdigest()[:16] if ua else None
+
+            # Crear la entrada de log
+            log_entry = AccessLog(
+                company_short_name=company_short_name,
+                user_identifier=user_identifier,
+                auth_type=auth_type,
+                outcome=outcome,
+                reason_code=reason_code,
+                source_ip=source_ip,
+                user_agent_hash=ua_hash,
+                request_path=path,
+            )
+            session.add(log_entry)
+            session.commit()
+
+        except Exception as e:
+            logging.error(f"Fallo al escribir en AccessLog: {e}", exc_info=False)
+            session.rollback()