fix: escape Lucene special characters in fulltext search (#21)

Searching for formatted CNPJs (with / and -) caused a 500 error
because these are Lucene query syntax characters. Escape all special
characters before passing user input to the fulltext index.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: bruno cesar <brunoclz@brunos-MacBook-Pro.local>

api/src/bracc/routers/search.py

@@ -1,3 +1,4 @@
+import re
 from typing import Annotated, Any
 
 from fastapi import APIRouter, Depends, Query
@@ -18,6 +19,13 @@ from bracc.services.public_guard import (
 
 router = APIRouter(prefix="/api/v1", tags=["search"])
 
+_LUCENE_SPECIAL = re.compile(r'([+\-&|!(){}[\]^"~*?:\\/])')
+
+
+def _escape_lucene(query: str) -> str:
+    """Escape Lucene special characters so user input is treated as literals."""
+    return _LUCENE_SPECIAL.sub(r"\\\1", query)
+
 
 def _extract_name(node: Any, labels: list[str]) -> str:
     props = dict(node)
@@ -50,7 +58,7 @@ async def search_entities(
         session,
         "search",
         {
-            "query": q,
+            "query": _escape_lucene(q),
             "entity_type": type_filter,
             "skip": skip,
             "limit": size,

api/tests/unit/test_search.py

@@ -1,6 +1,21 @@
 import pytest
 from httpx import AsyncClient
 
+from bracc.routers.search import _escape_lucene
+
+
+def test_escape_lucene_cnpj() -> None:
+    assert _escape_lucene("00.000.000/0001-00") == "00.000.000\\/0001\\-00"
+
+
+def test_escape_lucene_plain_text() -> None:
+    assert _escape_lucene("silva construcoes") == "silva construcoes"
+
+
+def test_escape_lucene_all_special_chars() -> None:
+    for ch in r'+-&|!(){}[]^"~*?:\/':
+        assert f"\\{ch}" in _escape_lucene(ch)
+
 
 @pytest.mark.anyio
 async def test_search_rejects_short_query(client: AsyncClient) -> None: