Add audit logs

.gitignore

@@ -36,3 +36,6 @@ docker-compose.local.yml
 # SSO
 *.pem
 *.crt
+
+# Local Claude Code skills
+.claude/commands/

deployment/community/.env.template

@@ -66,6 +66,9 @@ SECURITY_EMAIL_SALT=fixme
 #SECURITY_PASSWORD_SALT=NODEFAULT
 SECURITY_PASSWORD_SALT=fixme
 
+#SECURITY_UNLOCK_SALT=NODEFAULT
+SECURITY_UNLOCK_SALT=fixme
+
 #WTF_CSRF_ENABLED=True
 
 #WTF_CSRF_TIME_LIMIT=3600 * 24  # in seconds
@@ -109,6 +112,9 @@ LOCAL_PROJECTS=/data
 
 #BLACKLIST='.mergin/, .DS_Store, .directory'  # cast=Csv()
 
+# extra file extensions to permit beyond the default block-list, e.g. '.py, .sh'
+#UPLOAD_EXTENSIONS_WHITELIST=
+
 #FILE_EXPIRATION=48 * 3600  # for clean up of old files where diffs were applied, in seconds
 
 #LOCKFILE_EXPIRATION=300  # in seconds

deployment/enterprise/.env.template

@@ -71,6 +71,9 @@ SECURITY_EMAIL_SALT=fixme
 #SECURITY_PASSWORD_SALT=NODEFAULT
 SECURITY_PASSWORD_SALT=fixme
 
+#SECURITY_UNLOCK_SALT=NODEFAULT
+SECURITY_UNLOCK_SALT=fixme
+
 #WTF_CSRF_ENABLED=True
 
 #WTF_CSRF_TIME_LIMIT=3600 * 24  # in seconds

server/.test.env

@@ -23,6 +23,7 @@ GEODIFF_WORKING_DIR=/tmp/geodiff
 SECURITY_BEARER_SALT='bearer'
 SECURITY_EMAIL_SALT='email'
 SECURITY_PASSWORD_SALT='password'
+SECURITY_UNLOCK_SALT='unlock'
 DIAGNOSTIC_LOGS_DIR=/tmp/diagnostic_logs
 GEVENT_WORKER=0
 OTEL_ENABLED=0

server/mergin/.env

@@ -4,5 +4,6 @@ SECRET_KEY='top-secret'
 SECURITY_BEARER_SALT='top-secret'
 SECURITY_EMAIL_SALT='top-secret'
 SECURITY_PASSWORD_SALT='top-secret'
+SECURITY_UNLOCK_SALT='top-secret'
 MAIL_DEFAULT_SENDER=''
 FLASK_DEBUG=0

server/mergin/app.py

@@ -154,6 +154,7 @@ def create_app(public_keys: List[str] = None) -> Flask:
     """Factory function to create Flask app instance"""
     from itsdangerous import BadTimeSignature, BadSignature
 
+    from .audit import register as register_audit
     from .auth import auth_required, decode_token, register as register_auth
     from .auth.models import User
     from .sync.app import register as register_sync
@@ -180,6 +181,9 @@ def create_app(public_keys: List[str] = None) -> Flask:
     csrf.init_app(app.app)
     login_manager.init_app(app.app)
 
+    # register audit module
+    register_audit(app.app)
+
     # register auth blueprint
     register_auth(app.app)
 
@@ -188,7 +192,9 @@ def create_app(public_keys: List[str] = None) -> Flask:
     # adjust login manager
     @login_manager.user_loader
     def load_user(user_id):  # pylint: disable=W0613,W0612
-        return User.query.get(user_id)
+        user = User.query.get(user_id)
+        if user and user.active:
+            return user
 
     @login_manager.header_loader
     def load_user_from_header(header_val):  # pylint: disable=W0613,W0612

server/mergin/audit/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (C) Lutra Consulting Limited
+#
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-MerginMaps-Commercial
+
+from .app import emit, register

server/mergin/audit/app.py

@@ -0,0 +1,51 @@
+# Copyright (C) Lutra Consulting Limited
+#
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-MerginMaps-Commercial
+
+import datetime
+
+from flask import Flask, current_app
+
+from .events import AuditEvent, EventType
+from .sinks import NullSink
+
+
+def register(app: Flask) -> None:
+    """Wire the audit module into a Flask app.
+
+    Stores the sink in app.extensions["audit"] so emit() has one consistent lookup path.
+    """
+    app.extensions["audit"] = {"sink": NullSink()}
+
+
+def emit(
+    event_type: EventType,
+    actor_id=None,
+    actor_email=None,
+    actor_ua=None,
+    actor_device=None,
+    actor_ip=None,
+    user_id=None,
+    project_id=None,
+    workspace_id=None,
+    **metadata,
+) -> None:
+    """Emit one audit event to the configured sink.
+
+    Set at least one of user_id, project_id, workspace_id to identify the target.
+    Extra keyword arguments become the metadata dict.
+    """
+    event = AuditEvent(
+        event_type=event_type,
+        actor_id=actor_id,
+        actor_email=actor_email,
+        actor_ua=actor_ua,
+        actor_device=actor_device,
+        actor_ip=actor_ip,
+        happened_at=datetime.datetime.utcnow(),
+        user_id=user_id,
+        project_id=project_id,
+        workspace_id=workspace_id,
+        metadata=metadata,
+    )
+    current_app.extensions["audit"]["sink"].write(event)

server/mergin/audit/events.py

@@ -0,0 +1,29 @@
+# Copyright (C) Lutra Consulting Limited
+#
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-MerginMaps-Commercial
+
+import datetime
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+# Noun.verb dot-notation string, e.g. "user.login.succeeded".
+# Each module defines its own str enum; the sink stores the raw string.
+EventType = str
+
+
+@dataclass(frozen=True)
+class AuditEvent:
+    event_type: EventType
+    actor_ip: Optional[str]
+    happened_at: datetime.datetime
+    actor_id: Optional[int]
+    actor_email: Optional[str]
+    actor_ua: Optional[str]
+    actor_device: Optional[str]  # X-Device-Id header; set by mobile/QGIS clients
+    user_id: Optional[int]  # set when the target is a user
+    project_id: Optional[uuid.UUID]  # set when the target is a project
+    workspace_id: Optional[
+        int
+    ]  # workspace the event belongs to; set for project and workspace events
+    metadata: Dict[str, Any] = field(default_factory=dict)

server/mergin/audit/listeners.py

@@ -0,0 +1,90 @@
+# Copyright (C) Lutra Consulting Limited
+#
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-MerginMaps-Commercial
+
+"""
+Utilities for writing SQLAlchemy-based audit listeners in any module.
+"""
+
+import logging
+
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.orm import ColumnProperty
+from flask import has_request_context, has_app_context, request, current_app
+from flask_login import current_user
+
+from ..utils import get_ip, get_user_agent, get_device_id
+from .app import emit
+
+logger = logging.getLogger(__name__)
+
+
+def request_context():
+    """Return the three request-derived actor kwargs: user_agent, device_id, ip.
+
+    Use **request_context() in explicit emit() calls so adding a new request
+    field only requires changing this one function.
+    """
+    if not has_request_context():
+        return dict(actor_ua=None, actor_device=None, actor_ip=None)
+    return dict(
+        actor_ua=get_user_agent(request),
+        actor_device=get_device_id(request),
+        actor_ip=get_ip(request),
+    )
+
+
+def actor_context():
+    """Return full actor kwargs for emit() drawn from the current request context.
+
+    Used by SQLAlchemy listeners where current_user is the actor.
+    """
+    actor_id = None
+    actor_email = None
+    if has_request_context() and hasattr(
+        current_app._get_current_object(), "login_manager"
+    ):
+        try:
+            if current_user.is_authenticated:
+                actor_id = current_user.id
+                actor_email = current_user.email
+        except Exception:
+            pass
+    return dict(actor_id=actor_id, actor_email=actor_email, **request_context())
+
+
+def field_changes(target, skip=frozenset()):
+    """Return flat old_<field>/new_<field> context for all changed non-skipped column fields.
+
+    Only column attributes are included — relationships are skipped because their
+    history entries are ORM instances, not JSON-serializable values.
+    """
+    mapper = sa_inspect(type(target))
+    ctx = {}
+    for attr in sa_inspect(target).attrs:
+        if attr.key in skip:
+            continue
+        if not isinstance(mapper.attrs[attr.key], ColumnProperty):
+            continue
+        hist = attr.history
+        if hist.has_changes():
+            old = hist.deleted[0] if hist.deleted else None
+            new = hist.added[0] if hist.added else None
+            if old != new:
+                ctx[f"old_{attr.key}"] = old
+                ctx[f"new_{attr.key}"] = new
+    return ctx
+
+
+def emit_safe(event_type, **kwargs):
+    """Emit without raising if outside app context or sink not yet configured.
+
+    Works both inside HTTP requests (actor context populated) and Celery tasks
+    (actor fields are None, indicating a system-initiated action).
+    """
+    if not has_app_context() or "audit" not in current_app.extensions:
+        return
+    try:
+        emit(event_type, **kwargs)
+    except Exception:
+        logger.warning("Failed to emit audit event %s", event_type, exc_info=True)

server/mergin/audit/sinks.py

@@ -0,0 +1,21 @@
+# Copyright (C) Lutra Consulting Limited
+#
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-MerginMaps-Commercial
+
+from abc import ABC, abstractmethod
+
+from .events import AuditEvent
+
+
+class AbstractSink(ABC):
+    """Interface all audit sinks must implement."""
+
+    @abstractmethod
+    def write(self, event: AuditEvent) -> None: ...
+
+
+class NullSink(AbstractSink):
+    """Default sink — discards all events."""
+
+    def write(self, event: AuditEvent) -> None:
+        pass

server/mergin/auth/api.yaml

@@ -360,6 +360,8 @@ paths:
           $ref: "#/components/responses/BadStatusResp"
         "401":
           $ref: "#/components/responses/UnauthorizedError"
+        "423":
+          $ref: "#/components/responses/LockedResp"
   /app/auth/logout:
     get:
       summary: Logout
@@ -470,6 +472,26 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFoundResp"
+  /app/auth/unlock-account/{token}:
+    post:
+      summary: Unlock account
+      description: Clear an active lockout for the user encoded in the token
+      operationId: mergin.auth.controller.unlock_account
+      parameters:
+        - name: token
+          in: path
+          description: User token for account unlock verification
+          required: true
+          schema:
+            type: string
+            example: InRlc3RAbHV0cmFjb25zdWx0aW5nLmNvLnVrIg.YN2KRg.Vj1LSzSvQx9DcNnQFgZ0baS7LPU
+      responses:
+        "200":
+          description: OK
+        "400":
+          $ref: "#/components/responses/BadStatusResp"
+        "404":
+          $ref: "#/components/responses/NotFoundResp"
   /app/auth/confirm-email/{token}:
     post:
       summary: Email verified
@@ -617,6 +639,8 @@ paths:
           $ref: "#/components/responses/NotFoundResp"
         "415":
           $ref: "#/components/responses/UnsupportedMediaType"
+        "423":
+          $ref: "#/components/responses/LockedResp"
       x-openapi-router-controller: mergin.auth.controller
   /app/admin/login:
     post:
@@ -646,6 +670,8 @@ paths:
           $ref: "#/components/responses/UnauthorizedError"
         "403":
           $ref: "#/components/responses/Forbidden"
+        "423":
+          $ref: "#/components/responses/LockedResp"
   /v2/users:
     post:
       tags:
@@ -718,6 +744,8 @@ components:
       description: Request could not be processed becuase of conflict in resources
     UnprocessableEntity:
       description: Request was correct and yet server could not process it
+    LockedResp:
+      description: Account is temporarily locked due to too many failed login attempts.
     NoContent:
       description: Success. No content returned.
   schemas: