feat(cloud): .wefc envelope endpoints + Backstage cloud-save wiring

Voegt GET/PUT /api/v2/projects/{id}/wefc endpoints toe in de Python
FastAPI backend. Bridge naar bestaande NextcloudClient via project.name
als folder en project-{id}.wefc als manifestnaam. Volume-mount fast-path
+ WebDAV fallback. Auth via Authentik forward_auth headers (X-Authentik-
Username + X-Authentik-Meta-Tenant) met 401/403/404/503/502 fout-mapping.

Backstage.tsx vervangt placeholder cloud open/save calls met echte
project-id-based endpoints — niet meer hardcoded "current-project":
- handleSave leest bestaande envelope en merget header voor in-place
  update via saveProjectWefc(project.id, ...)
- handleSaveAsServer maakt nieuw v2 project via createProject() en
  schrijft envelope met canonical id
- handleSaveAsLocal exporteert echte WeFC JSON envelope
- handleFileSelected valideert WeFC header bij lokale .wefc open
- ProjectIoSlice setSaveInfo + markClean voor dirty-tracking

Build: viewer npm run build exit 0, tsc strict exit 0.
Tests: server pytest cloud + NC client (26 passed, geen regressies).

Plan: docs/2026-04-16-week-plan-authentik-saveux.md week 2 cloud-save

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jochem25

server/routers/projects.py

@@ -4,25 +4,41 @@
 Endpoints for CRUD on projects, and upload/download/delete of
 IFC, BCF, and IDS files within projects. Files are stored on disk
 under PROJECT_FILES_DIR/{project_id}/{file_type}/.
+
+Also provides .wefc envelope endpoints that bridge the persistent
+project (DB row) to its corresponding tenant Nextcloud folder.
 """
 
+import json
 import logging
 import os
 import shutil
 import uuid
+from datetime import datetime, timezone
 from pathlib import Path
+from typing import Any
 
-from fastapi import APIRouter, File, Form, HTTPException, UploadFile
-from fastapi.responses import FileResponse
+from fastapi import APIRouter, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import FileResponse, JSONResponse, Response
 from sqlalchemy import select
 
 from server.database import get_session
 from server.models.db_models import Project, ProjectFile
+from server.nextcloud_client import (
+    MANIFEST_FILENAME,
+    NextcloudError,
+    get_nc_client,
+)
+from server.tenant_config import TenantConfig, get_tenants
+from server.volume_reader import VolumeReader
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/v2", tags=["projects"])
 
+# Default tenant slug when multi-tenant resolution is not yet active
+DEFAULT_TENANT_SLUG = "3bm"
+
 # Base directory for project file storage
 PROJECT_FILES_DIR = Path(
     os.environ.get("PROJECT_FILES_DIR", "/data/projects")
@@ -265,3 +281,182 @@ async def delete_file(project_id: str, file_id: str):
             "Deleted file %s from project %s", file_id, project_id
         )
         return {"success": True, "message": f"File {file_id} deleted"}
+
+
+# ── .wefc envelope (bridges persistent project to tenant cloud) ──
+
+
+def _resolve_tenant_from_request(request: Request) -> TenantConfig:
+    """Resolve tenant from Authentik forward-auth headers.
+
+    Looks for X-Authentik-Meta-Tenant first (custom OpenAEC profile
+    scope), falls back to a query parameter ``tenant`` and finally to
+    the default tenant slug.
+
+    Raises:
+        HTTPException 401 when no Authentik user header is present.
+        HTTPException 503 when no tenants are configured at all.
+        HTTPException 403 when the requested tenant slug is unknown.
+    """
+    # Auth gate — Authentik forward-auth always sets a username header
+    # for authenticated requests. Reject when missing.
+    if not request.headers.get("X-authentik-username"):
+        raise HTTPException(401, "Not authenticated")
+
+    registry = get_tenants()
+    if not registry.is_configured:
+        raise HTTPException(503, "Cloud storage not configured (no tenants)")
+
+    # Header is set by Authentik when the openaec_profile scope is mapped.
+    slug = (
+        request.headers.get("X-Authentik-Meta-Tenant")
+        or request.query_params.get("tenant")
+        or DEFAULT_TENANT_SLUG
+    )
+
+    config = registry.get(slug)
+    if not config:
+        raise HTTPException(403, f"Unknown tenant: {slug}")
+    return config
+
+
+def _nc_error_to_http(exc: Exception) -> HTTPException:
+    """Map a NextcloudError to an HTTP response."""
+    if isinstance(exc, NextcloudError) and exc.status_code:
+        return HTTPException(status_code=exc.status_code, detail=str(exc))
+    return HTTPException(status_code=502, detail=f"Cloud backend error: {exc}")
+
+
+def _wefc_filename_for_project(project: Project) -> str:
+    """Return the .wefc filename used for a persistent project.
+
+    Uses a stable, project-id derived name so multiple projects with
+    the same display name do not collide in the same Nextcloud folder.
+    The plain project.wefc remains reserved for the legacy/default
+    container.
+    """
+    return f"project-{project.id}.wefc"
+
+
+def _project_folder_name(project: Project) -> str:
+    """Return the Nextcloud folder name for a persistent project.
+
+    Convention: all v2 project envelopes live under a single shared
+    ``Projects/`` namespace, in a per-project folder derived from the
+    project name. Falls back to the project id if no name is set.
+    """
+    name = (project.name or "").strip()
+    if not name:
+        return f"project-{project.id}"
+    return name
+
+
+@router.get("/projects/{project_id}/wefc")
+async def get_project_wefc(project_id: str, request: Request):
+    """Return the .wefc envelope for a persistent project.
+
+    Resolves the tenant from forward-auth headers, locates the
+    project's Nextcloud folder, and reads the manifest via the volume
+    mount when available, falling back to WebDAV otherwise.
+    """
+    config = _resolve_tenant_from_request(request)
+
+    async with get_session() as session:
+        project = await session.get(Project, project_id)
+        if not project:
+            raise HTTPException(404, f"Project not found: {project_id}")
+        folder = _project_folder_name(project)
+        manifest_name = _wefc_filename_for_project(project)
+
+    # Fast path: read from the tenant's volume mount
+    reader = VolumeReader(config)
+    if reader.available:
+        manifest = reader.read_manifest(folder, manifest_name)
+        if manifest is None:
+            # Backward-compat: also try the default project.wefc for projects
+            # that were saved before the project-id naming convention.
+            manifest = reader.read_manifest(folder, MANIFEST_FILENAME)
+        if manifest is not None:
+            return JSONResponse(content=manifest)
+
+    # Fallback: WebDAV
+    client = get_nc_client(config)
+    try:
+        manifest = await client.read_manifest(folder, manifest_name)
+        if manifest is None:
+            manifest = await client.read_manifest(folder, MANIFEST_FILENAME)
+    except Exception as exc:
+        raise _nc_error_to_http(exc) from exc
+
+    if manifest is None:
+        raise HTTPException(
+            404,
+            f"No .wefc envelope for project {project_id} (folder: {folder})",
+        )
+    return JSONResponse(content=manifest)
+
+
+@router.put("/projects/{project_id}/wefc")
+async def put_project_wefc(
+    project_id: str,
+    request: Request,
+    manifest: dict[str, Any],
+):
+    """Write the .wefc envelope for a persistent project.
+
+    Validates that the body is a dict, ensures the manifest header is
+    present and current, and writes via WebDAV (always — volume mount
+    is read-only for the bim-validator process).
+    """
+    config = _resolve_tenant_from_request(request)
+
+    if not isinstance(manifest, dict):
+        raise HTTPException(400, "Body must be a JSON object")
+
+    async with get_session() as session:
+        project = await session.get(Project, project_id)
+        if not project:
+            raise HTTPException(404, f"Project not found: {project_id}")
+        folder = _project_folder_name(project)
+        manifest_name = _wefc_filename_for_project(project)
+
+    # Ensure the manifest header is up to date
+    header = manifest.get("header") if isinstance(manifest.get("header"), dict) else {}
+    header.setdefault("schema", "WeFC")
+    header.setdefault("schema_version", "1.1.0")
+    header.setdefault("fileId", str(uuid.uuid4()))
+    header["timestamp"] = datetime.now(timezone.utc).isoformat()
+    header["application"] = "bim-validator"
+    header["projectId"] = project_id
+    header["projectName"] = project.name
+    manifest["header"] = header
+
+    # Touch the project's updated_at so the listing reflects the save.
+    async with get_session() as session:
+        db_project = await session.get(Project, project_id)
+        if db_project is not None:
+            db_project.updated_at = datetime.now(timezone.utc)
+
+    client = get_nc_client(config)
+    try:
+        await client.write_manifest(folder, manifest, manifest_name)
+    except Exception as exc:
+        raise _nc_error_to_http(exc) from exc
+
+    logger.info(
+        "Wrote .wefc envelope for project %s (folder=%s, file=%s, tenant=%s)",
+        project_id,
+        folder,
+        manifest_name,
+        config.slug,
+    )
+
+    return JSONResponse(
+        content={
+            "success": True,
+            "projectId": project_id,
+            "folder": folder,
+            "manifest": manifest_name,
+            "tenant": config.slug,
+        }
+    )

viewer/src/api/projectApi.ts

@@ -283,3 +283,36 @@ export async function getElementProperties(
   );
   return handleResponse<ElementProperties>(response);
 }
+
+// ── .wefc envelope (cloud-bridge) ─────────────────────────────
+
+/**
+ * Read the .wefc envelope for a persistent project from the tenant
+ * Nextcloud folder. Returns ``null`` when no envelope exists yet.
+ */
+export async function readProjectWefc(
+  projectId: string
+): Promise<Record<string, unknown> | null> {
+  const response = await fetch(`${API_V2}/projects/${projectId}/wefc`);
+  if (response.status === 404) {
+    return null;
+  }
+  return handleResponse<Record<string, unknown>>(response);
+}
+
+/**
+ * Write the .wefc envelope for a persistent project. The backend
+ * persists the manifest in the tenant Nextcloud folder via WebDAV
+ * and refreshes the project's ``updated_at`` timestamp.
+ */
+export async function saveProjectWefc(
+  projectId: string,
+  manifest: Record<string, unknown>
+): Promise<void> {
+  const response = await fetch(`${API_V2}/projects/${projectId}/wefc`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(manifest),
+  });
+  await handleResponse(response);
+}