Merge pull request #109 from ScilifelabDataCentre/altcha-form-validation

SQ-927: Add Captcha validation to frontend forms

Author: RMCrean

docker/divbase_compose.yaml

@@ -195,6 +195,7 @@ services:
     - ASYNC_DATABASE_URL=postgresql+asyncpg://divbase_user:badpassword@postgres:5432/divbase_db 
     - SYNC_DATABASE_URL=postgresql+psycopg2://divbase_user:badpassword@postgres:5432/divbase_db # Needed for lifespan event to check migrations are at HEAD.
     - JWT_SECRET_KEY=a-string-secret-at-least-256-bits-long
+    - ALTCHA_HMAC_SECRET=a-string-secret-at-least-256-bits-long
     - FIRST_ADMIN_EMAIL=admin@divbase.com
     - FIRST_ADMIN_PASSWORD=badpassword
     - S3_ENDPOINT_URL=http://host.docker.internal:9000

packages/divbase-api/pyproject.toml

@@ -6,7 +6,7 @@ requires-python = ">=3.12"
 dependencies = [
     "fastapi[standard]==0.138.0",
     "uvicorn==0.49.0",
-    "asyncpg==0.31.0", 
+    "asyncpg==0.31.0",
     "pyjwt==2.13.0",
     "pwdlib[argon2]==0.3.0",
     "starlette-admin==0.16.1",
@@ -19,7 +19,8 @@ dependencies = [
     "prometheus-client==0.25.0",
     "psutil==7.2.2",
     "boto3==1.43.34",
-    "structlog>=26.1.0",    
+    "structlog==26.1.0",
+    "altcha==2.0.2",
     "divbase-lib", # always uses version in repo, handled by uv
 ]
 

packages/divbase-api/src/divbase_api/api_config.py

@@ -29,13 +29,20 @@ class GeneralSettings:
     log_to_file: bool = os.getenv("LOG_TO_FILE", "0") == "1"
     first_admin_email: str = os.getenv("FIRST_ADMIN_EMAIL", "NOT_SET")
     first_admin_password: SecretStr = SecretStr(os.getenv("FIRST_ADMIN_PASSWORD", "NOT_SET"))
+    altcha_hmac_secret: SecretStr = SecretStr(os.getenv("ALTCHA_HMAC_SECRET", "NOT_SET"))
 
     # versions before this are denied access to the API, until the user has upgraded
     minimum_cli_version: str = os.getenv("MINIMUM_CLI_VERSION", "0.1.0")
     # Used in deciding if to give the user an announcement on login that a new version of the CLI is available.
     # Whilst we are keeping version numbers identical across each component of divbase, this does not need to be manually set.
     latest_cli_version: str = lib_version
 
+    def __post_init__(self):
+        if self.frontend_base_url.endswith("/"):
+            self.frontend_base_url = self.frontend_base_url[:-1]
+        if self.mkdocs_site_url.endswith("/"):
+            self.mkdocs_site_url = self.mkdocs_site_url[:-1]
+
 
 @dataclass
 class DBSettings:
@@ -148,6 +155,7 @@ def validate_api_settings(self) -> None:
             "FRONTEND_BASE_URL": self.general.frontend_base_url,
             "MKDOCS_SITE_URL": self.general.mkdocs_site_url,
             "USER_SUPPORT_EMAIL": self.general.user_support_email,
+            "ALTCHA_HMAC_SECRET": self.general.altcha_hmac_secret,
             "ASYNC_DATABASE_URL": self.database.url,
             "SYNC_DATABASE_URL": self.database.sync_url,
             "JWT_SECRET_KEY": self.jwt.secret_key,
@@ -158,6 +166,9 @@ def validate_api_settings(self) -> None:
             "S3_SERVICE_ACCOUNT_SECRET_KEY": self.s3.secret_key,
         }
         for setting_name, setting in required_fields.items():
+            if setting_name == "ALTCHA_HMAC_SECRET" and self.general.environment == "test":
+                # we do not run Captcha checks with ALTCHA in e2e tests.
+                continue
             if isinstance(setting, str) and setting == "NOT_SET":
                 raise ValueError(f"A required environment variable was not set: {setting_name=}")
             if isinstance(setting, SecretStr):

packages/divbase-api/src/divbase_api/crud/auth.py

@@ -1,13 +1,28 @@
 """
 Authentication-related CRUD operations.
+
+Covers:
+- email+password validation
+- JWT access and refresh token creation and validation
+- various user validation helpers (e.g. is user account valid).
+- Altcha captcha generation and verification
+
+NOTE: For Altcha captcha generation and verification, we are using the V1 API,
+consistent with the Django implementation https://github.com/aboutcode-org/django-altcha/
 """
 
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 
 import structlog
+from altcha import (
+    ChallengeOptionsV1,  # pyright: ignore[reportPrivateImportUsage]
+    create_challenge_v1,  # pyright: ignore[reportPrivateImportUsage]
+    verify_solution_v1,  # pyright: ignore[reportPrivateImportUsage]
+)
 from fastapi import Response
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from divbase_api.api_config import api_settings
 from divbase_api.crud.revoked_tokens import token_is_revoked
 from divbase_api.crud.users import get_user_by_email, get_user_by_id, get_user_by_id_or_raise
 from divbase_api.exceptions import AuthenticationError
@@ -17,6 +32,9 @@
 
 logger = structlog.get_logger(__name__)
 
+# Altcha (Captcha for e.g. registration + password reset) is disabled in test environments
+ALTCHA_ENABLED = api_settings.general.environment != "test"
+
 
 async def authenticate_user(db: AsyncSession, email: str, password: str) -> UserDB:
     """
@@ -38,8 +56,9 @@ async def authenticate_user(db: AsyncSession, email: str, password: str) -> User
         raise AuthenticationError(message=generic_error_msg)
 
     if not user.email_verified:
+        verify_url = f"{api_settings.general.frontend_base_url}/resend-email-verification"
         raise AuthenticationError(
-            message="Email address not verified, check your inbox or visit the DivBase website to resend a new verification email."
+            message=f"Email address not verified, check your inbox or visit {verify_url} to get a new verification email."
         )
 
     return user
@@ -130,3 +149,39 @@ def delete_auth_cookies(response: Response) -> Response:
     response.delete_cookie(TokenType.ACCESS.value)
     response.delete_cookie(TokenType.REFRESH.value)
     return response
+
+
+def generate_altcha_challenge() -> dict:
+    """Generate a new Altcha captcha challenge."""
+    expires = datetime.now(tz=timezone.utc) + timedelta(minutes=1)
+    options = ChallengeOptionsV1(
+        algorithm="SHA-256",
+        hmac_key=api_settings.general.altcha_hmac_secret.get_secret_value(),
+        expires=expires,
+    )
+    challenge = create_challenge_v1(options)
+    return challenge.to_dict()
+
+
+def verify_altcha_solution(altcha: str | None, email: str) -> bool:
+    """
+    Verify the Altcha captcha solution. Returns True for a valid solution.
+    Validation skipped if in test environment (to avoid having to deal with Altcha in e2e playwright tests).
+    """
+    if not ALTCHA_ENABLED:
+        logger.info("Skipping Altcha verification as in test mode.")
+        return True
+
+    if not altcha:
+        logger.warning("Altcha verification failed: no solution provided.")
+        return False
+
+    verified, error = verify_solution_v1(
+        payload=altcha,
+        hmac_key=api_settings.general.altcha_hmac_secret.get_secret_value(),
+        check_expires=True,
+    )
+    if not verified:
+        logger.warning(f"Altcha verification failed for email {email} with error message: {error}")
+        return False
+    return True