From 2cd74690cee5187bd662bb517b6f053e337d31c2 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Fri, 12 Jun 2026 13:32:45 +0200
Subject: [PATCH] docs(journey): annotate note field as unsanitized plain text
 in JourneyItem and JourneyItemView
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add Javadoc to the note field warning renderers not to use @html or equivalent
unsafe output — the value is stored verbatim without sanitization.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../familienarchiv/geschichte/journeyitem/JourneyItem.java | 7 +++++--
 .../geschichte/journeyitem/JourneyItemView.java            | 1 +
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItem.java b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItem.java
index 173423d9..d57d7c09 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItem.java
+++ b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItem.java
@@ -38,8 +38,11 @@ public class JourneyItem {
     @JsonIgnore
     private Document document;
 
-    // CWE-79 tripwire: plain text — store verbatim, no sanitization. Any HTML/feed/PDF/email
-    // renderer MUST escape this; only Svelte {note} is auto-safe.
+    /**
+     * Plain text — not HTML-sanitized. Renderers MUST NOT use {@code @html} or equivalent unsafe output.
+     *
+     * <p>CWE-79 tripwire: stored verbatim; only Svelte {note} interpolation is auto-safe.</p>
+     */
     @Column(columnDefinition = "TEXT")
     private String note;
 
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemView.java b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemView.java
index 141860af..1e443299 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemView.java
+++ b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemView.java
@@ -12,5 +12,6 @@ public record JourneyItemView(
         @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
         @Schema(requiredMode = Schema.RequiredMode.REQUIRED) int position,
         DocumentSummary document,
+        /** Plain text — not HTML-sanitized. Renderers MUST NOT use {@code @html} or equivalent unsafe output. */
         String note
 ) {}