feat(validation): implement validateAnnotationStrokes function for safe annotation data handling

feat(rate-limit): add TRUSTED_PROXY_MODE for configurable proxy header trust
feat(comments): validate annotation data structure in comment routes and components

lib/validation.ts

@@ -11,6 +11,57 @@ export function isValidHttpUrl(urlString: string): boolean {
     }
 }
 
+// Matches exactly 6-digit hex colours produced by the annotation canvas (e.g. #FF3B30)
+const ANNOTATION_COLOR_RE = /^#[0-9a-fA-F]{6}$/;
+const MAX_STROKES = 500;
+const MAX_POINTS_PER_STROKE = 2000;
+const MIN_STROKE_WIDTH = 1;
+const MAX_STROKE_WIDTH = 20;
+
+/**
+ * Validates and returns a safe copy of annotation stroke data.
+ *
+ * Accepts only an array of plain stroke objects with the exact shape created
+ * by AnnotationCanvas. Rejects anything that could trigger prototype pollution
+ * or carry unexpected properties into the renderer.
+ *
+ * Returns null when the input is absent or structurally invalid.
+ */
+export function validateAnnotationStrokes(
+    data: unknown
+): { points: { x: number; y: number }[]; color: string; width: number }[] | null {
+    if (data === null || data === undefined) return null;
+    if (!Array.isArray(data)) return null;
+    if (data.length > MAX_STROKES) return null;
+
+    const result: { points: { x: number; y: number }[]; color: string; width: number }[] = [];
+
+    for (const stroke of data) {
+        if (stroke === null || typeof stroke !== 'object' || Array.isArray(stroke)) return null;
+
+        const { points, color, width } = stroke as Record<string, unknown>;
+
+        if (!Array.isArray(points)) return null;
+        if (points.length > MAX_POINTS_PER_STROKE) return null;
+
+        const safePoints: { x: number; y: number }[] = [];
+        for (const pt of points) {
+            if (pt === null || typeof pt !== 'object' || Array.isArray(pt)) return null;
+            const { x, y } = pt as Record<string, unknown>;
+            if (typeof x !== 'number' || !isFinite(x)) return null;
+            if (typeof y !== 'number' || !isFinite(y)) return null;
+            safePoints.push({ x, y });
+        }
+
+        if (typeof color !== 'string' || !ANNOTATION_COLOR_RE.test(color)) return null;
+        if (typeof width !== 'number' || width < MIN_STROKE_WIDTH || width > MAX_STROKE_WIDTH) return null;
+
+        result.push({ points: safePoints, color, width });
+    }
+
+    return result;
+}
+
 /**
  * Validates a URL and returns an error message if invalid
  */