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.

Author: btouchard

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)

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

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,

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
 			}

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 ""
 	}