curu-memory 0.2.0__py3-none-any.whl

curu_memory/browser.py

@@ -0,0 +1,396 @@
+"""The read-only browser: HTML pages made on the server (ADR-004).
+
+The pages call the same `Retriever` as the MCP tools and the CLI. Each value from a
+concept is escaped, each body goes through `render_markdown`, and each response has
+a content security policy that blocks scripts. Each route accepts GET and HEAD only.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import re
+from collections.abc import Callable, Sequence
+from html import escape
+from pathlib import PurePosixPath
+from typing import Any
+
+import anyio
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, Response
+from starlette.routing import Route
+
+from curu_memory.access import ANONYMOUS, hidden_space
+from curu_memory.audit import REFUSED, AuditLog
+from curu_memory.config import Settings
+from curu_memory.errors import ConceptNotFound, IndexMissing, InvalidArgument, NoReadableSpace
+from curu_memory.ports import GLOBAL, Embedder
+from curu_memory.render import concept_href, render_markdown
+from curu_memory.retrieval import (
+    DEFAULT_LIMIT,
+    MAX_LIMIT,
+    MAX_QUESTION,
+    Retriever,
+    SearchResult,
+    retriever_for,
+)
+from curu_memory.store_sqlite import SqliteIndexStore
+
+SECURITY_HEADERS = {
+    "Content-Security-Policy": (
+        "default-src 'none'; style-src 'self'; img-src 'self'; media-src 'self'; "
+        "form-action 'self'; "
+        "base-uri 'none'; frame-ancestors 'none'"
+    ),
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+}
+REALM = 'Basic realm="curu-memory"'
+READ_METHODS = ("GET", "HEAD")
+
+STYLE = """
+body { font-family: system-ui, sans-serif; max-width: 52rem; margin: 2rem auto; padding: 0 1rem;
+       line-height: 1.5; color: #1f2328; }
+header a { text-decoration: none; color: inherit; font-weight: 600; }
+form { display: flex; gap: .5rem; margin: 1rem 0; }
+input[type=search] { flex: 1; padding: .4rem; font-size: 1rem; }
+.result { margin-bottom: 1rem; list-style: none; }
+.type, .kind, .space { font-size: .8rem; color: #59636e; border: 1px solid #d1d9e0;
+                       border-radius: 1rem; padding: 0 .5rem; }
+.tags span { font-size: .8rem; background: #eef1f4; border-radius: .3rem; padding: 0 .3rem;
+             margin-right: .3rem; }
+.notice { background: #fff8c5; padding: .5rem; border-radius: .3rem; }
+.broken { color: #8c959f; text-decoration: line-through; }
+.score { color: #59636e; font-size: .8rem; }
+pre { background: #f6f8fa; padding: .5rem; overflow-x: auto; }
+dt { font-weight: 600; }
+figure { margin: 1rem 0; }
+figure img { max-width: 100%; height: auto; border: 1px solid #d1d9e0; }
+figcaption { font-size: .8rem; color: #59636e; }
+"""
+#: A media address is the SHA-256 of the bytes: 64 lowercase hexadecimal characters.
+SHA256 = re.compile(r"[0-9a-f]{64}")
+#: The bytes of an address never change, so a web browser can keep them (research R-3).
+MEDIA_CACHE = "private, max-age=31536000, immutable"
+NO_MEDIA = "No media file has this address."
+#: The range of a Range header that starts after the end of the file.
+UNSATISFIABLE = (-1, -1)
+_RANGE = re.compile(r"bytes=(\d*)-(\d*)")
+
+
+def build_browser(
+    settings: Settings,
+    embedder: Embedder | None = None,
+    token: str | None = None,
+    readable: Callable[[], Sequence[str]] | None = None,
+    audit: AuditLog | None = None,
+    principal: str = ANONYMOUS.label,
+) -> Starlette:
+    """The browser app over the index of the settings.
+
+    With `token`, each request needs HTTP Basic authentication with that password.
+    `readable` gives the readable spaces of each request (ADR-016). Without it, the
+    reader reads `global` only. With `audit`, a refused read of a page or of media in a
+    space without a role writes one line for `principal` (FR-015).
+    """
+    store = SqliteIndexStore(settings.data_dir)
+    retriever = retriever_for(settings, store, embedder)
+    # Denied by default: with no callable, a caller reads global only (ADR-016).
+    spaces_of_request = readable or (lambda: (GLOBAL,))
+
+    def refused_all(action: str) -> None:
+        """A principal with no role in any space is a failed check (ADR-016)."""
+        if audit is not None:
+            audit.write(principal, action, None, REFUSED, "no role in any space")
+
+    def refused(action: str, spaces: Sequence[str], **target: str) -> None:
+        if audit is None:
+            return
+        space = hidden_space(store, spaces, **target)
+        if space is not None:
+            audit.write(principal, action, space, REFUSED, "no role in the space")
+
+    async def home(request: Request) -> Response:
+        response = await _search_page(retriever, request, spaces_of_request(), search=False)
+        if response.status_code == 403:
+            refused_all("page")
+        return response
+
+    async def search(request: Request) -> Response:
+        response = await _search_page(retriever, request, spaces_of_request(), search=True)
+        if response.status_code == 403:
+            refused_all("search")
+        return response
+
+    async def concept(request: Request) -> Response:
+        concept_id = request.path_params["concept_id"]
+        spaces = spaces_of_request()
+        try:
+            detail, links, known = await anyio.to_thread.run_sync(
+                lambda: _concept_parts(retriever, store, concept_id, spaces)
+            )
+        except IndexMissing as error:
+            return _page("No index", f"<p>{escape(error.message)}</p>", 503)
+        except NoReadableSpace as error:
+            refused_all("page")
+            return _page("No access", f"<p>{escape(error.message)}</p>", 403)
+        except ConceptNotFound:
+            await anyio.to_thread.run_sync(lambda: refused("page", spaces, concept_id=concept_id))
+            body = f"<p>No concept has the identifier <code>{escape(concept_id)}</code>.</p>"
+            return _page("Not found", body, 404)
+        return _page(detail.title, _concept_html(detail, links, known))
+
+    async def media(request: Request) -> Response:
+        digest = request.path_params["sha256"]
+        if not SHA256.fullmatch(digest):
+            return Response(NO_MEDIA, status_code=404, media_type="text/plain")
+        spaces = spaces_of_request()
+        found = await anyio.to_thread.run_sync(lambda: store.media_bytes(spaces, digest))
+        # The browser checks the bytes before it sends them (FR-006).
+        if found is None or hashlib.sha256(found[1]).hexdigest() != digest:
+            if found is None and not spaces:
+                refused_all("media")
+            elif found is None:
+                await anyio.to_thread.run_sync(lambda: refused("media", spaces, sha256=digest))
+            return Response(NO_MEDIA, status_code=404, media_type="text/plain")
+        mime, data = found
+        headers = {"Cache-Control": MEDIA_CACHE, "Accept-Ranges": "bytes"}
+        wanted = _byte_range(request.headers.get("range"), len(data))
+        if wanted is None:
+            return Response(data, media_type=mime, headers=headers)
+        if wanted == UNSATISFIABLE:
+            headers["Content-Range"] = f"bytes */{len(data)}"
+            return Response(status_code=416, headers=headers)
+        start, end = wanted
+        headers["Content-Range"] = f"bytes {start}-{end}/{len(data)}"
+        return Response(data[start : end + 1], status_code=206, media_type=mime, headers=headers)
+
+    async def style(request: Request) -> Response:
+        return Response(STYLE, media_type="text/css")
+
+    methods = list(READ_METHODS)
+    routes = [
+        Route("/", home, methods=methods),
+        Route("/search", search, methods=methods),
+        Route("/concepts/{concept_id:path}", concept, methods=methods),
+        Route("/static/style.css", style, methods=methods),
+        Route("/media/{sha256:path}", media, methods=methods),
+    ]
+    middleware = [Middleware(_Gate, token=token)]
+    return Starlette(routes=routes, middleware=middleware)
+
+
+class _Gate(BaseHTTPMiddleware):
+    """The token check and the security headers of each response."""
+
+    def __init__(self, app: Any, token: str | None) -> None:
+        super().__init__(app)
+        self._token = token.encode() if token else None
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        # The browser only reads, so each other method gets 405 on each path, before the token.
+        if request.method not in READ_METHODS:
+            response: Response = Response("The browser only reads.", status_code=405)
+            response.headers["Allow"] = ", ".join(READ_METHODS)
+        elif self._token is not None and not self._allowed(request):
+            response = Response("Give the token as the password.", status_code=401)
+            response.headers["WWW-Authenticate"] = REALM
+        else:
+            response = await call_next(request)
+        response.headers.update(SECURITY_HEADERS)
+        return response
+
+    def _allowed(self, request: Request) -> bool:
+        scheme, _, value = request.headers.get("authorization", "").partition(" ")
+        if scheme.lower() != "basic":
+            return False
+        try:
+            decoded = base64.b64decode(value, validate=True).decode()
+        except (binascii.Error, UnicodeDecodeError):
+            return False
+        _user, _, password = decoded.partition(":")
+        assert self._token is not None
+        return hmac.compare_digest(password.encode(), self._token)
+
+
+async def _search_page(
+    retriever: Retriever, request: Request, spaces: Sequence[str], *, search: bool
+) -> Response:
+    query = request.query_params
+    question = query.get("q", "")
+    types = query.getlist("type")
+    tags = query.getlist("tag")
+    try:
+        limit = int(query.get("limit", DEFAULT_LIMIT))
+    except ValueError:
+        limit = 0
+    form = _form(question, limit if 1 <= limit <= MAX_LIMIT else DEFAULT_LIMIT)
+    if not 1 <= limit <= MAX_LIMIT:
+        return _page("Search", form + f"<p>The limit must be from 1 to {MAX_LIMIT}.</p>", 400)
+    if len(question) > MAX_QUESTION:
+        text = f"<p>The question has more than {MAX_QUESTION} characters.</p>"
+        return _page("Search", form + text, 400)
+    try:
+        if not search or not question.strip():
+            await anyio.to_thread.run_sync(lambda: retriever.index_meta(spaces=spaces))
+            return _page("Search", form)
+        result = await anyio.to_thread.run_sync(
+            lambda: retriever.search(question, limit, types, tags, spaces=spaces)
+        )
+    except IndexMissing as error:
+        return _page("No index", f"<p>{escape(error.message)}</p>", 503)
+    except NoReadableSpace as error:
+        return _page("No access", f"<p>{escape(error.message)}</p>", 403)
+    except InvalidArgument as error:
+        return _page("Search", form + f"<p>{escape(error.message)}</p>", 400)
+    return _page(f"Search: {question}", form + _results_html(result))
+
+
+def _form(question: str, limit: int) -> str:
+    return (
+        '<form method="get" action="/search">'
+        f'<input type="search" name="q" value="{escape(question)}" '
+        'aria-label="Question" placeholder="Ask the knowledge" autofocus>'
+        f'<input type="hidden" name="limit" value="{limit}">'
+        "<button>Search</button></form>"
+    )
+
+
+def _results_html(result: SearchResult) -> str:
+    parts = []
+    if result.notice:
+        parts.append(f'<p class="notice">{escape(result.notice)}</p>')
+    parts.append(f'<p class="score">Mode: {escape(result.mode)}</p><ol>')
+    for hit in result.results:
+        tags = "".join(f"<span>{escape(tag)}</span>" for tag in hit.tags)
+        parts.append(
+            f'<li class="result"><a href="{concept_href(hit.id)}">{escape(hit.title)}</a> '
+            f'<span class="type">{escape(hit.type)}</span> '
+            f'<span class="space">{escape(hit.space)}</span>'
+            f"<p>{escape(hit.description)}</p>"
+            f'<p class="tags">{tags} <span class="score">score {hit.score:.4f}</span></p></li>'
+        )
+    parts.append("</ol>")
+    return "".join(parts)
+
+
+def _concept_parts(
+    retriever: Retriever, store: SqliteIndexStore, concept_id: str, spaces: Sequence[str]
+) -> Any:
+    detail = retriever.get_concept(concept_id, spaces=spaces)
+    links = retriever.neighbours(concept_id, spaces=spaces)
+    targets = _md_targets(detail.body)
+    # A link to a concept in a space that is not readable shows as a missing link.
+    known = set(store.titles(spaces, targets))
+    return detail, links, known
+
+
+_MD_TARGET = re.compile(r"\]\(\s*([^\s)]+\.md)")
+
+
+def _md_targets(body: str) -> list[str]:
+    """The identifiers of the concept files that a body links to."""
+    return [PurePosixPath(target).stem for target in _MD_TARGET.findall(body)]
+
+
+def _concept_html(detail: Any, links: Any, known: set[str]) -> str:
+    tags = "".join(f"<span>{escape(tag)}</span>" for tag in detail.tags)
+    sources = "".join(_source_html(source) for source in detail.sources)
+    fields = (
+        f"<dl><dt>Identifier</dt><dd><code>{escape(detail.id)}</code></dd>"
+        f"<dt>Space</dt><dd><code>{escape(detail.space)}</code></dd>"
+        f"<dt>Type</dt><dd>{escape(detail.type)}</dd>"
+        f"<dt>Status</dt><dd>{escape(detail.status or 'none')}</dd>"
+        f"<dt>File</dt><dd><code>{escape(detail.path)}</code></dd>"
+        f'<dt>Tags</dt><dd class="tags">{tags}</dd></dl>'
+    )
+    return (
+        f'<p class="description">{escape(detail.description)}</p>{fields}'
+        f'<div class="body">{render_markdown(detail.body, known)}</div>'
+        f"{_media_html(detail.media)}"
+        f"<h2>Sources</h2><ul>{sources or '<li>None</li>'}</ul>"
+        f'<h2 id="outgoing">Outgoing links</h2>{_links_html(links.outgoing)}'
+        f'<h2 id="incoming">Incoming links</h2>{_links_html(links.incoming)}'
+    )
+
+
+def _byte_range(header: str | None, size: int) -> tuple[int, int] | None:
+    """The (first, last) byte of one range of a Range header, UNSATISFIABLE, or None.
+
+    A web browser asks for parts of a clip to play it and to seek in it. A header with
+    no range, with more than one range or with another unit gets the whole file (None).
+    """
+    found = _RANGE.fullmatch(header.strip()) if header else None
+    if found is None or found.group(0) == "bytes=-":
+        return None
+    first, last = found.groups()
+    if not first:
+        start, end = max(size - int(last), 0), size - 1
+    else:
+        start = int(first)
+        end = min(int(last), size - 1) if last else size - 1
+    if start >= size or start > end:
+        return UNSATISFIABLE
+    return start, end
+
+
+def _media_html(media: list[Any]) -> str:
+    """A figure for each file, in list order: an image, an audio player or a video player.
+
+    The path is the caption, and the alt text of an image.
+    """
+    if not media:
+        return ""
+    figures = []
+    for item in media:
+        source = f"/media/{escape(item.sha256)}"
+        path = escape(item.path)
+        if item.mime.startswith("audio/"):
+            element = f'<audio controls preload="none" src="{source}"></audio>'
+        elif item.mime.startswith("video/"):
+            element = f'<video controls preload="none" src="{source}"></video>'
+        else:
+            element = f'<img src="{source}" alt="{path}" loading="lazy">'
+        figures.append(f"<figure>{element}<figcaption>{path}</figcaption></figure>")
+    return '<h2 id="media">Media</h2>' + "".join(figures)
+
+
+def _source_html(source: dict[str, Any]) -> str:
+    label = escape(str(source.get("title") or source.get("id") or "source"))
+    details = [
+        escape(str(source[key]))
+        for key in ("resource", "author", "last_modified")
+        if source.get(key)
+    ]
+    return f"<li>{label}" + (f" ({', '.join(details)})" if details else "") + "</li>"
+
+
+def _links_html(links: list[Any]) -> str:
+    if not links:
+        return "<p>None.</p>"
+    items = []
+    for link in links:
+        kind = f'<span class="kind">{escape(link.kind)}</span> '
+        if link.resolved:
+            title = escape(link.title or link.id)
+            items.append(f'<li>{kind}<a href="{concept_href(link.id)}">{title}</a></li>')
+        else:
+            items.append(f'<li>{kind}<span class="broken">{escape(link.id)}</span> (missing)</li>')
+    return "<ul>" + "".join(items) + "</ul>"
+
+
+def _page(title: str, body: str, status: int = 200) -> HTMLResponse:
+    html = (
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        f"<title>{escape(title)} · curu-memory</title>"
+        '<link rel="stylesheet" href="/static/style.css"></head><body>'
+        '<header><a href="/">curu-memory</a></header>'
+        f"<h1>{escape(title)}</h1>{body}</body></html>"
+    )
+    return HTMLResponse(html, status_code=status)