From 8ef5bb38cb34eb92bd457b5a443d7f5575f446c2 Mon Sep 17 00:00:00 2001
From: Benjamin <benjamin@kolapsis.com>
Date: Thu, 5 Feb 2026 23:35:09 +0100
Subject: [PATCH] fix: accept 'ref' as fallback for 'doc' query parameter

Keep backward compatibility for external integrations that still use
the old ?ref= parameter while recommending ?doc= to avoid privacy
extensions blocking.
---
 backend/internal/presentation/api/documents/handler.go | 5 ++++-
 backend/internal/presentation/api/proxy/handler.go     | 5 ++++-
 backend/internal/presentation/handlers/oembed.go       | 5 ++++-
 backend/pkg/web/middleware_embed.go                    | 6 ++++--
 backend/pkg/web/static.go                              | 3 +++
 5 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/backend/internal/presentation/api/documents/handler.go b/backend/internal/presentation/api/documents/handler.go
index 5bac45c..745c221 100644
--- a/backend/internal/presentation/api/documents/handler.go
+++ b/backend/internal/presentation/api/documents/handler.go
@@ -492,8 +492,11 @@ type FindOrCreateDocumentResponse struct {
 func (h *Handler) HandleFindOrCreateDocument(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 
-	// Get reference from query parameter (renamed from "ref" to "doc" to avoid ClearURLs blocking)
+	// "doc" is the primary parameter; "ref" is accepted as fallback for backward compatibility
 	ref := r.URL.Query().Get("doc")
+	if ref == "" {
+		ref = r.URL.Query().Get("ref")
+	}
 	if ref == "" {
 		logger.Logger.Warn("Find or create request missing doc parameter",
 			"remote_addr", r.RemoteAddr)
diff --git a/backend/internal/presentation/api/proxy/handler.go b/backend/internal/presentation/api/proxy/handler.go
index fc6aa12..b1f9d21 100644
--- a/backend/internal/presentation/api/proxy/handler.go
+++ b/backend/internal/presentation/api/proxy/handler.go
@@ -85,8 +85,11 @@ func (h *Handler) HandleProxy(w http.ResponseWriter, r *http.Request) {
 	startTime := time.Now()
 	requestID := getRequestID(r.Context())
 
-	// Extract parameters
+	// "doc" is the primary parameter; "ref" is accepted as fallback for backward compatibility
 	docID := r.URL.Query().Get("doc")
+	if docID == "" {
+		docID = r.URL.Query().Get("ref")
+	}
 	rawURL := r.URL.Query().Get("url")
 
 	// Validate required parameters
diff --git a/backend/internal/presentation/handlers/oembed.go b/backend/internal/presentation/handlers/oembed.go
index ba98c5e..3fda85c 100644
--- a/backend/internal/presentation/handlers/oembed.go
+++ b/backend/internal/presentation/handlers/oembed.go
@@ -44,8 +44,11 @@ func HandleOEmbed(baseURL string) http.HandlerFunc {
 			return
 		}
 
-		// Extract doc ID from query parameters
+		// "doc" is the primary parameter; "ref" is accepted as fallback for backward compatibility
 		docID := parsedURL.Query().Get("doc")
+		if docID == "" {
+			docID = parsedURL.Query().Get("ref")
+		}
 		if docID == "" {
 			logger.Logger.Warn("oEmbed request missing doc parameter in url",
 				"url", urlParam,
diff --git a/backend/pkg/web/middleware_embed.go b/backend/pkg/web/middleware_embed.go
index 7916608..d5e68e7 100644
--- a/backend/pkg/web/middleware_embed.go
+++ b/backend/pkg/web/middleware_embed.go
@@ -50,10 +50,12 @@ func EmbedDocumentMiddleware(
 				return
 			}
 
-			// Get doc ID from query parameter
+			// "doc" is the primary parameter; "ref" is accepted as fallback for backward compatibility
 			docID := r.URL.Query().Get("doc")
 			if docID == "" {
-				// No doc parameter, let SPA handle it
+				docID = r.URL.Query().Get("ref")
+			}
+			if docID == "" {
 				next.ServeHTTP(w, r)
 				return
 			}
diff --git a/backend/pkg/web/static.go b/backend/pkg/web/static.go
index 7e370fb..35bde35 100644
--- a/backend/pkg/web/static.go
+++ b/backend/pkg/web/static.go
@@ -97,6 +97,9 @@ func serveIndexTemplate(w http.ResponseWriter, r *http.Request, file fs.File, ba
 
 func generateMetaTags(r *http.Request, baseURL string, signatureRepo SignatureRepository) string {
 	docID := r.URL.Query().Get("doc")
+	if docID == "" {
+		docID = r.URL.Query().Get("ref")
+	}
 	if docID == "" {
 		return ""
 	}