iatoolkit 2.8.0__tar.gz → 2.9.0__tar.gz

{iatoolkit-2.8.0/src/iatoolkit.egg-info → iatoolkit-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iatoolkit
-Version: 2.8.0
+Version: 2.9.0
 Summary: IAToolkit
 Author: Fernando Libedinsky
 License-Expression: MIT

{iatoolkit-2.8.0 → iatoolkit-2.9.0}/src/iatoolkit/__init__.py

@@ -3,7 +3,7 @@
 #
 # IAToolkit is open source software.
 
-__version__ = "2.8.0"
+__version__ = "2.9.0"
 
 # Expose main classes and functions at the top level of the package
 

{iatoolkit-2.8.0 → iatoolkit-2.9.0}/src/iatoolkit/common/routes.py

@@ -39,6 +39,7 @@ def register_views(app):
     from iatoolkit.views.logout_api_view import LogoutApiView
     from iatoolkit.views.home_view import HomeView
     from iatoolkit.views.chat_view import ChatView
+    from iatoolkit.views.account_view import AccountView
     from iatoolkit.views.static_page_view import StaticPageView
     from iatoolkit.views.root_redirect_view import RootRedirectView
     from iatoolkit.views.users_api_view import UsersApiView
@@ -69,6 +70,9 @@ def register_views(app):
     # Chat Route (Direct Access)
     app.add_url_rule('/<company_short_name>/chat',
                      view_func=ChatView.as_view('chat'))
+    app.add_url_rule('/<company_short_name>/account',
+                     view_func=AccountView.as_view('account'),
+                     methods=['GET', 'POST'])
 
     # this endpoint is called when onboarding_shell finish the context load
     app.add_url_rule(

{iatoolkit-2.8.0 → iatoolkit-2.9.0}/src/iatoolkit/core.py

@@ -355,6 +355,7 @@ class IAToolkit:
         from iatoolkit.repositories.profile_repo import ProfileRepo
         from iatoolkit.repositories.llm_query_repo import LLMQueryRepo
         from iatoolkit.repositories.memory_repo import MemoryRepo
+        from iatoolkit.repositories.mcp_personal_access_token_repo import McpPersonalAccessTokenRepo
         from iatoolkit.repositories.sql_dataset_repo import SqlDatasetRepo
         from iatoolkit.repositories.sql_source_repo import SqlSourceRepo
         from iatoolkit.repositories.vs_repo import VSRepo
@@ -371,6 +372,7 @@ class IAToolkit:
         binder.bind(ProfileRepo, to=ProfileRepo)
         binder.bind(LLMQueryRepo, to=LLMQueryRepo)
         binder.bind(MemoryRepo, to=MemoryRepo)
+        binder.bind(McpPersonalAccessTokenRepo, to=McpPersonalAccessTokenRepo)
         binder.bind(SqlDatasetRepo, to=SqlDatasetRepo)
         binder.bind(SqlSourceRepo, to=SqlSourceRepo)
         binder.bind(VSRepo, to=VSRepo)
@@ -403,6 +405,7 @@ class IAToolkit:
         from iatoolkit.services.mail_service import MailService
         from iatoolkit.services.memory_compiler_service import MemoryCompilerService
         from iatoolkit.services.memory_service import MemoryService
+        from iatoolkit.services.mcp_personal_access_token_service import McpPersonalAccessTokenService
         from iatoolkit.services.memory_wiki_service import MemoryWikiService
         from iatoolkit.services.profile_service import ProfileService
         from iatoolkit.services.jwt_service import JWTService
@@ -446,6 +449,7 @@ class IAToolkit:
         binder.bind(MemoryWikiService, to=MemoryWikiService)
         binder.bind(MemoryCompilerService, to=MemoryCompilerService)
         binder.bind(MemoryService, to=MemoryService)
+        binder.bind(McpPersonalAccessTokenService, to=McpPersonalAccessTokenService)
         binder.bind(ProfileService, to=ProfileService)
         binder.bind(JWTService, to=JWTService)
         binder.bind(SqlDatasetService, to=SqlDatasetService)

{iatoolkit-2.8.0 → iatoolkit-2.9.0}/src/iatoolkit/locales/en.yaml

@@ -134,6 +134,59 @@ ui:
     prompts_available: "Available prompts"
     init_context: "Initializing the context ..."
 
+  account:
+    title: "My Account"
+    back_to_chat: "Back to chat"
+    menu_general: "General"
+    menu_mcp_tokens: "MCP Tokens"
+    general_title: "Personal settings"
+    general_description: "Manage your personal access, integrations, and the settings connected to your account."
+    general_tag: "Personal workspace"
+    general_profile_label: "Profile"
+    general_tokens_label: "Integrations"
+    general_tokens_title: "MCP access tokens"
+    general_tokens_description: "Create and manage bearer tokens for MCP clients that do not complete the OAuth flow directly."
+    general_tokens_action: "Open MCP tokens"
+    mcp_tokens_create_title: "Create MCP token"
+    mcp_tokens_create_description: "Generate a personal access token for MCP clients that require a bearer token."
+    mcp_tokens_list_title: "MCP access tokens"
+    mcp_tokens_count_suffix: "tokens"
+    mcp_tokens_empty: "You have not created any MCP tokens yet."
+    mcp_connection_title: "Connection snippets"
+    mcp_connection_description: "Use these snippets with MCP clients that connect through a fixed bearer token instead of completing OAuth in-app."
+    mcp_connection_tag: "Ready to paste"
+    mcp_connection_server_url: "Server URL"
+    mcp_connection_json_label: "JSON config"
+    mcp_connection_copy_url_button: "Copy URL"
+    mcp_connection_copy_json_button: "Copy JSON"
+    mcp_connection_url_copy_success: "Server URL copied."
+    mcp_connection_json_copy_success: "JSON config copied."
+    mcp_connection_copy_error: "Could not copy the MCP connection snippet."
+    mcp_connection_placeholder_help: "Replace <YOUR_MCP_TOKEN> with one of your active MCP personal access tokens."
+    mcp_token_name: "Token name"
+    mcp_token_name_placeholder: "Claude Desktop, PyCharm, Codex..."
+    mcp_token_expiry_days: "Expires in (days)"
+    mcp_token_created_at: "Created"
+    mcp_token_expires_at: "Expires"
+    mcp_token_last_used_at: "Last used"
+    mcp_token_status: "Status"
+    mcp_token_actions: "Actions"
+    mcp_token_status_active: "Active"
+    mcp_token_status_revoked: "Revoked"
+    mcp_token_status_expired: "Expired"
+    mcp_token_create_button: "Create token"
+    mcp_token_copy_button: "Copy"
+    mcp_token_copy_success: "Token copied."
+    mcp_token_copy_error: "Could not copy the token."
+    mcp_token_revoke_button: "Revoke"
+    mcp_token_created_title: "Copy this token now"
+    mcp_token_created_help: "For security reasons, this token is shown only once."
+    mcp_token_created_token_label: "Bearer token"
+    mcp_token_created_json_label: "Ready-to-paste JSON config"
+    mcp_token_created_flash: "MCP token created."
+    mcp_token_revoked_flash: "MCP token revoked."
+    mcp_token_unknown_action: "Unknown account action."
+
   memory:
     title: "Memory"
     capture_title: "Save something"
@@ -1420,8 +1473,12 @@ errors:
     authentication_required: "Authentication required. No session cookie or API Key provided."
     invalid_api_key: "Invalid or inactive API Key."
     api_key_name_required: "api_key_name parameter is required."
-
     no_user_identifier_api: "No user_identifier provided for API call."
+    mcp_pat_name_required: "Token name is required."
+    mcp_pat_name_exists: "A token with that name already exists."
+    mcp_pat_expiry_invalid: "Invalid expiration value."
+    mcp_pat_invalid: "Invalid, expired, or revoked MCP token."
+    mcp_pat_not_found: "MCP token not found."
     no_company_permissions: "Do not have permissions to admin this company."
   templates:
     company_not_found: "Company not found."

{iatoolkit-2.8.0 → iatoolkit-2.9.0}/src/iatoolkit/locales/es.yaml

@@ -135,6 +135,59 @@ ui:
     prompts_available: "Prompts disponibles"
     init_context: "Inicializando el contexto de la IA ..."
 
+  account:
+    title: "Mi cuenta"
+    back_to_chat: "Volver al chat"
+    menu_general: "General"
+    menu_mcp_tokens: "Tokens MCP"
+    general_title: "Configuración personal"
+    general_description: "Administra tu acceso personal, tus integraciones y la configuración asociada a tu cuenta."
+    general_tag: "Espacio personal"
+    general_profile_label: "Perfil"
+    general_tokens_label: "Integraciones"
+    general_tokens_title: "Tokens de acceso MCP"
+    general_tokens_description: "Crea y administra bearer tokens para clientes MCP que no completan el flujo OAuth directamente."
+    general_tokens_action: "Abrir tokens MCP"
+    mcp_tokens_create_title: "Crear token MCP"
+    mcp_tokens_create_description: "Genera un token de acceso personal para clientes MCP que requieren un bearer token."
+    mcp_tokens_list_title: "Tokens de acceso MCP"
+    mcp_tokens_count_suffix: "tokens"
+    mcp_tokens_empty: "Todavía no has creado tokens MCP."
+    mcp_connection_title: "Snippets de conexión"
+    mcp_connection_description: "Usa estos snippets con clientes MCP que se conectan con un bearer token fijo en vez de completar OAuth dentro de la app."
+    mcp_connection_tag: "Listo para pegar"
+    mcp_connection_server_url: "URL del servidor"
+    mcp_connection_json_label: "Configuración JSON"
+    mcp_connection_copy_url_button: "Copiar URL"
+    mcp_connection_copy_json_button: "Copiar JSON"
+    mcp_connection_url_copy_success: "URL del servidor copiada."
+    mcp_connection_json_copy_success: "Configuración JSON copiada."
+    mcp_connection_copy_error: "No se pudo copiar el snippet de conexión MCP."
+    mcp_connection_placeholder_help: "Reemplaza <YOUR_MCP_TOKEN> por uno de tus tokens MCP activos."
+    mcp_token_name: "Nombre del token"
+    mcp_token_name_placeholder: "Claude Desktop, PyCharm, Codex..."
+    mcp_token_expiry_days: "Expira en (días)"
+    mcp_token_created_at: "Creado"
+    mcp_token_expires_at: "Expira"
+    mcp_token_last_used_at: "Último uso"
+    mcp_token_status: "Estado"
+    mcp_token_actions: "Acciones"
+    mcp_token_status_active: "Activo"
+    mcp_token_status_revoked: "Revocado"
+    mcp_token_status_expired: "Expirado"
+    mcp_token_create_button: "Crear token"
+    mcp_token_copy_button: "Copiar"
+    mcp_token_copy_success: "Token copiado."
+    mcp_token_copy_error: "No se pudo copiar el token."
+    mcp_token_revoke_button: "Revocar"
+    mcp_token_created_title: "Copia este token ahora"
+    mcp_token_created_help: "Por seguridad, este token se muestra solo una vez."
+    mcp_token_created_token_label: "Bearer token"
+    mcp_token_created_json_label: "Configuración JSON lista para pegar"
+    mcp_token_created_flash: "Token MCP creado."
+    mcp_token_revoked_flash: "Token MCP revocado."
+    mcp_token_unknown_action: "Acción de cuenta desconocida."
+
   memory:
     title: "Memoria"
     capture_title: "Guardar algo"
@@ -1423,6 +1476,11 @@ errors:
     no_user_identifier_api: "No se proporcionó user_identifier para la llamada a la API."
     no_company_permissions: "No tiene permisos para administrar esta empresa."
     api_key_name_required: "el parametro api_key_name es requerido."
+    mcp_pat_name_required: "El nombre del token es obligatorio."
+    mcp_pat_name_exists: "Ya existe un token con ese nombre."
+    mcp_pat_expiry_invalid: "El valor de expiración es inválido."
+    mcp_pat_invalid: "Token MCP inválido, expirado o revocado."
+    mcp_pat_not_found: "Token MCP no encontrado."
 
   templates:
     company_not_found: "Empresa no encontrada."

iatoolkit-2.9.0/src/iatoolkit/repositories/mcp_personal_access_token_repo.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from injector import inject
+
+from iatoolkit.repositories.database_manager import DatabaseManager
+from iatoolkit.repositories.models import McpPersonalAccessToken
+
+
+class McpPersonalAccessTokenRepo:
+    @inject
+    def __init__(self, db_manager: DatabaseManager):
+        self.db_manager = db_manager
+        self.session = db_manager.get_session()
+
+    def create_token(self, token: McpPersonalAccessToken) -> McpPersonalAccessToken:
+        self.session.add(token)
+        self.session.commit()
+        return token
+
+    def save_token(self, token: McpPersonalAccessToken) -> McpPersonalAccessToken:
+        self.session.add(token)
+        self.session.commit()
+        return token
+
+    def rollback(self) -> None:
+        self.session.rollback()
+
+    def list_tokens_for_user(self, company_id: int, user_identifier: str) -> list[McpPersonalAccessToken]:
+        return (
+            self.session.query(McpPersonalAccessToken)
+            .filter_by(company_id=company_id, user_identifier=user_identifier)
+            .order_by(McpPersonalAccessToken.created_at.desc())
+            .all()
+        )
+
+    def get_token_by_id(self, company_id: int, user_identifier: str, token_id: int) -> McpPersonalAccessToken | None:
+        return (
+            self.session.query(McpPersonalAccessToken)
+            .filter_by(company_id=company_id, user_identifier=user_identifier, id=token_id)
+            .first()
+        )
+
+    def get_token_by_name(self, company_id: int, user_identifier: str, name: str) -> McpPersonalAccessToken | None:
+        return (
+            self.session.query(McpPersonalAccessToken)
+            .filter_by(company_id=company_id, user_identifier=user_identifier, name=name)
+            .first()
+        )
+
+    def get_active_token_by_hash(self, company_id: int, token_hash: str) -> McpPersonalAccessToken | None:
+        now = datetime.now()
+        return (
+            self.session.query(McpPersonalAccessToken)
+            .filter(
+                McpPersonalAccessToken.company_id == company_id,
+                McpPersonalAccessToken.token_hash == token_hash,
+                McpPersonalAccessToken.revoked_at.is_(None),
+                McpPersonalAccessToken.expires_at > now,
+            )
+            .first()
+        )

{iatoolkit-2.8.0 → iatoolkit-2.9.0}/src/iatoolkit/repositories/models.py

@@ -153,6 +153,11 @@ class Company(Base):
         back_populates="company",
         cascade="all, delete-orphan",
     )
+    mcp_personal_access_tokens = relationship(
+        "McpPersonalAccessToken",
+        back_populates="company",
+        cascade="all, delete-orphan",
+    )
     memory_items = relationship(
         "MemoryItem",
         back_populates="company",
@@ -698,6 +703,29 @@ class SqlDataset(Base):
         return {column.key: getattr(self, column.key) for column in class_mapper(self.__class__).columns}
 
 
+class McpPersonalAccessToken(Base):
+    __tablename__ = "iat_mcp_personal_access_tokens"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    company_id = Column(Integer, ForeignKey(f"{ORM_SCHEMA}.iat_companies.id", ondelete="CASCADE"), nullable=False, index=True)
+    user_identifier = Column(String, nullable=False, index=True)
+    name = Column(String, nullable=False)
+    token_hash = Column(String(64), nullable=False, unique=True, index=True)
+    created_at = Column(DateTime, default=datetime.now, nullable=False)
+    expires_at = Column(DateTime, nullable=False)
+    revoked_at = Column(DateTime, nullable=True)
+    last_used_at = Column(DateTime, nullable=True)
+
+    __table_args__ = (
+        UniqueConstraint("company_id", "user_identifier", "name", name="uix_mcp_pat_company_user_name"),
+    )
+
+    company = relationship("Company", back_populates="mcp_personal_access_tokens")
+
+    def to_dict(self):
+        return {column.key: getattr(self, column.key) for column in class_mapper(self.__class__).columns}
+
+
 class AccessLog(Base):
     # Modelo ORM para registrar cada intento de acceso a la plataforma.
     __tablename__ = 'iat_access_log'

{iatoolkit-2.8.0 → iatoolkit-2.9.0}/src/iatoolkit/services/knowledge_base_service.py

@@ -24,6 +24,7 @@ import os
 from typing import List, Optional, Union
 from datetime import datetime
 from injector import inject
+import mimetypes
 
 
 class KnowledgeBaseService:
@@ -661,6 +662,71 @@ class KnowledgeBaseService:
         )
         return int(query.order_by(None).count() or 0)
 
+    def get_document_descriptor(
+        self,
+        company_short_name: str,
+        document_id: int,
+        collection_name: str | None = None,
+    ) -> dict:
+        """
+        Resolves a document descriptor suitable for MCP/API download workflows.
+
+        Validates tenant ownership and, when provided, that the document belongs
+        to the requested collection.
+        """
+        if not company_short_name or not document_id:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_PARAMETER,
+                "company_short_name and document_id are required.",
+            )
+
+        document = self.document_repo.get_by_id(document_id)
+        if not document:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.DOCUMENT_NOT_FOUND,
+                f"Document '{document_id}' not found.",
+            )
+
+        document_company_short_name = str(getattr(getattr(document, "company", None), "short_name", "") or "").strip()
+        if document_company_short_name != company_short_name:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_OPERATION,
+                f"Document '{document_id}' does not belong to company '{company_short_name}'.",
+            )
+
+        normalized_collection_name = str(collection_name or "").strip().lower() or None
+        document_collection_name = str(
+            getattr(getattr(document, "collection_type", None), "name", "") or ""
+        ).strip().lower() or None
+        if normalized_collection_name and document_collection_name != normalized_collection_name:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.INVALID_OPERATION,
+                f"Document '{document_id}' does not belong to collection '{collection_name}'.",
+            )
+
+        mime_type, _ = mimetypes.guess_type(str(document.filename or "").strip())
+        download_url = None
+        content_available = bool(document.storage_key)
+        if content_available:
+            download_url = self.storage_service.generate_presigned_url(
+                company_short_name,
+                document.storage_key,
+            )
+
+        return {
+            "document_id": document.id,
+            "company_short_name": company_short_name,
+            "collection_name": document_collection_name,
+            "filename": document.filename,
+            "mime_type": mime_type or "application/octet-stream",
+            "storage_key": document.storage_key,
+            "download_url": download_url,
+            "content_available": content_available,
+            "status": document.status.value if hasattr(document.status, "value") else str(document.status),
+            "metadata": document.meta or {},
+            "created_at": document.created_at.isoformat() if document.created_at else None,
+        }
+
     def get_document_content(self, document_id: int) -> tuple[bytes, str]:
         """
         Retrieves the raw content of a document and its filename.

iatoolkit-2.9.0/src/iatoolkit/services/mcp_personal_access_token_service.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import hashlib
+import secrets
+from datetime import datetime, timedelta
+
+from injector import inject
+from sqlalchemy.exc import IntegrityError
+
+from iatoolkit.repositories.mcp_personal_access_token_repo import McpPersonalAccessTokenRepo
+from iatoolkit.repositories.models import McpPersonalAccessToken
+from iatoolkit.repositories.profile_repo import ProfileRepo
+from iatoolkit.services.i18n_service import I18nService
+
+
+class McpPersonalAccessTokenService:
+    TOKEN_PREFIX = "iatmcp_"
+    DEFAULT_EXPIRY_DAYS = 30
+    MAX_EXPIRY_DAYS = 365
+
+    @inject
+    def __init__(
+        self,
+        i18n_service: I18nService,
+        profile_repo: ProfileRepo,
+        token_repo: McpPersonalAccessTokenRepo,
+    ):
+        self.i18n_service = i18n_service
+        self.profile_repo = profile_repo
+        self.token_repo = token_repo
+
+    def list_tokens(self, company_short_name: str, user_identifier: str) -> dict:
+        company, error = self._get_company(company_short_name)
+        if error:
+            return error
+
+        tokens = self.token_repo.list_tokens_for_user(company.id, user_identifier)
+        return {"data": [self._token_to_dict(item) for item in tokens]}
+
+    def create_token(
+        self,
+        company_short_name: str,
+        user_identifier: str,
+        *,
+        name: str,
+        expires_in_days: int | None = None,
+    ) -> dict:
+        company, error = self._get_company(company_short_name)
+        if error:
+            return error
+
+        normalized_name = str(name or "").strip()
+        if not normalized_name:
+            return {"error": self.i18n_service.t("errors.auth.mcp_pat_name_required"), "status_code": 400}
+
+        expiry_days = self._normalize_expiry_days(expires_in_days)
+        if expiry_days is None:
+            return {"error": self.i18n_service.t("errors.auth.mcp_pat_expiry_invalid"), "status_code": 400}
+
+        existing = self.token_repo.get_token_by_name(company.id, user_identifier, normalized_name)
+        if existing and existing.revoked_at is None and existing.expires_at > datetime.now():
+            return {"error": self.i18n_service.t("errors.auth.mcp_pat_name_exists"), "status_code": 409}
+
+        raw_token = self._generate_raw_token()
+        expires_at = datetime.now() + timedelta(days=expiry_days)
+        try:
+            if existing:
+                existing.token_hash = self._hash_token(raw_token)
+                existing.created_at = datetime.now()
+                existing.expires_at = expires_at
+                existing.revoked_at = None
+                existing.last_used_at = None
+                created = self.token_repo.save_token(existing)
+            else:
+                token = McpPersonalAccessToken(
+                    company_id=company.id,
+                    user_identifier=user_identifier,
+                    name=normalized_name,
+                    token_hash=self._hash_token(raw_token),
+                    expires_at=expires_at,
+                )
+                created = self.token_repo.create_token(token)
+        except IntegrityError:
+            self.token_repo.rollback()
+            return {"error": self.i18n_service.t("errors.auth.mcp_pat_name_exists"), "status_code": 409}
+        payload = self._token_to_dict(created)
+        payload["token"] = raw_token
+        return {"data": payload}
+
+    def revoke_token(self, company_short_name: str, user_identifier: str, token_id: int) -> dict:
+        company, error = self._get_company(company_short_name)
+        if error:
+            return error
+
+        token = self.token_repo.get_token_by_id(company.id, user_identifier, token_id)
+        if not token:
+            return {"error": self.i18n_service.t("errors.auth.mcp_pat_not_found"), "status_code": 404}
+
+        if token.revoked_at is None:
+            token.revoked_at = datetime.now()
+            self.token_repo.save_token(token)
+
+        return {"data": self._token_to_dict(token)}
+
+    def authenticate_token(self, company_short_name: str, raw_token: str) -> dict:
+        company, error = self._get_company(company_short_name)
+        if error:
+            return error
+
+        normalized_token = str(raw_token or "").strip()
+        if not normalized_token:
+            return {"error": self.i18n_service.t("errors.auth.mcp_pat_invalid"), "status_code": 401}
+
+        token_hash = self._hash_token(normalized_token)
+        token = self.token_repo.get_active_token_by_hash(company.id, token_hash)
+        if not token:
+            return {"error": self.i18n_service.t("errors.auth.mcp_pat_invalid"), "status_code": 401}
+
+        token.last_used_at = datetime.now()
+        self.token_repo.save_token(token)
+        return {
+            "success": True,
+            "company_short_name": company.short_name,
+            "user_identifier": token.user_identifier,
+            "token_id": token.id,
+        }
+
+    def _get_company(self, company_short_name: str):
+        company = self.profile_repo.get_company_by_short_name(company_short_name)
+        if not company:
+            return None, {
+                "error": self.i18n_service.t("errors.company_not_found", company_short_name=company_short_name),
+                "status_code": 404,
+            }
+        return company, None
+
+    def _token_to_dict(self, token: McpPersonalAccessToken) -> dict:
+        return {
+            "id": token.id,
+            "name": token.name,
+            "user_identifier": token.user_identifier,
+            "created_at": token.created_at.isoformat() if token.created_at else None,
+            "expires_at": token.expires_at.isoformat() if token.expires_at else None,
+            "revoked_at": token.revoked_at.isoformat() if token.revoked_at else None,
+            "last_used_at": token.last_used_at.isoformat() if token.last_used_at else None,
+            "is_active": token.revoked_at is None and token.expires_at > datetime.now(),
+        }
+
+    def _normalize_expiry_days(self, raw_value: int | None) -> int | None:
+        if raw_value in (None, ""):
+            return self.DEFAULT_EXPIRY_DAYS
+        try:
+            expiry_days = int(raw_value)
+        except (TypeError, ValueError):
+            return None
+        if expiry_days <= 0 or expiry_days > self.MAX_EXPIRY_DAYS:
+            return None
+        return expiry_days
+
+    @classmethod
+    def _hash_token(cls, raw_token: str) -> str:
+        return hashlib.sha256(str(raw_token or "").encode("utf-8")).hexdigest()
+
+    @classmethod
+    def _generate_raw_token(cls) -> str:
+        return f"{cls.TOKEN_PREFIX}{secrets.token_urlsafe(32)}"