Link Preview Privacy

Traditional Preview Flow (INSECURE):

1. Alice sends link to Bob in Zentalk
2. Alice's client fetches preview from target.com
   → Target sees: IP=Alice, Referer=zentalk-client
3. Bob's client fetches preview from target.com
   → Target sees: IP=Bob, Referer=zentalk-client
4. Target can correlate:
   → Two Zentalk users accessed same URL
   → Timing suggests communication between them
   → IPs reveal approximate locations

Privacy-Preserving Preview Flow:

1. USER PASTES LINK
   → Client detects URL pattern in message input
   → Preview request initiated (if enabled)

2. BUILD RELAY CIRCUIT
   → Select 2-hop circuit from relay pool
   → Entry relay: Knows client, not destination
   → Exit relay: Knows destination, not client

3. ENCRYPT REQUEST
   → Construct preview request
   → Encrypt for exit relay (inner layer)
   → Encrypt for entry relay (outer layer)

4. ROUTE THROUGH RELAYS
   → Client → Entry Relay (onion layer 1)
   → Entry Relay → Exit Relay (onion layer 2)
   → Exit Relay → Target URL (plaintext HTTPS)

5. FETCH AND SANITIZE
   → Exit relay fetches target URL
   → Content sanitized (scripts removed)
   → Metadata extracted (title, description, image)

6. RETURN ENCRYPTED RESPONSE
   → Exit relay encrypts response for client
   → Routed back through entry relay
   → Client decrypts preview data

7. CACHE AND DISPLAY
   → Preview cached locally (encrypted)
   → Rendered in message compose area
   → Attached to message when sent

Metadata Extraction Process:

1. PARSE HTML
   document = parse_html(response_body)

2. EXTRACT OPEN GRAPH
   og_tags = document.query_all('meta[property^="og:"]')
   FOR EACH tag IN og_tags:
       key = tag.property.replace("og:", "")
       value = tag.content
       metadata[key] = sanitize(value)

3. EXTRACT TWITTER CARDS
   twitter_tags = document.query_all('meta[name^="twitter:"]')
   FOR EACH tag IN twitter_tags:
       key = tag.name.replace("twitter:", "")
       IF key NOT IN metadata:
           metadata[key] = sanitize(tag.content)

4. FALLBACK TO HTML
   IF "title" NOT IN metadata:
       metadata["title"] = document.query('title').text

   IF "description" NOT IN metadata:
       meta_desc = document.query('meta[name="description"]')
       metadata["description"] = meta_desc.content

5. TRUNCATE AND SANITIZE
   metadata["title"] = truncate(metadata["title"], 200)
   metadata["description"] = truncate(metadata["description"], 500)

Thumbnail Generation:

1. FETCH IMAGE
   image_data = fetch_with_limit(image_url, max=2MB)

2. VALIDATE IMAGE
   IF NOT valid_image_format(image_data):
       SKIP thumbnail generation
   IF image_dimensions > 4096x4096:
       SKIP thumbnail generation

3. RESIZE
   thumbnail = resize_image(
       image_data,
       max_width=400,
       max_height=400,
       preserve_aspect=true
   )

4. ENCODE
   output = encode_webp(thumbnail, quality=75)
   IF output.size > 100KB:
       output = encode_jpeg(thumbnail, quality=60)

5. RETURN
   IF output.size ≤ 100KB:
       RETURN output
   ELSE:
       RETURN null  // Skip oversized thumbnails

Cache Key Derivation:

1. NORMALIZE URL
   normalized = url.lower()
   normalized = remove_tracking_params(normalized)
   normalized = sort_query_params(normalized)

2. GENERATE KEY
   cache_key = SHA-256(normalized)

3. LOOKUP
   cached_preview = cache.get(cache_key)
   IF cached_preview AND NOT expired(cached_preview):
       RETURN cached_preview

Tracking Parameters Removed:
  - utm_source, utm_medium, utm_campaign
  - fbclid, gclid, msclkid
  - ref, source, via
  - Any parameter matching tracking patterns

Content Sanitization Process:

1. REMOVE DANGEROUS ELEMENTS
   dangerous_tags = [
       'script', 'style', 'iframe', 'frame',
       'object', 'embed', 'applet', 'form',
       'input', 'button', 'select', 'textarea'
   ]
   FOR EACH tag IN dangerous_tags:
       document.remove_all(tag)

2. REMOVE EVENT HANDLERS
   FOR EACH element IN document.all_elements():
       FOR EACH attr IN element.attributes:
           IF attr.name.starts_with('on'):
               element.remove_attribute(attr.name)

3. SANITIZE URLS
   FOR EACH attr IN ['href', 'src', 'action']:
       FOR EACH element IN document.query_all('[' + attr + ']'):
           url = element.get(attr)
           IF NOT is_safe_url(url):
               element.remove_attribute(attr)

4. EXTRACT TEXT ONLY
   // Final preview contains only:
   // - Plain text title
   // - Plain text description
   // - Validated image URL
   // No HTML markup in final preview

SSRF Prevention Flow:

1. PARSE URL
   parsed = parse_url(target_url)
   IF parsed.scheme NOT IN ['http', 'https']:
       REJECT("Invalid protocol")

2. RESOLVE DNS
   ip_addresses = dns_resolve(parsed.host)

3. VALIDATE IPS
   FOR EACH ip IN ip_addresses:
       IF is_private_ip(ip):
           REJECT("Private IP not allowed")
       IF is_loopback(ip):
           REJECT("Loopback not allowed")
       IF is_cloud_metadata(ip):
           REJECT("Metadata endpoint not allowed")

4. FETCH WITH VALIDATED IP
   connection = connect_to_ip(ip_addresses[0], parsed.port)
   // Use original hostname for TLS SNI and Host header

5. FOLLOW REDIRECTS (limited)
   redirect_count = 0
   WHILE response.is_redirect AND redirect_count < 3:
       new_url = response.headers['Location']
       VALIDATE new_url (repeat steps 1-4)
       redirect_count += 1

Preview Confirmation Flow:

1. USER PASTES URL
   → Preview generated in background

2. PREVIEW DISPLAYED IN COMPOSE
   ┌────────────────────────────────┐
   │ [Preview Image]                │
   │ Title of the Page              │
   │ Description excerpt...         │
   │ example.com                    │
   │                                │
   │ [Include Preview] [Remove]     │
   └────────────────────────────────┘

3. USER CHOOSES
   → "Include Preview": Attach preview to message
   → "Remove": Send message without preview

4. RECIPIENT OPTIONS
   → Preview shown inline
   → Click to open URL (with warning)

Staleness Mitigation:

1. CACHE HEADERS
   Respect Cache-Control from origin
   max-age used when present

2. FRESHNESS INDICATORS
   Show "Preview from [time]" if > 1 hour old

3. REFRESH OPTION
   User can manually refresh preview
   Bypasses cache, fetches fresh content

4. RECIPIENT FETCH
   Recipients can optionally re-fetch
   Useful for time-sensitive content

Fallback Hierarchy:

1. FULL PREVIEW
   Title + Description + Image
   ↓ (if image fetch fails)

2. TEXT PREVIEW
   Title + Description only
   ↓ (if metadata extraction fails)

3. MINIMAL PREVIEW
   Domain name + favicon
   ↓ (if everything fails)

4. LINK ONLY
   Plain URL displayed
   No preview attachment

Preview Attachment Structure:

┌─────────────────────────────────────────┐
│ Attachment Type (1 byte): LINK_PREVIEW  │
├─────────────────────────────────────────┤
│ Original URL (variable)                 │
├─────────────────────────────────────────┤
│ Title (variable)                        │
├─────────────────────────────────────────┤
│ Description (variable)                  │
├─────────────────────────────────────────┤
│ Site Name (variable)                    │
├─────────────────────────────────────────┤
│ Thumbnail Key (32 bytes)                │
├─────────────────────────────────────────┤
│ Thumbnail Ref (32 bytes, hash)          │
├─────────────────────────────────────────┤
│ Fetch Timestamp (8 bytes)               │
└─────────────────────────────────────────┘

// Thumbnail stored separately in mesh
// Same encryption as media thumbnails