WIP checkpoint: Text filtering service + profanity config

backend/alembic/env.py

@@ -8,7 +8,7 @@ from sqlalchemy.ext.asyncio import create_async_engine
 
 from app.config import settings
 from app.database import Base
-from app.models import user, session, world, asset, friendship, follow, block  # noqa: F401
+from app.models import user, session, world, asset  # noqa: F401
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.

backend/alembic/versions/0002_social_graph.py

@@ -1,136 +0,0 @@
-"""social graph: friendships, follows, blocks
-
-Revision ID: 0002_social_graph
-Revises: 0001_initial
-Create Date: 2026-08-18 00:00:00.000000
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-# revision identifiers, used by Alembic.
-revision: str = "0002_social_graph"
-down_revision: Union[str, None] = "0001_initial"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    """Create friendships, follows, and blocks tables."""
-    op.create_table(
-        "friendships",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("requester_id", sa.Integer(), nullable=False),
-        sa.Column("addressee_id", sa.Integer(), nullable=False),
-        sa.Column("status", sa.String(length=20), server_default="pending", nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
-        sa.CheckConstraint(
-            "status IN ('pending', 'accepted')",
-            name="ck_friendships_status",
-        ),
-        sa.CheckConstraint(
-            "requester_id <> addressee_id",
-            name="ck_friendships_no_self",
-        ),
-        sa.ForeignKeyConstraint(
-            ["addressee_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["requester_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint(
-            "requester_id",
-            "addressee_id",
-            name="uq_friendships_requester_addressee",
-        ),
-    )
-    op.create_index(op.f("ix_friendships_id"), "friendships", ["id"], unique=False)
-    op.create_index(op.f("ix_friendships_addressee_id"), "friendships", ["addressee_id"], unique=False)
-    op.create_index(op.f("ix_friendships_requester_id"), "friendships", ["requester_id"], unique=False)
-
-    op.create_table(
-        "follows",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("follower_id", sa.Integer(), nullable=False),
-        sa.Column("followed_id", sa.Integer(), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.CheckConstraint(
-            "follower_id <> followed_id",
-            name="ck_follows_no_self",
-        ),
-        sa.ForeignKeyConstraint(
-            ["followed_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["follower_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint(
-            "follower_id",
-            "followed_id",
-            name="uq_follows_follower_followed",
-        ),
-    )
-    op.create_index(op.f("ix_follows_id"), "follows", ["id"], unique=False)
-    op.create_index(op.f("ix_follows_followed_id"), "follows", ["followed_id"], unique=False)
-    op.create_index(op.f("ix_follows_follower_id"), "follows", ["follower_id"], unique=False)
-
-    op.create_table(
-        "blocks",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("blocker_id", sa.Integer(), nullable=False),
-        sa.Column("blocked_id", sa.Integer(), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.CheckConstraint(
-            "blocker_id <> blocked_id",
-            name="ck_blocks_no_self",
-        ),
-        sa.ForeignKeyConstraint(
-            ["blocked_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["blocker_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint(
-            "blocker_id",
-            "blocked_id",
-            name="uq_blocks_blocker_blocked",
-        ),
-    )
-    op.create_index(op.f("ix_blocks_id"), "blocks", ["id"], unique=False)
-    op.create_index(op.f("ix_blocks_blocked_id"), "blocks", ["blocked_id"], unique=False)
-    op.create_index(op.f("ix_blocks_blocker_id"), "blocks", ["blocker_id"], unique=False)
-
-
-def downgrade() -> None:
-    """Drop friendships, follows, and blocks tables."""
-    op.drop_index(op.f("ix_blocks_blocker_id"), table_name="blocks")
-    op.drop_index(op.f("ix_blocks_blocked_id"), table_name="blocks")
-    op.drop_index(op.f("ix_blocks_id"), table_name="blocks")
-    op.drop_table("blocks")
-
-    op.drop_index(op.f("ix_follows_follower_id"), table_name="follows")
-    op.drop_index(op.f("ix_follows_followed_id"), table_name="follows")
-    op.drop_index(op.f("ix_follows_id"), table_name="follows")
-    op.drop_table("follows")
-
-    op.drop_index(op.f("ix_friendships_requester_id"), table_name="friendships")
-    op.drop_index(op.f("ix_friendships_addressee_id"), table_name="friendships")
-    op.drop_index(op.f("ix_friendships_id"), table_name="friendships")
-    op.drop_table("friendships")

backend/app/models/__init__.py

@@ -2,17 +2,5 @@ from app.models.user import User
 from app.models.session import Session
 from app.models.world import World
 from app.models.asset import Asset
-from app.models.friendship import Friendship, FriendshipStatus
-from app.models.follow import Follow
-from app.models.block import Block
 
-__all__ = [
-    "User",
-    "Session",
-    "World",
-    "Asset",
-    "Friendship",
-    "FriendshipStatus",
-    "Follow",
-    "Block",
-]
+__all__ = ["User", "Session", "World", "Asset"]

backend/app/models/block.py

@@ -1,48 +0,0 @@
-"""Block model: a hard deny that also hides content and prevents DMs."""
-
-from sqlalchemy import CheckConstraint, Column, DateTime, ForeignKey, Integer, UniqueConstraint
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-
-from app.database import Base
-
-
-class Block(Base):
-    __tablename__ = "blocks"
-    __table_args__ = (
-        UniqueConstraint(
-            "blocker_id",
-            "blocked_id",
-            name="uq_blocks_pair",
-        ),
-        CheckConstraint(
-            "blocker_id <> blocked_id",
-            name="ck_blocks_no_self",
-        ),
-    )
-
-    id = Column(Integer, primary_key=True, index=True)
-    blocker_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    blocked_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-
-    blocker = relationship(
-        "User",
-        foreign_keys=[blocker_id],
-        back_populates="blocks_issued",
-    )
-    blocked = relationship(
-        "User",
-        foreign_keys=[blocked_id],
-        back_populates="blocks_received",
-    )

backend/app/models/follow.py

@@ -1,48 +0,0 @@
-"""Follow model: a one-way relationship requiring no approval."""
-
-from sqlalchemy import CheckConstraint, Column, DateTime, ForeignKey, Integer, UniqueConstraint
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-
-from app.database import Base
-
-
-class Follow(Base):
-    __tablename__ = "follows"
-    __table_args__ = (
-        UniqueConstraint(
-            "follower_id",
-            "followed_id",
-            name="uq_follows_pair",
-        ),
-        CheckConstraint(
-            "follower_id <> followed_id",
-            name="ck_follows_no_self",
-        ),
-    )
-
-    id = Column(Integer, primary_key=True, index=True)
-    follower_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    followed_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-
-    follower = relationship(
-        "User",
-        foreign_keys=[follower_id],
-        back_populates="following",
-    )
-    followed = relationship(
-        "User",
-        foreign_keys=[followed_id],
-        back_populates="followers",
-    )

backend/app/models/friendship.py

@@ -1,74 +0,0 @@
-"""Friendship model: a one-directional request that becomes mutual on accept."""
-
-from sqlalchemy import (
-    CheckConstraint,
-    Column,
-    DateTime,
-    ForeignKey,
-    Integer,
-    String,
-    UniqueConstraint,
-)
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-
-from app.database import Base
-
-
-class FriendshipStatus:
-    """String values for the friendship.status column."""
-
-    PENDING = "pending"
-    ACCEPTED = "accepted"
-
-
-class Friendship(Base):
-    __tablename__ = "friendships"
-    __table_args__ = (
-        UniqueConstraint(
-            "requester_id",
-            "addressee_id",
-            name="uq_friendships_pair",
-        ),
-        CheckConstraint(
-            "requester_id <> addressee_id",
-            name="ck_friendships_no_self",
-        ),
-        CheckConstraint(
-            "status IN ('pending', 'accepted')",
-            name="ck_friendships_status",
-        ),
-    )
-
-    id = Column(Integer, primary_key=True, index=True)
-    requester_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    addressee_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    status = Column(
-        String(20),
-        nullable=False,
-        default=FriendshipStatus.PENDING,
-        server_default=FriendshipStatus.PENDING,
-    )
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
-
-    requester = relationship(
-        "User",
-        foreign_keys=[requester_id],
-        back_populates="sent_friend_requests",
-    )
-    addressee = relationship(
-        "User",
-        foreign_keys=[addressee_id],
-        back_populates="received_friend_requests",
-    )

backend/app/models/user.py

@@ -19,41 +19,3 @@ class User(Base):
     sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
     worlds = relationship("World", back_populates="owner")
     assets = relationship("Asset", back_populates="owner")
-
-    # Social graph
-    sent_friend_requests = relationship(
-        "Friendship",
-        foreign_keys="Friendship.requester_id",
-        back_populates="requester",
-        cascade="all, delete-orphan",
-    )
-    received_friend_requests = relationship(
-        "Friendship",
-        foreign_keys="Friendship.addressee_id",
-        back_populates="addressee",
-        cascade="all, delete-orphan",
-    )
-    following = relationship(
-        "Follow",
-        foreign_keys="Follow.follower_id",
-        back_populates="follower",
-        cascade="all, delete-orphan",
-    )
-    followers = relationship(
-        "Follow",
-        foreign_keys="Follow.followed_id",
-        back_populates="followed",
-        cascade="all, delete-orphan",
-    )
-    blocks_issued = relationship(
-        "Block",
-        foreign_keys="Block.blocker_id",
-        back_populates="blocker",
-        cascade="all, delete-orphan",
-    )
-    blocks_received = relationship(
-        "Block",
-        foreign_keys="Block.blocked_id",
-        back_populates="blocked",
-        cascade="all, delete-orphan",
-    )

backend/app/services/__init__.py

@@ -0,0 +1 @@
+"""Application services."""

backend/app/services/text_filter.py

@@ -0,0 +1,340 @@
+"""Pluggable server-side text filtering service.
+
+Provides a ``TextFilter`` protocol with a deterministic default
+implementation (profanity/term list with normalization) and a hook
+for third-party providers.
+
+Usage::
+
+    from app.services.text_filter import TextFilter, FilterResult, \
+        ProfanityTextFilter, get_text_filter
+
+    # Default factory reads config from the path below
+    filt = get_text_filter()
+    result = filt.check("Hello wor1d!")
+    # result.action == FilterAction.ALLOW
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import unicodedata
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Enums / Data classes
+# ---------------------------------------------------------------------------
+
+
+class FilterAction(str, Enum):
+    """Action the filter wants the caller to take."""
+
+    ALLOW = "allow"
+    REDACT = "redact"
+    REJECT = "reject"
+
+
+@dataclass(frozen=True)
+class FilterResult:
+    """Immutable result of a single ``TextFilter.check()`` call.
+
+    Attributes:
+        action: What to do with the message.
+        filtered_text: The text after redaction (may equal *text* if
+            action is ``ALLOW``).
+        matched_terms: Sorted list of terms that triggered the filter.
+    """
+
+    action: FilterAction
+    filtered_text: str
+    matched_terms: list[str] = field(default_factory=list)
+
+    @property
+    def is_allowed(self) -> bool:
+        return self.action == FilterAction.ALLOW
+
+    @property
+    def is_rejected(self) -> bool:
+        return self.action == FilterAction.REJECT
+
+    @property
+    def is_redacted(self) -> bool:
+        return self.action == FilterAction.REDACT
+
+
+# ---------------------------------------------------------------------------
+# Protocol / abstract base
+# ---------------------------------------------------------------------------
+
+
+class TextFilter(ABC):
+    """Protocol for server-side text filters.
+
+    Every concrete filter must implement ``check()``.  The default
+    implementation (``ProfanityTextFilter``) is deterministic and
+    requires no external service.  A third-party provider can be
+    plugged in by subclassing ``TextFilter`` and overriding ``check``.
+    """
+
+    @abstractmethod
+    def check(self, text: str) -> FilterResult:
+        """Analyse *text* and return a ``FilterResult``.
+
+        Args:
+            text: Raw message text to filter.
+
+        Returns:
+            A ``FilterResult`` with the decision and any redacted text.
+        """
+
+
+# ---------------------------------------------------------------------------
+# Normalisation helpers
+# ---------------------------------------------------------------------------
+
+# Common leetspeak substitutions (char -> set of possible originals)
+_LEETSPEAK: dict[str, str] = {
+    "0": "o",
+    "1": "i",
+    "3": "e",
+    "4": "a",
+    "5": "s",
+    "7": "t",
+    "8": "b",
+    "9": "g",
+    "@": "a",
+}
+
+# Normalise separators that are often used to obfuscate words
+_SEPARATORS = re.compile(r"[\s_\-\.]+")
+
+
+def _normalize(text: str) -> str:
+    """Case-fold, strip diacritics, and replace leetspeak / separators.
+
+    This produces a canonical form for matching against the term list.
+    """
+    # Case-fold
+    text = text.casefold()
+    # Strip diacritics (e.g. é -> e)
+    text = unicodedata.normalize("NFKD", text)
+    text = "".join(c for c in text if not unicodedata.combining(c))
+    # Replace leetspeak
+    normalized = ""
+    for ch in text:
+        normalized += _LEETSPEAK.get(ch, ch)
+    # Collapse separators
+    normalized = _SEPARATORS.sub("", normalized)
+    return normalized
+
+
+# ---------------------------------------------------------------------------
+# Default implementation
+# ---------------------------------------------------------------------------
+
+# Default config path (relative to project root)
+_DEFAULT_CONFIG_PATH = Path(__file__).resolve().parent.parent.parent / "data" / "text_filter_config.json"
+
+
+@dataclass
+class _FilterPolicy:
+    """Filtering policy loaded from config."""
+
+    mode: str  # "redact" or "reject"
+    redaction_char: str = "*"
+    # Minimum term length to consider (avoids matching single chars)
+    min_term_length: int = 3
+    # If True, match terms case-insensitively after normalisation
+    case_insensitive: bool = True
+    # If True, match whole words only (after normalisation)
+    whole_word: bool = True
+
+
+class ProfanityTextFilter(TextFilter):
+    """Deterministic text filter backed by a JSON term list.
+
+    The config file is a JSON object with:
+
+    .. code-block:: json
+
+        {
+            "mode": "redact",
+            "redaction_char": "*",
+            "min_term_length": 3,
+            "case_insensitive": true,
+            "whole_word": true,
+            "terms": ["badword", "another", ...]
+        }
+
+    Terms are matched after normalisation (case-fold, leetspeak
+    substitution, separator removal, diacritic stripping).
+    """
+
+    def __init__(
+        self,
+        config_path: str | Path | None = None,
+        terms: list[str] | None = None,
+        policy: _FilterPolicy | None = None,
+    ) -> None:
+        """
+        Args:
+            config_path: Path to a JSON config file.  Ignored if *terms*
+                is provided.
+            terms: Inline list of terms (overrides config file).
+            policy: Filter policy.  Defaults to a redact policy.
+        """
+        if terms is not None:
+            self._terms: list[str] = [t.lower() for t in terms]
+        elif config_path is not None:
+            self._terms = self._load_terms(Path(config_path))
+        else:
+            # Try default path
+            if _DEFAULT_CONFIG_PATH.exists():
+                self._terms = self._load_terms(_DEFAULT_CONFIG_PATH)
+            else:
+                self._terms = []
+
+        self._policy = policy or _FilterPolicy(mode="redact")
+        # Pre-compile patterns for each term
+        self._patterns: list[tuple[re.Pattern[str], str]] = []
+        for term in self._terms:
+            if len(term) < self._policy.min_term_length:
+                continue
+            if self._policy.whole_word:
+                pattern = re.compile(
+                    r"(?<!\w)" + re.escape(term) + r"(?!\w)",
+                    re.IGNORECASE if self._policy.case_insensitive else 0,
+                )
+            else:
+                pattern = re.compile(
+                    re.escape(term),
+                    re.IGNORECASE if self._policy.case_insensitive else 0,
+                )
+            self._patterns.append((pattern, term))
+
+    # -- config loading --------------------------------------------------
+
+    @staticmethod
+    def _load_terms(config_path: Path) -> list[str]:
+        """Load terms from a JSON config file."""
+        with open(config_path, "r", encoding="utf-8") as f:
+            data: dict[str, Any] = json.load(f)
+
+        terms: list[str] = []
+        for raw in data.get("terms", []):
+            term = str(raw).strip()
+            if term:
+                terms.append(term.casefold())
+        return terms
+
+    # -- public API ------------------------------------------------------
+
+    def check(self, text: str) -> FilterResult:
+        """Check *text* against the loaded term list.
+
+        Returns a ``FilterResult`` with the appropriate action,
+        filtered text, and matched terms.
+        """
+        if not text:
+            return FilterResult(
+                action=FilterAction.ALLOW,
+                filtered_text=text,
+                matched_terms=[],
+            )
+
+        normalized = _normalize(text)
+        matched_terms: list[str] = []
+
+        # Collect all matches
+        for pattern, term in self._patterns:
+            if pattern.search(normalized):
+                if term not in matched_terms:
+                    matched_terms.append(term)
+
+        if not matched_terms:
+            return FilterResult(
+                action=FilterAction.ALLOW,
+                filtered_text=text,
+                matched_terms=[],
+            )
+
+        matched_terms.sort()
+
+        # Build filtered text by replacing matched terms
+        filtered = text
+        for term in matched_terms:
+            norm_term = _normalize(term)
+            # Find all occurrences in the normalised text and replace in original
+            # We need to map positions from normalised text back to original
+            filtered = self._replace_terms(filtered, term, norm_term)
+
+        action = FilterAction.REJECT if self._policy.mode == "reject" else FilterAction.REDACT
+
+        return FilterResult(
+            action=action,
+            filtered_text=filtered,
+            matched_terms=matched_terms,
+        )
+
+    def _replace_terms(
+        self, text: str, term: str, norm_term: str
+    ) -> str:
+        """Replace occurrences of *term* in *text* with redaction chars.
+
+        Uses normalised text for matching but preserves original casing
+        in the output.
+        """
+        norm_text = _normalize(text)
+        norm_term_len = len(norm_term)
+        result_chars = list(text)
+
+        start = 0
+        while start < len(norm_text):
+            idx = norm_text.find(norm_term, start)
+            if idx == -1:
+                break
+            # Replace characters in original text
+            for i in range(idx, min(idx + norm_term_len, len(result_chars))):
+                result_chars[i] = self._policy.redaction_char
+            start = idx + norm_term_len
+
+        return "".join(result_chars)
+
+    @property
+    def terms(self) -> list[str]:
+        """Read-only access to the loaded term list."""
+        return list(self._terms)
+
+    @property
+    def policy(self) -> _FilterPolicy:
+        """Read-only access to the filter policy."""
+        return self._policy
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+
+def get_text_filter(
+    config_path: str | Path | None = None,
+    terms: list[str] | None = None,
+    policy: _FilterPolicy | None = None,
+) -> TextFilter:
+    """Return a ``TextFilter`` instance.
+
+    By default this creates a ``ProfanityTextFilter``.  To use a
+    third-party provider, subclass ``TextFilter`` and pass an
+    instance here instead.
+    """
+    return ProfanityTextFilter(
+        config_path=config_path,
+        terms=terms,
+        policy=policy,
+    )