feat(vcard): implement vCard round-trip hash verification

Author: pike00

backend/app/api/main.py

@@ -26,6 +26,7 @@
     tags,
     users,
     utils,
+    vcard_conflicts,
     webhooks,
 )
 from app.core.config import settings
@@ -57,6 +58,7 @@
 api_router.include_router(import_export.router)
 api_router.include_router(webhooks.router)
 api_router.include_router(activity_logs.router)
+api_router.include_router(vcard_conflicts.router)
 api_router.include_router(calendar.router)
 
 

backend/app/api/routes/contacts.py

@@ -28,6 +28,7 @@
     OverdueContactsPublic,
     User,
 )
+from app.vcard import compute_vcard_hash
 
 
 class BulkContactFilter(BaseModel):
@@ -641,6 +642,9 @@ def update_contact(
     group_ids = update_data.pop("group_ids", None)
 
     contact.sqlmodel_update(update_data)
+    # Compute vcard_sha256 if vcard_raw was updated
+    if "vcard_raw" in update_data and contact.vcard_raw:
+        contact.vcard_sha256 = compute_vcard_hash(contact.vcard_raw)
     session.add(contact)
 
     # Update tag associations if provided

backend/app/api/routes/vcard_conflicts.py

@@ -0,0 +1,162 @@
+"""API routes for vCard conflict management."""
+
+import uuid
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, HTTPException
+from sqlmodel import select
+
+from app.api.deps import CurrentUser, SessionDep
+from app.models import Contact
+from app.models_vcard_conflict import (
+    VCardConflict,
+    VCardConflictPublic,
+    VCardConflictsPublic,
+)
+
+router = APIRouter(prefix="/vcard-conflicts", tags=["vCard Conflicts"])
+
+
+@router.get("/", response_model=VCardConflictsPublic)
+def list_vcard_conflicts(
+    session: SessionDep,
+    current_user: CurrentUser,
+    skip: int = 0,
+    limit: int = 100,
+) -> VCardConflictsPublic:
+    """List all unresolved vCard conflicts for the current user."""
+    # Join with Contact to ensure we only return conflicts for this user's contacts
+    stmt = (
+        select(VCardConflict)
+        .join(Contact, VCardConflict.contact_id == Contact.id)
+        .where(
+            Contact.owner_id == current_user.id,
+            VCardConflict.resolved_at.is_(None),
+        )
+        .order_by(VCardConflict.created_at.desc())
+        .offset(skip)
+        .limit(limit)
+    )
+    conflicts = session.exec(stmt).all()
+
+    # Also get the local vcard_raw for each conflict
+    result = []
+    for conflict in conflicts:
+        conflict_public = VCardConflictPublic(
+            id=conflict.id,
+            contact_id=conflict.contact_id,
+            incoming_vcard_raw=conflict.incoming_vcard_raw,
+            incoming_hash=conflict.incoming_hash,
+            local_hash=conflict.local_hash,
+            resolved_at=conflict.resolved_at,
+            resolution_type=conflict.resolution_type,
+            created_at=conflict.created_at,
+            local_vcard_raw=conflict.local_vcard_raw,
+        )
+        result.append(conflict_public)
+
+    count_stmt = (
+        select(VCardConflict)
+        .join(Contact, VCardConflict.contact_id == Contact.id)
+        .where(
+            Contact.owner_id == current_user.id,
+            VCardConflict.resolved_at.is_(None),
+        )
+    )
+    count = len(session.exec(count_stmt).all())
+
+    return VCardConflictsPublic(data=result, count=count)
+
+
+@router.post("/{conflict_id}/resolve", response_model=VCardConflictPublic)
+def resolve_vcard_conflict(
+    session: SessionDep,
+    current_user: CurrentUser,
+    conflict_id: uuid.UUID,
+    resolution_type: str,
+) -> VCardConflictPublic:
+    """Resolve a vCard conflict by accepting remote or keeping local.
+
+    resolution_type must be one of: 'keep_local', 'accept_remote'
+    """
+    if resolution_type not in ("keep_local", "accept_remote"):
+        raise HTTPException(
+            status_code=400,
+            detail="resolution_type must be 'keep_local' or 'accept_remote'",
+        )
+
+    # Get the conflict and verify ownership
+    stmt = (
+        select(VCardConflict)
+        .join(Contact, VCardConflict.contact_id == Contact.id)
+        .where(
+            VCardConflict.id == conflict_id,
+            Contact.owner_id == current_user.id,
+        )
+    )
+    conflict = session.exec(stmt).first()
+    if not conflict:
+        raise HTTPException(status_code=404, detail="Conflict not found")
+
+    if conflict.resolved_at is not None:
+        raise HTTPException(status_code=400, detail="Conflict already resolved")
+
+    # Get the contact
+    contact = session.get(Contact, conflict.contact_id)
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    if resolution_type == "accept_remote":
+        # Update contact with incoming vCard data
+        from app.vcard import vcard_to_contact_data
+
+        parsed = vcard_to_contact_data(conflict.incoming_vcard_raw)
+        contact_data = parsed["contact"]
+        for key, value in contact_data.items():
+            if hasattr(contact, key):
+                setattr(contact, key, value)
+        contact.vcard_raw = conflict.incoming_vcard_raw
+        contact.vcard_sha256 = conflict.incoming_hash
+        session.add(contact)
+
+    # Mark conflict as resolved
+    conflict.resolved_at = datetime.now(timezone.utc)
+    conflict.resolution_type = resolution_type
+    session.add(conflict)
+    session.commit()
+    session.refresh(conflict)
+
+    return VCardConflictPublic(
+        id=conflict.id,
+        contact_id=conflict.contact_id,
+        incoming_vcard_raw=conflict.incoming_vcard_raw,
+        incoming_hash=conflict.incoming_hash,
+        local_hash=conflict.local_hash,
+        resolved_at=conflict.resolved_at,
+        resolution_type=conflict.resolution_type,
+        created_at=conflict.created_at,
+        local_vcard_raw=conflict.local_vcard_raw,
+    )
+
+
+@router.delete("/{conflict_id}", status_code=204)
+def delete_vcard_conflict(
+    session: SessionDep,
+    current_user: CurrentUser,
+    conflict_id: uuid.UUID,
+) -> None:
+    """Delete a vCard conflict (dismiss without action)."""
+    stmt = (
+        select(VCardConflict)
+        .join(Contact, VCardConflict.contact_id == Contact.id)
+        .where(
+            VCardConflict.id == conflict_id,
+            Contact.owner_id == current_user.id,
+        )
+    )
+    conflict = session.exec(stmt).first()
+    if not conflict:
+        raise HTTPException(status_code=404, detail="Conflict not found")
+
+    session.delete(conflict)
+    session.commit()

backend/app/carddav/storage.py

@@ -17,7 +17,8 @@
 from sqlmodel import Session, create_engine, select
 
 from app.core.config import settings
-from app.models import Contact, User
+from app.models import Contact, User, VCardConflict
+from app.vcard import compute_vcard_hash, normalize_vcard_for_hash
 
 
 def _http_datetime(dt: datetime) -> str:
@@ -137,24 +138,42 @@ def upload(
                     )
                 # Update fields from parsed vCard
                 contact_data = parsed["contact"]
+
+                # vCard hash verification for conflict detection
+                incoming_hash = compute_vcard_hash(vcard_text)
+                if existing.vcard_sha256 and existing.vcard_sha256 != incoming_hash:
+                    # Hash mismatch - potential conflict
+                    # Check if it's just whitespace/formatting drift
+                    if existing.vcard_raw:
+                        local_normalized = normalize_vcard_for_hash(existing.vcard_raw)
+                        incoming_normalized = normalize_vcard_for_hash(vcard_text)
+                        if local_normalized != incoming_normalized:
+                            # Real conflict - store for user review
+                            conflict = VCardConflict(
+                                contact_id=existing.id,
+                                incoming_vcard_raw=vcard_text,
+                                incoming_hash=incoming_hash,
+                                local_hash=existing.vcard_sha256,
+                                local_vcard_raw=existing.vcard_raw,
+                            )
+                            session.add(conflict)
+
                 for key, value in contact_data.items():
                     if hasattr(existing, key):
                         setattr(existing, key, value)
                 existing.vcard_raw = vcard_text
                 existing.vcard_etag = item.etag
-                session.add(existing)
+                existing.vcard_sha256 = incoming_hash
             else:
                 # Create new contact
                 contact_data = parsed["contact"]
-                new_contact = Contact(
+                Contact(
                     owner_id=user.id,
                     vcard_raw=vcard_text,
                     vcard_etag=item.etag,
+                    vcard_sha256=compute_vcard_hash(vcard_text),
                     **contact_data,
                 )
-                if parsed.get("uid"):
-                    new_contact.id = parsed["uid"]
-                session.add(new_contact)
 
             session.commit()
 

backend/app/crud.py

@@ -55,6 +55,7 @@
     UserCreate,
     UserUpdate,
 )
+from app.vcard import compute_vcard_hash
 
 
 def create_user(*, session: Session, user_create: UserCreate) -> User:
@@ -117,6 +118,9 @@ def create_contact(
     *, session: Session, contact_in: ContactCreate, owner_id: uuid.UUID
 ) -> Contact:
     db_obj = Contact.model_validate(contact_in, update={"owner_id": owner_id})
+    # Compute vcard_sha256 if vcard_raw is present
+    if db_obj.vcard_raw:
+        db_obj.vcard_sha256 = compute_vcard_hash(db_obj.vcard_raw)
     session.add(db_obj)
     session.commit()
     session.refresh(db_obj)

backend/app/models.py

@@ -7,6 +7,8 @@
 from sqlalchemy import DateTime
 from sqlmodel import Field, Relationship, SQLModel
 
+from app.models_vcard_conflict import VCardConflict  # noqa: F401
+
 
 def get_datetime_utc() -> datetime:
     return datetime.now(timezone.utc)

backend/app/vcard.py

@@ -4,6 +4,7 @@
 Preserves unknown vCard properties through round-trips by storing raw vCard text.
 """
 
+import hashlib
 import uuid
 
 import vobject
@@ -17,9 +18,6 @@
     ContactFieldType,
 )
 
-import hashlib
-import re
-
 
 def normalize_vcard_for_hash(vcard_text: str) -> str:
     """Normalize vCard text before hashing to ensure stable hashes.
@@ -103,6 +101,8 @@ def compute_vcard_hash(vcard_text: str) -> str:
     """
     normalized = normalize_vcard_for_hash(vcard_text)
     return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
 def contact_to_vcard(
     contact: Contact,
     fields: list[ContactField],
@@ -229,6 +229,7 @@ def contact_to_vcard(
     vcard_text = card.serialize()
     return vcard_text, compute_vcard_hash(vcard_text)
 
+
 def vcard_to_contact_data(vcard_text: str) -> dict:
     """Parse a vCard string and return a dict of Contact fields + related data.