Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(servers): add merged restore timeline

Juan Denisd060e77e998f
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index ed93e71d..0a4ee3cf 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -24,6 +24,7 @@ from app.services.agent_fleet_service import fleet_service
from app.services.discovery_service import discovery_service
from app.services import connection_string as connection_string_codec
from app.middleware.rbac import admin_required, developer_required, get_current_user
+from app.exceptions import ValidationError
# Default token lifetime when the caller doesn't specify one. 7 days is
@@ -532,6 +533,39 @@ def get_server(server_id):
return jsonify(result)
+@servers_bp.route('/<server_id>/timeline', methods=['GET'])
+@developer_required
+def get_server_timeline(server_id):
+ """Merge the server's accessible audit and checkpoint history."""
+ allowed = {'types', 'before', 'limit'}
+ unknown = set(request.args) - allowed
+ if unknown:
+ raise ValidationError(
+ 'Unknown query parameters',
+ details={'fields': sorted(unknown)},
+ )
+ for key in allowed:
+ if len(request.args.getlist(key)) > 1:
+ raise ValidationError(
+ f'{key} must be provided at most once',
+ details={'field': key},
+ )
+
+ from app.services.server_timeline_service import ServerTimelineService
+
+ page = ServerTimelineService.get_timeline(
+ get_current_user(),
+ server_id,
+ types=request.args.get('types'),
+ before=request.args.get('before'),
+ limit=request.args.get('limit'),
+ )
+ return jsonify({
+ 'events': page.events,
+ 'next_cursor': page.next_cursor,
+ }), 200
+
+
@servers_bp.route('/<server_id>', methods=['PUT'])
@developer_required
def update_server(server_id):
diff --git a/backend/app/services/server_timeline_service.py b/backend/app/services/server_timeline_service.py
new file mode 100644
index 00000000..35e100e7
--- /dev/null
+++ b/backend/app/services/server_timeline_service.py
@@ -0,0 +1,539 @@
+"""Authorization-aware read model for one server's activity timeline.
+
+The three source tables intentionally remain independent. This service owns
+their attribution, secret-safe projections, global ordering, and keyset cursor
+so the HTTP layer never reaches into ORM persistence.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from dataclasses import dataclass
+from datetime import datetime
+import json
+
+from sqlalchemy import and_, or_
+from sqlalchemy.orm import joinedload
+
+from app import db
+from app.exceptions import NotFoundError, PermissionDeniedError, ValidationError
+
+
+EVENT_AUDIT = 'audit'
+EVENT_RESTORE_POINT = 'restore_point'
+EVENT_DEPLOYMENT_SNAPSHOT = 'deployment_snapshot'
+EVENT_TYPES = frozenset({
+ EVENT_AUDIT,
+ EVENT_RESTORE_POINT,
+ EVENT_DEPLOYMENT_SNAPSHOT,
+})
+
+DEFAULT_LIMIT = 50
+MAX_LIMIT = 200
+_APP_SCOPE_TYPES = frozenset({'application', 'env'})
+
+# Higher ranks sort first when timestamps are equal. This is API state: the
+# cursor records the source name and resolves its stable rank from this table.
+_SOURCE_RANK = {
+ EVENT_AUDIT: 3,
+ EVENT_RESTORE_POINT: 2,
+ EVENT_DEPLOYMENT_SNAPSHOT: 1,
+}
+
+# AuditLog may contain request payloads, IPs, user agents, and provider data.
+# A server timeline is not the admin audit export, so expose only small fields
+# that help explain an event. Nested request payload/query objects never pass.
+_AUDIT_DETAIL_KEYS = frozenset({
+ 'action',
+ 'allow_agent_update_observed',
+ 'app_id',
+ 'app_name',
+ 'application_id',
+ 'code',
+ 'endpoint',
+ 'from',
+ 'kind',
+ 'label',
+ 'method',
+ 'pre_restore_point_id',
+ 'restore_point_id',
+ 'scope_id',
+ 'scope_type',
+ 'server_id',
+ 'service',
+ 'state',
+ 'status_code',
+ 'success',
+ 'to',
+ 'trigger',
+})
+
+
+class ServerTimelineError(ValidationError):
+ code = 'server_timeline_invalid'
+
+
+class ServerTimelineNotFoundError(NotFoundError):
+ code = 'server_timeline_server_not_found'
+
+
+@dataclass(frozen=True)
+class TimelineCursor:
+ created_at: datetime
+ source: str
+ source_id: int | str
+ server_id: str
+ types: frozenset[str]
+
+
+@dataclass(frozen=True)
+class TimelinePage:
+ events: list[dict]
+ next_cursor: str | None
+
+
+def _parse_limit(value) -> int:
+ if value in (None, ''):
+ return DEFAULT_LIMIT
+ try:
+ limit = int(value)
+ except (TypeError, ValueError) as exc:
+ raise ServerTimelineError('limit must be an integer') from exc
+ if limit < 1 or limit > MAX_LIMIT:
+ raise ServerTimelineError(
+ f'limit must be between 1 and {MAX_LIMIT}',
+ )
+ return limit
+
+
+def _parse_types(value) -> frozenset[str]:
+ if value in (None, ''):
+ return EVENT_TYPES
+ raw_values = value if isinstance(value, (list, tuple, set)) else str(value).split(',')
+ requested = frozenset(
+ str(item).strip() for item in raw_values if str(item).strip()
+ )
+ if not requested:
+ return EVENT_TYPES
+ unknown = requested - EVENT_TYPES
+ if unknown:
+ raise ServerTimelineError(
+ 'Unknown timeline event types',
+ details={
+ 'types': sorted(unknown),
+ 'allowed': sorted(EVENT_TYPES),
+ },
+ )
+ return requested
+
+
+def _native_cursor_id(source, value):
+ if source in {EVENT_AUDIT, EVENT_DEPLOYMENT_SNAPSHOT}:
+ try:
+ parsed = int(value)
+ except (TypeError, ValueError) as exc:
+ raise ValueError from exc
+ if parsed < 1:
+ raise ValueError
+ return parsed
+ if source == EVENT_RESTORE_POINT:
+ parsed = str(value or '')
+ if not parsed or len(parsed) > 128:
+ raise ValueError
+ return parsed
+ raise ValueError
+
+
+def encode_cursor(event, *, server_id, types) -> str:
+ payload = {
+ 'v': 1,
+ 'created_at': event['_created_at'].isoformat(timespec='microseconds'),
+ 'source': event['type'],
+ 'source_id': event['source_id'],
+ 'server_id': str(server_id),
+ 'types': sorted(types),
+ }
+ raw = json.dumps(payload, sort_keys=True, separators=(',', ':')).encode('utf-8')
+ return base64.urlsafe_b64encode(raw).rstrip(b'=').decode('ascii')
+
+
+def decode_cursor(value, *, server_id, types) -> TimelineCursor | None:
+ if value in (None, ''):
+ return None
+ try:
+ encoded = str(value).encode('ascii')
+ encoded += b'=' * (-len(encoded) % 4)
+ payload = json.loads(base64.b64decode(
+ encoded, altchars=b'-_', validate=True,
+ ).decode('utf-8'))
+ if not isinstance(payload, dict) or payload.get('v') != 1:
+ raise ValueError
+ if set(payload) != {
+ 'v', 'created_at', 'source', 'source_id', 'server_id', 'types',
+ }:
+ raise ValueError
+ if payload['server_id'] != str(server_id):
+ raise ValueError
+ cursor_types = frozenset(payload['types'])
+ if (
+ not isinstance(payload['types'], list)
+ or cursor_types != frozenset(types)
+ or not cursor_types <= EVENT_TYPES
+ ):
+ raise ValueError
+ source = payload['source']
+ if source not in EVENT_TYPES or source not in cursor_types:
+ raise ValueError
+ created_at = datetime.fromisoformat(payload['created_at'])
+ if created_at.tzinfo is not None:
+ # Stored timestamps are UTC-naive throughout these three models.
+ raise ValueError
+ source_id = _native_cursor_id(source, payload['source_id'])
+ return TimelineCursor(
+ created_at, source, source_id, str(server_id), cursor_types,
+ )
+ except (
+ binascii.Error,
+ json.JSONDecodeError,
+ UnicodeError,
+ ValueError,
+ TypeError,
+ ) as exc:
+ raise ServerTimelineError(
+ 'Invalid timeline cursor', code='invalid_cursor',
+ ) from exc
+
+
+def _require_developer(user):
+ if user is None:
+ raise PermissionDeniedError('Developer access required')
+ if not user.is_active:
+ raise PermissionDeniedError('Account is deactivated')
+ if not user.is_developer:
+ raise PermissionDeniedError('Developer access required')
+
+
+def _resolve_server(server_id):
+ from app.models.server import Server
+
+ server = db.session.get(Server, str(server_id))
+ if server is None:
+ raise ServerTimelineNotFoundError(f'Server {server_id} not found')
+ return server
+
+
+def _globally_accessible_app_ids(user):
+ from app.models.application import Application
+ from app.services.workspace_service import WorkspaceService
+
+ query = WorkspaceService.scope_query(
+ Application.query_active(), Application, user,
+ owner_attr='user_id', grant_resource_type='application',
+ )
+ return {
+ application_id
+ for application_id, in query.with_entities(Application.id).all()
+ }
+
+
+def _accessible_apps_on_server(server_id, user):
+ from app.models.application import Application
+ from app.services.workspace_service import WorkspaceService
+
+ query = WorkspaceService.scope_query(
+ Application.query_active().filter(Application.server_id == server_id),
+ Application,
+ user,
+ owner_attr='user_id',
+ grant_resource_type='application',
+ )
+ return {
+ row.id: row
+ for row in query.with_entities(
+ Application.id, Application.name, Application.server_id,
+ ).all()
+ }
+
+
+def _apply_seek(query, created_column, id_column, source, cursor):
+ if cursor is None:
+ return query
+ source_rank = _SOURCE_RANK[source]
+ cursor_rank = _SOURCE_RANK[cursor.source]
+ if source_rank < cursor_rank:
+ return query.filter(created_column <= cursor.created_at)
+ if source_rank > cursor_rank:
+ return query.filter(created_column < cursor.created_at)
+ return query.filter(or_(
+ created_column < cursor.created_at,
+ and_(
+ created_column == cursor.created_at,
+ id_column < cursor.source_id,
+ ),
+ ))
+
+
+def _base_event(source, source_id, created_at, *, action, actor_user_id=None):
+ return {
+ 'id': f'{source}:{source_id}',
+ 'type': source,
+ 'source_id': source_id,
+ 'created_at': created_at.isoformat(timespec='microseconds'),
+ 'action': action,
+ 'actor_user_id': actor_user_id,
+ '_created_at': created_at,
+ }
+
+
+def _safe_audit_details(details):
+ if not isinstance(details, dict):
+ return {}
+ result = {}
+ for key in sorted(_AUDIT_DETAIL_KEYS & set(details)):
+ value = details[key]
+ if value is None or isinstance(value, (bool, int, float)):
+ result[key] = value
+ elif isinstance(value, str):
+ result[key] = value[:500]
+ return result
+
+
+def _coerce_app_id(value):
+ try:
+ app_id = int(value)
+ except (TypeError, ValueError):
+ return None
+ return app_id if app_id > 0 else None
+
+
+def _audit_application_id(row, details):
+ if row.target_type in {'app', 'application'}:
+ return _coerce_app_id(row.target_id)
+ for key in ('application_id', 'app_id'):
+ app_id = _coerce_app_id(details.get(key))
+ if app_id is not None:
+ return app_id
+ if details.get('scope_type') in _APP_SCOPE_TYPES:
+ return _coerce_app_id(details.get('scope_id'))
+ return None
+
+
+def _audit_server_id(row, details):
+ if row.target_type == 'server' and row.target_id is not None:
+ return str(row.target_id)
+ direct = details.get('server_id')
+ if direct not in (None, ''):
+ return str(direct)
+ route_args = details.get('route_args')
+ if isinstance(route_args, dict):
+ routed = route_args.get('server_id')
+ if routed not in (None, ''):
+ return str(routed)
+ return None
+
+
+def _audit_belongs_to_server(
+ row, details, server_id, accessible_app_ids, current_apps):
+ app_id = _audit_application_id(row, details)
+ if app_id is not None:
+ if app_id not in accessible_app_ids:
+ return False
+ # A frozen server attribution preserves history after an app moves.
+ # Only older audit shapes with no server stamp derive from the app's
+ # current server association.
+ explicit_server_id = _audit_server_id(row, details)
+ if explicit_server_id is not None:
+ return explicit_server_id == server_id
+ return app_id in current_apps
+ return _audit_server_id(row, details) == server_id
+
+
+def _audit_events(
+ server_id, accessible_app_ids, current_apps, cursor, fetch_limit):
+ from app.models.audit_log import AuditLog
+
+ app_ids = tuple(accessible_app_ids)
+ candidates = [AuditLog.target_type.in_(('server', 'servers', 'restore_point'))]
+ if app_ids:
+ candidates.append(and_(
+ AuditLog.target_type.in_(('app', 'application')),
+ AuditLog.target_id.in_(app_ids),
+ ))
+ # Some explicit audits use a domain-specific target_type and put the UUID
+ # in details. The quoted value is only a candidate prefilter; attribution
+ # below parses JSON and requires exact server_id/route_args equality.
+ candidates.append(AuditLog.details.contains(f'"{server_id}"'))
+
+ query = AuditLog.query.options(joinedload(AuditLog.user)).filter(
+ AuditLog.created_at.isnot(None),
+ AuditLog.action != AuditLog.ACTION_RESTORE_POINT_CREATE,
+ or_(*candidates),
+ )
+ query = _apply_seek(
+ query, AuditLog.created_at, AuditLog.id, EVENT_AUDIT, cursor,
+ ).order_by(AuditLog.created_at.desc(), AuditLog.id.desc())
+
+ events = []
+ for row in query.yield_per(200):
+ details = row.get_details()
+ if not _audit_belongs_to_server(
+ row, details, server_id, accessible_app_ids, current_apps,
+ ):
+ continue
+ event = _base_event(
+ EVENT_AUDIT, row.id, row.created_at,
+ action=row.action, actor_user_id=row.user_id,
+ )
+ event.update({
+ 'actor_username': row.user.username if row.user else None,
+ 'target_type': row.target_type,
+ 'target_id': row.target_id,
+ 'details': _safe_audit_details(details),
+ })
+ events.append(event)
+ if len(events) >= fetch_limit:
+ break
+ return events
+
+
+def _restore_point_events(
+ server_id, accessible_app_ids, current_apps, cursor, fetch_limit):
+ from app.models.restore_point import RestorePoint
+
+ app_scope_ids = tuple(str(app_id) for app_id in accessible_app_ids)
+ current_scope_ids = tuple(str(app_id) for app_id in current_apps)
+ attributed = [and_(
+ RestorePoint.server_id == server_id,
+ RestorePoint.scope_type.notin_(_APP_SCOPE_TYPES),
+ )]
+ if app_scope_ids:
+ attributed.append(and_(
+ RestorePoint.server_id == server_id,
+ RestorePoint.scope_type.in_(_APP_SCOPE_TYPES),
+ RestorePoint.scope_id.in_(app_scope_ids),
+ ))
+ if current_scope_ids:
+ attributed.append(and_(
+ RestorePoint.server_id.is_(None),
+ RestorePoint.scope_type == 'env',
+ RestorePoint.scope_id.in_(current_scope_ids),
+ ))
+ query = RestorePoint.query.filter(
+ RestorePoint.created_at.isnot(None), or_(*attributed),
+ )
+ query = _apply_seek(
+ query, RestorePoint.created_at, RestorePoint.id,
+ EVENT_RESTORE_POINT, cursor,
+ ).order_by(RestorePoint.created_at.desc(), RestorePoint.id.desc())
+
+ events = []
+ for point in query.limit(fetch_limit).all():
+ event = _base_event(
+ EVENT_RESTORE_POINT, point.id, point.created_at,
+ action='restore_point.captured',
+ actor_user_id=point.actor_user_id,
+ )
+ event.update({
+ 'server_id': point.server_id or server_id,
+ 'scope_type': point.scope_type,
+ 'scope_id': point.scope_id,
+ 'trigger': point.trigger,
+ 'label': point.label,
+ 'keep': bool(point.keep),
+ 'coverage': point.get_coverage(),
+ })
+ events.append(event)
+ return events
+
+
+def _deployment_snapshot_events(accessible_apps, cursor, fetch_limit):
+ from app.models.deployment_snapshot import DeploymentSnapshot
+
+ app_ids = tuple(accessible_apps)
+ if not app_ids:
+ return []
+ query = DeploymentSnapshot.query.filter(
+ DeploymentSnapshot.application_id.in_(app_ids),
+ DeploymentSnapshot.created_at.isnot(None),
+ )
+ query = _apply_seek(
+ query, DeploymentSnapshot.created_at, DeploymentSnapshot.id,
+ EVENT_DEPLOYMENT_SNAPSHOT, cursor,
+ ).order_by(
+ DeploymentSnapshot.created_at.desc(), DeploymentSnapshot.id.desc(),
+ )
+
+ events = []
+ for snapshot in query.limit(fetch_limit).all():
+ application = accessible_apps[snapshot.application_id]
+ event = _base_event(
+ EVENT_DEPLOYMENT_SNAPSHOT, snapshot.id, snapshot.created_at,
+ action='deployment.snapshot', actor_user_id=None,
+ )
+ event.update({
+ 'application_id': snapshot.application_id,
+ 'application_name': application.name,
+ 'deployment_id': snapshot.deployment_id,
+ 'snapshot_hash': snapshot.snapshot_hash,
+ 'summary': snapshot.summary,
+ })
+ events.append(event)
+ return events
+
+
+def _event_sort_key(event):
+ return (
+ event['_created_at'],
+ _SOURCE_RANK[event['type']],
+ event['source_id'],
+ )
+
+
+def get_timeline(user, server_id, *, types=None, before=None, limit=None):
+ """Return one authorization-filtered keyset page, newest first."""
+ _require_developer(user)
+ server = _resolve_server(server_id)
+ requested_types = _parse_types(types)
+ page_limit = _parse_limit(limit)
+ cursor = decode_cursor(
+ before, server_id=server.id, types=requested_types,
+ )
+ accessible_app_ids = _globally_accessible_app_ids(user)
+ current_apps = _accessible_apps_on_server(server.id, user)
+ fetch_limit = page_limit + 1
+
+ events = []
+ if EVENT_AUDIT in requested_types:
+ events.extend(_audit_events(
+ server.id, accessible_app_ids, current_apps, cursor, fetch_limit,
+ ))
+ if EVENT_RESTORE_POINT in requested_types:
+ events.extend(_restore_point_events(
+ server.id, accessible_app_ids, current_apps, cursor, fetch_limit,
+ ))
+ if EVENT_DEPLOYMENT_SNAPSHOT in requested_types:
+ events.extend(_deployment_snapshot_events(
+ current_apps, cursor, fetch_limit,
+ ))
+
+ events.sort(key=_event_sort_key, reverse=True)
+ has_more = len(events) > page_limit
+ page_events = events[:page_limit]
+ next_cursor = (
+ encode_cursor(
+ page_events[-1], server_id=server.id, types=requested_types,
+ )
+ if has_more else None
+ )
+ for event in page_events:
+ event.pop('_created_at', None)
+ return TimelinePage(page_events, next_cursor)
+
+
+class ServerTimelineService:
+ """Facade for call sites that use the project's service-class convention."""
+
+ get_timeline = staticmethod(get_timeline)
+ encode_cursor = staticmethod(encode_cursor)
+ decode_cursor = staticmethod(decode_cursor)
diff --git a/backend/tests/test_server_timeline.py b/backend/tests/test_server_timeline.py
new file mode 100644
index 00000000..8d14cb4d
--- /dev/null
+++ b/backend/tests/test_server_timeline.py
@@ -0,0 +1,381 @@
+"""Plan 81 M4: server timeline merge, authorization, and cursor contracts."""
+
+import base64
+from datetime import datetime, timedelta
+import json
+
+from factories import headers_for, make_application, make_server, make_user
+
+
+def _restore_point(db, *, server_id, scope_type, scope_id, created_at,
+ actor_user_id=None, label=None):
+ from app.models.restore_point import RestorePoint
+
+ point = RestorePoint(
+ server_id=server_id,
+ scope_type=scope_type,
+ scope_id=str(scope_id),
+ trigger='manual',
+ label=label,
+ payload_hash='a' * 64,
+ payload_json='{}',
+ coverage_json='["outside"]',
+ actor_user_id=actor_user_id,
+ keep=True,
+ created_at=created_at,
+ updated_at=created_at,
+ )
+ db.session.add(point)
+ db.session.commit()
+ return point
+
+
+def _snapshot(db, application, created_at, *, summary='config changed'):
+ from app.models.deployment_snapshot import DeploymentSnapshot
+
+ snapshot = DeploymentSnapshot(
+ application_id=application.id,
+ snapshot_hash='b' * 64,
+ config_json='{}',
+ summary=summary,
+ created_at=created_at,
+ )
+ db.session.add(snapshot)
+ db.session.commit()
+ return snapshot
+
+
+def _audit(db, *, action, created_at, target_type=None, target_id=None,
+ details=None, user_id=None, ip_address='203.0.113.1',
+ user_agent='secret-agent'):
+ from app.models.audit_log import AuditLog
+
+ row = AuditLog(
+ action=action,
+ target_type=target_type,
+ target_id=target_id,
+ user_id=user_id,
+ created_at=created_at,
+ ip_address=ip_address,
+ user_agent=user_agent,
+ )
+ row.set_details(details or {})
+ db.session.add(row)
+ db.session.commit()
+ return row
+
+
+def test_timeline_requires_developer_and_returns_typed_missing_server(
+ client, db_session):
+ server = make_server(db_session)
+ viewer = make_user(db_session, role='viewer')
+ developer = make_user(db_session, role='developer')
+
+ url = f'/api/v1/servers/{server.id}/timeline'
+ assert client.get(url).status_code == 401
+ assert client.get(url, headers=headers_for(viewer)).status_code == 403
+
+ missing = '00000000-0000-0000-0000-000000000000'
+ response = client.get(
+ f'/api/v1/servers/{missing}/timeline',
+ headers=headers_for(developer),
+ )
+ assert response.status_code == 404
+ assert response.get_json()['code'] == 'server_timeline_server_not_found'
+
+
+def test_timeline_global_order_ties_and_cursor_have_no_duplicates(
+ client, db_session):
+ server = make_server(db_session)
+ owner = make_user(db_session, role='developer')
+ application = make_application(
+ db_session, user_id=owner.id, server_id=server.id,
+ )
+ when = datetime(2026, 8, 23, 12, 0, 0, 123456)
+ older = when - timedelta(seconds=1)
+
+ audit_low = _audit(
+ db_session, action='server.low', created_at=when,
+ target_type='server', target_id=server.id,
+ )
+ audit_high = _audit(
+ db_session, action='server.high', created_at=when,
+ details={'server_id': server.id},
+ )
+ point = _restore_point(
+ db_session, server_id=server.id, scope_type='cron', scope_id='root',
+ created_at=when, actor_user_id=owner.id,
+ )
+ snapshot = _snapshot(db_session, application, when)
+ old_audit = _audit(
+ db_session, action='server.old', created_at=older,
+ details={'server_id': server.id},
+ )
+
+ headers = headers_for(owner)
+ # limit=1 deliberately splits equal-time rows from the same source across
+ # pages, exercising the native-id component of the keyset cursor.
+ url = f'/api/v1/servers/{server.id}/timeline?limit=1'
+ seen = []
+ cursor = None
+ while True:
+ page_url = url + (f'&before={cursor}' if cursor else '')
+ response = client.get(page_url, headers=headers)
+ assert response.status_code == 200, response.get_json()
+ body = response.get_json()
+ seen.extend((event['type'], event['source_id']) for event in body['events'])
+ cursor = body['next_cursor']
+ if cursor is None:
+ break
+
+ assert seen == [
+ ('audit', audit_high.id),
+ ('audit', audit_low.id),
+ ('restore_point', point.id),
+ ('deployment_snapshot', snapshot.id),
+ ('audit', old_audit.id),
+ ]
+ assert len(seen) == len(set(seen))
+
+
+def test_timeline_type_filter_and_snapshot_attribution(client, db_session):
+ server = make_server(db_session)
+ owner = make_user(db_session, role='developer')
+ application = make_application(
+ db_session, user_id=owner.id, server_id=server.id, name='timeline-app',
+ )
+ snapshot = _snapshot(
+ db_session, application, datetime(2026, 8, 23, 11),
+ summary='image updated',
+ )
+ _audit(
+ db_session, action='server.other', created_at=datetime(2026, 8, 23, 12),
+ details={'server_id': server.id},
+ )
+
+ response = client.get(
+ f'/api/v1/servers/{server.id}/timeline?types=deployment_snapshot',
+ headers=headers_for(owner),
+ )
+ assert response.status_code == 200
+ assert response.get_json() == {
+ 'events': [{
+ 'id': f'deployment_snapshot:{snapshot.id}',
+ 'type': 'deployment_snapshot',
+ 'source_id': snapshot.id,
+ 'created_at': '2026-08-23T11:00:00.000000',
+ 'action': 'deployment.snapshot',
+ 'actor_user_id': None,
+ 'application_id': application.id,
+ 'application_name': 'timeline-app',
+ 'deployment_id': None,
+ 'snapshot_hash': 'b' * 64,
+ 'summary': 'image updated',
+ }],
+ 'next_cursor': None,
+ }
+
+
+def test_app_owned_events_are_grant_filtered_before_pagination(
+ client, db_session):
+ from app.services.resource_grant_service import ResourceGrantService
+
+ server = make_server(db_session)
+ caller = make_user(db_session, role='developer')
+ other = make_user(db_session, role='developer')
+ visible = make_application(
+ db_session, user_id=other.id, server_id=server.id, name='shared',
+ )
+ hidden = make_application(
+ db_session, user_id=other.id, server_id=server.id, name='hidden',
+ )
+ ResourceGrantService.grant(
+ caller.id, 'application', visible.id, role='viewer',
+ )
+ when = datetime(2026, 8, 23, 12)
+
+ visible_snapshot = _snapshot(db_session, visible, when)
+ _snapshot(db_session, hidden, when + timedelta(seconds=3))
+ visible_point = _restore_point(
+ db_session, server_id=server.id, scope_type='env', scope_id=visible.id,
+ created_at=when - timedelta(seconds=1),
+ )
+ _restore_point(
+ db_session, server_id=server.id, scope_type='env', scope_id=hidden.id,
+ created_at=when + timedelta(seconds=2),
+ )
+ visible_audit = _audit(
+ db_session, action='app.update', created_at=when - timedelta(seconds=2),
+ target_type='app', target_id=visible.id,
+ )
+ _audit(
+ db_session, action='app.secret', created_at=when + timedelta(seconds=1),
+ target_type='app', target_id=hidden.id,
+ details={'server_id': server.id},
+ )
+
+ response = client.get(
+ f'/api/v1/servers/{server.id}/timeline?limit=3',
+ headers=headers_for(caller),
+ )
+ assert response.status_code == 200
+ rows = response.get_json()['events']
+ assert [(row['type'], row['source_id']) for row in rows] == [
+ ('deployment_snapshot', visible_snapshot.id),
+ ('restore_point', visible_point.id),
+ ('audit', visible_audit.id),
+ ]
+ assert response.get_json()['next_cursor'] is None
+
+
+def test_legacy_env_fallback_and_explicit_server_history(client, db_session):
+ target = make_server(db_session, name='target')
+ other_server = make_server(db_session, name='other')
+ owner = make_user(db_session, role='developer')
+ current = make_application(
+ db_session, user_id=owner.id, server_id=target.id, name='current',
+ )
+ moved = make_application(
+ db_session, user_id=owner.id, server_id=other_server.id, name='moved',
+ )
+ legacy = _restore_point(
+ db_session, server_id=None, scope_type='env', scope_id=current.id,
+ created_at=datetime(2026, 8, 23, 10), label='legacy current',
+ )
+ explicit_history = _restore_point(
+ db_session, server_id=target.id, scope_type='env', scope_id=moved.id,
+ created_at=datetime(2026, 8, 23, 9), label='before app moved',
+ )
+ _restore_point(
+ db_session, server_id=None, scope_type='env', scope_id=moved.id,
+ created_at=datetime(2026, 8, 23, 11), label='belongs elsewhere',
+ )
+
+ response = client.get(
+ f'/api/v1/servers/{target.id}/timeline?types=restore_point',
+ headers=headers_for(owner),
+ )
+ assert response.status_code == 200
+ assert [row['source_id'] for row in response.get_json()['events']] == [
+ legacy.id, explicit_history.id,
+ ]
+
+
+def test_audit_exact_attribution_duplicate_suppression_and_safe_projection(
+ client, db_session):
+ server = make_server(db_session)
+ other = make_server(db_session)
+ developer = make_user(db_session, role='developer')
+ when = datetime(2026, 8, 23, 12)
+ direct = _audit(
+ db_session, action='server.direct', created_at=when,
+ target_type='server', target_id=server.id, user_id=developer.id,
+ details={'state': 'ready', 'password': 'must-not-appear'},
+ )
+ routed = _audit(
+ db_session, action='api.mutation', created_at=when - timedelta(seconds=1),
+ target_type='servers',
+ details={
+ 'route_args': {'server_id': server.id},
+ 'method': 'POST',
+ 'payload': {'api_secret': 'must-not-appear'},
+ },
+ )
+ detailed = _audit(
+ db_session, action='server.detail', created_at=when - timedelta(seconds=2),
+ target_type='fleet_repair',
+ details={'server_id': server.id, 'kind': 'service', 'ip': 'hidden'},
+ )
+ _audit(
+ db_session, action='server.wrong', created_at=when + timedelta(seconds=1),
+ details={'server_id': other.id},
+ )
+ _audit(
+ db_session, action='restore_point.create', created_at=when + timedelta(seconds=2),
+ target_type='restore_point', details={'server_id': server.id},
+ )
+
+ response = client.get(
+ f'/api/v1/servers/{server.id}/timeline?types=audit',
+ headers=headers_for(developer),
+ )
+ assert response.status_code == 200
+ events = response.get_json()['events']
+ assert [event['source_id'] for event in events] == [
+ direct.id, routed.id, detailed.id,
+ ]
+ assert events[0]['actor_username'] == developer.username
+ assert events[0]['details'] == {'state': 'ready'}
+ assert events[1]['details'] == {'method': 'POST'}
+ assert events[2]['details'] == {
+ 'kind': 'service', 'server_id': server.id,
+ }
+ for event in events:
+ assert 'ip_address' not in event
+ assert 'user_agent' not in event
+ assert 'payload' not in event['details']
+
+
+def test_timeline_rejects_invalid_query_and_mismatched_cursor(
+ client, db_session):
+ first_server = make_server(db_session)
+ second_server = make_server(db_session)
+ developer = make_user(db_session, role='developer')
+ headers = headers_for(developer)
+ now = datetime(2026, 8, 23, 12)
+ _audit(
+ db_session, action='one', created_at=now,
+ details={'server_id': first_server.id},
+ )
+ _audit(
+ db_session, action='two', created_at=now - timedelta(seconds=1),
+ details={'server_id': first_server.id},
+ )
+ base = f'/api/v1/servers/{first_server.id}/timeline'
+
+ invalid = (
+ '?types=unknown',
+ '?limit=0',
+ '?limit=201',
+ '?limit=wat',
+ '?before=not-a-cursor',
+ '?extra=yes',
+ '?limit=1&limit=2',
+ )
+ for query in invalid:
+ response = client.get(base + query, headers=headers)
+ assert response.status_code == 400, (query, response.get_json())
+ assert 'code' in response.get_json()
+
+ first = client.get(base + '?types=audit&limit=1', headers=headers)
+ assert first.status_code == 200
+ cursor = first.get_json()['next_cursor']
+ assert cursor
+
+ wrong_server = client.get(
+ f'/api/v1/servers/{second_server.id}/timeline'
+ f'?types=audit&limit=1&before={cursor}',
+ headers=headers,
+ )
+ assert wrong_server.status_code == 400
+ assert wrong_server.get_json()['code'] == 'invalid_cursor'
+
+ wrong_types = client.get(
+ base + f'?types=restore_point&limit=1&before={cursor}',
+ headers=headers,
+ )
+ assert wrong_types.status_code == 400
+ assert wrong_types.get_json()['code'] == 'invalid_cursor'
+
+ encoded = cursor.encode('ascii')
+ encoded += b'=' * (-len(encoded) % 4)
+ tampered_payload = json.loads(base64.urlsafe_b64decode(encoded))
+ tampered_payload['source'] = 'restore_point'
+ tampered = base64.urlsafe_b64encode(json.dumps(
+ tampered_payload, sort_keys=True, separators=(',', ':'),
+ ).encode()).rstrip(b'=').decode()
+ response = client.get(
+ base + f'?types=audit&limit=1&before={tampered}', headers=headers,
+ )
+ assert response.status_code == 400
+ assert response.get_json()['code'] == 'invalid_cursor'