Add safe archive preview and extraction workflows

2026-07-31 02:48:56 +02:00
parent 159a012833
commit b752dea610
20 changed files with 1961 additions and 182 deletions
@@ -1,12 +1,22 @@
 from __future__ import annotations

+import hashlib
+import hmac
 import json
+from datetime import UTC, datetime, timedelta
 from typing import Literal
 from fastapi import APIRouter, Depends, File as FastAPIFile, Form, UploadFile
 from sqlalchemy.orm import Session

 from govoplan_core.auth import ApiPrincipal, require_scope
+from govoplan_core.security.secrets import (
+    TransientPayloadError,
+    open_transient_payload,
+    seal_transient_payload,
+)
 from govoplan_files.backend.schemas import (
+    ArchiveEntryResponse,
+    ArchivePreviewResponse,
    ConflictResolutionRequest,
    FileUploadResponse,
    _conflict_resolutions,
@@ -14,8 +24,16 @@ from govoplan_files.backend.schemas import (
 from govoplan_files.backend.db.models import FileAsset
 from govoplan_core.db.session import get_session
 from govoplan_files.backend.runtime import settings
-from govoplan_files.backend.storage.paths import UnsafeFilePathError
-from govoplan_files.backend.storage.archives import extract_zip_upload
+from govoplan_files.backend.storage.paths import (
+    UnsafeFilePathError,
+    normalize_folder,
+)
+from govoplan_files.backend.storage.archives import (
+    archive_format_for_filename,
+    extract_archive_upload,
+    extract_zip_upload,
+    inspect_archive,
+)
 from govoplan_files.backend.storage.common import FileStorageError
 from govoplan_files.backend.storage.connector_policy import (
    ConnectorPolicyDenied,
@@ -39,6 +57,261 @@ from govoplan_files.backend.route_support import (
 )

 router = APIRouter(prefix="/files", tags=["files"])
+_ARCHIVE_PREVIEW_PURPOSE = "files.archive-preview.v1"
+
+
+def _archive_suffix(filename: str) -> str:
+    lowered = filename.casefold()
+    for suffix in (".tar.bz2", ".tar.gz", ".tar.xz", ".tbz2", ".tgz", ".txz", ".tar", ".zip"):
+        if lowered.endswith(suffix):
+            return suffix
+    return ".archive"
+
+
+def _archive_sha256(path: str) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as source:
+        while chunk := source.read(1024 * 1024):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _archive_selected_paths(value: str) -> list[str]:
+    parsed = json.loads(value)
+    if not isinstance(parsed, list) or not parsed:
+        raise FileStorageError("Select at least one archive file or folder")
+    if len(parsed) > settings.file_archive_max_entries:
+        raise FileStorageError(
+            "Archive selection exceeds the configured entry limit"
+        )
+    selected: list[str] = []
+    for item in parsed:
+        if not isinstance(item, str) or not item.strip():
+            raise FileStorageError("Archive selection contains an invalid path")
+        if len(item) > 4096:
+            raise FileStorageError("Archive selection path is too long")
+        selected.append(item)
+    return selected
+
+
+def _validate_archive_preview_token(
+    token: str,
+    *,
+    tenant_id: str,
+    user_id: str,
+    owner_type: str,
+    owner_id: str,
+    path: str,
+    campaign_id: str | None,
+    archive_format: str,
+    archive_sha256: str,
+) -> None:
+    payload = open_transient_payload(
+        token,
+        ttl_seconds=settings.file_archive_preview_ttl_seconds,
+    )
+    expected = {
+        "purpose": _ARCHIVE_PREVIEW_PURPOSE,
+        "tenant_id": tenant_id,
+        "user_id": user_id,
+        "owner_type": owner_type,
+        "owner_id": owner_id,
+        "path": path,
+        "campaign_id": campaign_id or "",
+        "archive_format": archive_format,
+    }
+    if any(payload.get(key) != value for key, value in expected.items()):
+        raise FileStorageError(
+            "Archive preview does not match this upload destination"
+        )
+    token_digest = payload.get("archive_sha256")
+    if not isinstance(token_digest, str) or not hmac.compare_digest(
+        token_digest, archive_sha256
+    ):
+        raise FileStorageError(
+            "Archive contents changed after preview; preview it again"
+        )
+
+
+@router.post("/archive-preview", response_model=ArchivePreviewResponse)
+def preview_archive_upload(
+    file: UploadFile = FastAPIFile(...),
+    owner_type: Literal["user", "group"] = Form(default="user"),
+    owner_id: str | None = Form(default=None),
+    path: str = Form(default=""),
+    campaign_id: str | None = Form(default=None),
+    password: str | None = Form(default=None),
+    principal: ApiPrincipal = Depends(require_scope("files:file:upload")),
+):
+    target_owner = owner_id or principal.user.id
+    archive_path: str | None = None
+    filename = file.filename or "archive"
+    try:
+        archive_format = archive_format_for_filename(filename)
+        archive_path = _spool_limited_upload_to_temp(
+            file,
+            max_bytes=settings.file_upload_zip_max_bytes,
+            suffix=_archive_suffix(filename),
+        )
+        inspection = inspect_archive(
+            archive_path,
+            filename=filename,
+            password=password,
+            max_entries=settings.file_archive_max_entries,
+            max_expanded_bytes=settings.file_archive_max_expanded_bytes,
+            max_expansion_ratio=settings.file_archive_max_expansion_ratio,
+        )
+        digest = _archive_sha256(archive_path)
+        normalized_path = normalize_folder(path)
+        preview_token = seal_transient_payload(
+            {
+                "purpose": _ARCHIVE_PREVIEW_PURPOSE,
+                "tenant_id": principal.tenant_id,
+                "user_id": principal.user.id,
+                "owner_type": owner_type,
+                "owner_id": target_owner,
+                "path": normalized_path,
+                "campaign_id": campaign_id or "",
+                "archive_format": archive_format,
+                "archive_sha256": digest,
+            }
+        )
+        expires_at = datetime.now(UTC) + timedelta(
+            seconds=settings.file_archive_preview_ttl_seconds
+        )
+        return ArchivePreviewResponse(
+            preview_token=preview_token,
+            archive_format=inspection.archive_format,
+            entries=[
+                ArchiveEntryResponse(
+                    path=entry.path,
+                    kind=entry.kind,
+                    size_bytes=entry.size_bytes,
+                    compressed_size_bytes=entry.compressed_size_bytes,
+                    encrypted=entry.encrypted,
+                )
+                for entry in inspection.entries
+            ],
+            file_count=inspection.file_count,
+            directory_count=inspection.directory_count,
+            expanded_size_bytes=inspection.expanded_size_bytes,
+            compressed_size_bytes=inspection.compressed_size_bytes,
+            requires_password=inspection.requires_password,
+            password_verified=inspection.password_verified,
+            expires_at=expires_at.isoformat(),
+        )
+    except (FileStorageError, UnsafeFilePathError, ValueError) as exc:
+        raise _http_error(exc) from exc
+    finally:
+        if archive_path:
+            _cleanup_temp_file(archive_path)
+
+
+@router.post("/archive-confirm", response_model=FileUploadResponse)
+def confirm_archive_upload(
+    file: UploadFile = FastAPIFile(...),
+    preview_token: str = Form(...),
+    selected_paths_json: str = Form(...),
+    owner_type: Literal["user", "group"] = Form(default="user"),
+    owner_id: str | None = Form(default=None),
+    path: str = Form(default=""),
+    campaign_id: str | None = Form(default=None),
+    password: str | None = Form(default=None),
+    conflict_strategy: Literal["reject", "overwrite", "rename"] = Form(
+        default="reject"
+    ),
+    conflict_resolutions_json: str | None = Form(default=None),
+    source_provenance_json: str | None = Form(default=None),
+    source_revision: str | None = Form(default=None),
+    connector_policy_json: str | None = Form(default=None),
+    session: Session = Depends(get_session),
+    principal: ApiPrincipal = Depends(require_scope("files:file:upload")),
+):
+    target_owner = owner_id or principal.user.id
+    archive_path: str | None = None
+    filename = file.filename or "archive"
+    try:
+        raw_resolutions = (
+            json.loads(conflict_resolutions_json)
+            if conflict_resolutions_json
+            else []
+        )
+        upload_resolutions = _conflict_resolutions(
+            [ConflictResolutionRequest(**item) for item in raw_resolutions]
+        )
+        selected_paths = _archive_selected_paths(selected_paths_json)
+        _enforce_connector_policy(
+            source_provenance_json,
+            connector_policy_json,
+            operation="import",
+        )
+        metadata = _source_metadata_from_form(
+            source_provenance_json, source_revision
+        )
+        archive_format = archive_format_for_filename(filename)
+        normalized_path = normalize_folder(path)
+        archive_path = _spool_limited_upload_to_temp(
+            file,
+            max_bytes=settings.file_upload_zip_max_bytes,
+            suffix=_archive_suffix(filename),
+        )
+        digest = _archive_sha256(archive_path)
+        _validate_archive_preview_token(
+            preview_token,
+            tenant_id=principal.tenant_id,
+            user_id=principal.user.id,
+            owner_type=owner_type,
+            owner_id=target_owner,
+            path=normalized_path,
+            campaign_id=campaign_id,
+            archive_format=archive_format,
+            archive_sha256=digest,
+        )
+        extracted = extract_archive_upload(
+            session,
+            tenant_id=principal.tenant_id,
+            owner_type=owner_type,
+            owner_id=target_owner,
+            user_id=principal.user.id,
+            archive_data=archive_path,
+            filename=filename,
+            folder=normalized_path,
+            campaign_id=campaign_id,
+            selected_paths=selected_paths,
+            password=password,
+            conflict_strategy=conflict_strategy,
+            conflict_resolutions=upload_resolutions,
+            metadata=metadata,
+            is_admin=_is_admin(principal),
+            max_entries=settings.file_archive_max_entries,
+            max_file_bytes=settings.file_upload_max_bytes,
+            max_expanded_bytes=settings.file_archive_max_expanded_bytes,
+            max_expansion_ratio=settings.file_archive_max_expansion_ratio,
+        )
+        uploaded_assets = [item.asset for item in extracted]
+        _audit_connector_imports(session, principal, uploaded_assets)
+        session.commit()
+        return FileUploadResponse(
+            files=[
+                _asset_response(session, asset, include_shares=True)
+                for asset in uploaded_assets
+            ]
+        )
+    except ConnectorPolicyDenied as exc:
+        session.rollback()
+        raise _connector_policy_error(exc) from exc
+    except (
+        FileStorageError,
+        TransientPayloadError,
+        UnsafeFilePathError,
+        ValueError,
+        json.JSONDecodeError,
+    ) as exc:
+        session.rollback()
+        raise _http_error(exc) from exc
+    finally:
+        if archive_path:
+            _cleanup_temp_file(archive_path)


@router.post("/upload", response_model=FileUploadResponse)