M3 plugin platform: frontend host, reference plugins, UI kit + docs

Completes M3 (SPEC §11 + §12 acceptance) on top of the backend platform (4e077f1).

Frontend host (§11.3):
- src/plugins/: manifest loader, runtime ESM bundle loader (framework-agnostic
  mount contract), PluginSlot, PluginPage (app.page at /p/*), plugin context
  (scoped api/events/i18n), capabilities hook. Wired slots into ThreadView
  (message.actions/message.banner), MailLayout sidebar (sidebar.section + page nav)
  and Settings→Accounts (settings.page); ws.ts fans out core + plugin.* events.
- plugin-ui.css: theme-aware .wm-* classes so bundles don't re-derive inline styles.

SDK additions:
- CurrentUserId + require_csrf (plugin-router auth), messages.envelope/header,
  actions.set_flags/trash, sdk.enqueue.

Reference plugins (plugins/, installed via webmail.plugins entry points):
- hello: skeleton page-plugin (app.page + plg_hello_note w/ RLS + cron job) —
  install→run→uninstall --drop-data leaves zero residue.
- labels: message.actions + sidebar.section slots, KV only, zero core diffs.
- filters: message.new hook -> match (subject/from/to) -> Mark read / Pin / Delete
  (delete = move thread to Trash via the core path).

docs/plugins.md: full authoring guide + a complete "Unsubscribe button" worked
example (the §12 "writable from docs alone" bar).

Also: conftest resets the arq pool between tests (loop-bound global, like engine/redis).

Gates: backend ruff + mypy --strict (107) + full suite 337; frontend tsc + eslint
+ vitest (11) + vite build.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rcj3TpydMTzTSmU7kunzf8

backend/tests/conftest.py

@@ -43,10 +43,14 @@ async def _reset_global_engine() -> AsyncIterator[None]:
     await get_redis().flushdb()
     yield
     from app.db import dispose_engine
+    from app.queue import close_arq_pool
     from app.redis_client import close_redis
 
     await dispose_engine()
     await close_redis()
+    # The arq enqueue pool is a loop-bound global like the engine/redis; reset it so
+    # a test that enqueues doesn't reuse a pool from a previous (closed) event loop.
+    await close_arq_pool()
 
 
 @pytest_asyncio.fixture

backend/tests/plugins/test_filters_plugin.py

@@ -0,0 +1,156 @@
+"""filters reference plugin: message.new hook match->flag + rule CRUD (SPEC §11, §12 M3).
+
+Fires the hook directly with a message.new payload (as the worker would) and checks
+the DB flag was applied; also exercises the rule CRUD HTTP surface. Hook + KV + slot,
+zero core diffs.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator
+from datetime import UTC, datetime
+
+import httpx
+import pytest
+import pytest_asyncio
+from httpx import ASGITransport
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+from webmail_plugin_filters.hook import on_message_new  # type: ignore[import-not-found]
+
+from app.config import get_settings
+from app.identity.passwords import hash_password
+from app.identity.sessions import create_session
+from app.main import create_app
+from app.models import Account, Mailbox, Message, Thread, User
+from app.plugins.sdk import sdk
+
+
+class _Ctx:
+    user_id: uuid.UUID
+    message_id: uuid.UUID
+    thread_id: uuid.UUID
+    sm: async_sessionmaker  # type: ignore[type-arg]
+    client: httpx.AsyncClient
+
+
+@pytest_asyncio.fixture
+async def ctx() -> AsyncIterator[_Ctx]:
+    engine = create_async_engine(get_settings().database_url, poolclass=NullPool)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+    c = _Ctx()
+    c.sm = sm
+    async with sm() as s:
+        user = User(
+            handle=f"fl{uuid.uuid4().hex[:8]}@test.local", password_hash=hash_password("pw")
+        )
+        s.add(user)
+        await s.flush()
+        account = Account(
+            user_id=user.id, email="me@example.com", imap_config={}, smtp_config={},
+            secret_ct=b"", discovery_src="manual",
+        )
+        s.add(account)
+        await s.flush()
+        mbox = Mailbox(account_id=account.id, user_id=user.id, path="INBOX", special_use="inbox")
+        trash = Mailbox(account_id=account.id, user_id=user.id, path="Trash", special_use="trash")
+        s.add_all([mbox, trash])
+        await s.flush()
+        thread = Thread(
+            user_id=user.id, subject_norm="your invoice 123", last_message_at=datetime.now(UTC)
+        )
+        s.add(thread)
+        await s.flush()
+        msg = Message(
+            user_id=user.id, account_id=account.id, mailbox_id=mbox.id, uid=1,
+            thread_id=thread.id,
+            subject="Your Invoice 123",
+            from_addr=[{"name": "Billing", "email": "billing@acme.com"}],
+            to_addr=[{"name": "Me", "email": "me@example.com"}],
+            flags=[], internal_date=datetime.now(UTC), blob_sha256="",
+        )
+        s.add(msg)
+        await s.commit()
+        c.user_id, c.message_id, c.thread_id = user.id, msg.id, thread.id
+
+    token = await create_session(c.user_id, "pytest")
+    c.client = httpx.AsyncClient(
+        transport=ASGITransport(app=create_app()),
+        base_url="http://testserver",
+        cookies={"session": token, "csrf": "csrf"},
+        headers={"X-CSRF": "csrf"},
+    )
+    try:
+        yield c
+    finally:
+        await c.client.aclose()
+        async with sm() as s:
+            await s.execute(delete(User).where(User.id == c.user_id))
+            await s.commit()
+        await engine.dispose()
+
+
+async def _flags(ctx: _Ctx) -> list[str]:
+    async with ctx.sm() as s:
+        msg = await s.scalar(select(Message).where(Message.id == ctx.message_id))
+        return list(msg.flags) if msg else []
+
+
+async def test_hook_applies_flag_on_match(ctx: _Ctx) -> None:
+    await sdk("filters").kv(ctx.user_id).set(
+        "_rules", [{"field": "subject", "contains": "invoice", "action": "read"}]
+    )
+    await on_message_new({"user_id": str(ctx.user_id), "message_id": str(ctx.message_id)})
+    assert "\\Seen" in await _flags(ctx)
+
+
+async def test_hook_no_match_leaves_flags(ctx: _Ctx) -> None:
+    await sdk("filters").kv(ctx.user_id).set(
+        "_rules", [{"field": "from", "contains": "newsletter@somewhere", "action": "pin"}]
+    )
+    await on_message_new({"user_id": str(ctx.user_id), "message_id": str(ctx.message_id)})
+    assert await _flags(ctx) == []
+
+
+async def test_hook_pin_applies_flagged(ctx: _Ctx) -> None:
+    await sdk("filters").kv(ctx.user_id).set(
+        "_rules", [{"field": "from", "contains": "billing@acme", "action": "pin"}]
+    )
+    await on_message_new({"user_id": str(ctx.user_id), "message_id": str(ctx.message_id)})
+    assert "\\Flagged" in await _flags(ctx)  # "pin" == the \Flagged flag in this app
+
+
+async def test_hook_matches_on_to(ctx: _Ctx) -> None:
+    # Multi-account setups match on the recipient address.
+    await sdk("filters").kv(ctx.user_id).set(
+        "_rules", [{"field": "to", "contains": "me@example.com", "action": "read"}]
+    )
+    await on_message_new({"user_id": str(ctx.user_id), "message_id": str(ctx.message_id)})
+    assert "\\Seen" in await _flags(ctx)
+
+
+async def test_hook_trash_moves_thread_to_trash(
+    ctx: _Ctx, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    calls: list[tuple[object, ...]] = []
+
+    async def fake_enqueue(name: str, *args: object, **kwargs: object) -> None:
+        calls.append((name, *args))
+
+    # trash() enqueues the same job the UI Delete uses (imported from app.queue).
+    monkeypatch.setattr("app.queue.enqueue_job", fake_enqueue)
+    await sdk("filters").kv(ctx.user_id).set(
+        "_rules", [{"field": "subject", "contains": "invoice", "action": "trash"}]
+    )
+    await on_message_new({"user_id": str(ctx.user_id), "message_id": str(ctx.message_id)})
+    assert ("move_thread_to_folder_job", str(ctx.thread_id), "trash") in calls
+
+
+async def test_rules_crud_over_http(ctx: _Ctx) -> None:
+    assert (await ctx.client.get("/api/plugins/filters/rules")).json() == []
+    rule = {"field": "subject", "contains": "invoice", "action": "pin"}
+    r = await ctx.client.put("/api/plugins/filters/rules", json={"rules": [rule]})
+    assert r.status_code == 200 and r.json()["count"] == 1
+    assert (await ctx.client.get("/api/plugins/filters/rules")).json() == [rule]

backend/tests/plugins/test_hello_plugin.py

@@ -0,0 +1,103 @@
+"""End-to-end test of the hello reference plugin (SPEC §11, §12 M3 acceptance).
+
+Exercises the whole vertical against the real HTTP surface: entry-point discovery
+-> router mounted at /api/plugins/hello -> SDK auth (CurrentUserId) -> RLS-scoped
+session -> the plg_hello_note table. Also proves per-user isolation: one user never
+sees another's notes. Requires the plugin installed + `install hello` run.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator
+
+import httpx
+import pytest_asyncio
+from httpx import ASGITransport
+from sqlalchemy import delete, text
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import get_settings
+from app.identity.passwords import hash_password
+from app.identity.sessions import create_session
+from app.main import create_app
+from app.models import User
+
+
+async def _mk_user(sm: async_sessionmaker) -> uuid.UUID:  # type: ignore[type-arg]
+    async with sm() as s:
+        user = User(
+            handle=f"hp{uuid.uuid4().hex[:8]}@test.local", password_hash=hash_password("pw")
+        )
+        s.add(user)
+        await s.commit()
+        return user.id
+
+
+class _Ctx:
+    user_a: uuid.UUID
+    user_b: uuid.UUID
+    client_a: httpx.AsyncClient
+    client_b: httpx.AsyncClient
+
+
+@pytest_asyncio.fixture
+async def ctx() -> AsyncIterator[_Ctx]:
+    engine = create_async_engine(get_settings().database_url, poolclass=NullPool)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+    c = _Ctx()
+    c.user_a = await _mk_user(sm)
+    c.user_b = await _mk_user(sm)
+    transport = ASGITransport(app=create_app())
+
+    async def client(uid: uuid.UUID) -> httpx.AsyncClient:
+        token = await create_session(uid, "pytest")
+        return httpx.AsyncClient(
+            transport=transport,
+            base_url="http://testserver",
+            cookies={"session": token, "csrf": "csrf"},
+            headers={"X-CSRF": "csrf"},
+        )
+
+    c.client_a = await client(c.user_a)
+    c.client_b = await client(c.user_b)
+    try:
+        yield c
+    finally:
+        await c.client_a.aclose()
+        await c.client_b.aclose()
+        async with sm() as s:
+            await s.execute(
+                delete(User).where(User.id.in_([c.user_a, c.user_b]))
+            )
+            await s.execute(
+                text("DELETE FROM plg_hello_note WHERE user_id IN (:a, :b)"),
+                {"a": str(c.user_a), "b": str(c.user_b)},
+            )
+            await s.commit()
+        await engine.dispose()
+
+
+async def test_notes_crud_and_rls_isolation(ctx: _Ctx) -> None:
+    # A adds a note and reads it back.
+    r = await ctx.client_a.post("/api/plugins/hello/notes", json={"body": "a-note"})
+    assert r.status_code == 200
+    a_notes = (await ctx.client_a.get("/api/plugins/hello/notes")).json()
+    assert [n["body"] for n in a_notes] == ["a-note"]
+
+    # B sees none of A's notes (RLS), then adds and sees only its own.
+    assert (await ctx.client_b.get("/api/plugins/hello/notes")).json() == []
+    await ctx.client_b.post("/api/plugins/hello/notes", json={"body": "b-note"})
+    b_notes = (await ctx.client_b.get("/api/plugins/hello/notes")).json()
+    assert [n["body"] for n in b_notes] == ["b-note"]
+
+    # A still sees only its own note.
+    a_again = (await ctx.client_a.get("/api/plugins/hello/notes")).json()
+    assert [n["body"] for n in a_again] == ["a-note"]
+
+
+async def test_notes_requires_auth(ctx: _Ctx) -> None:
+    transport = ASGITransport(app=create_app())
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as anon:
+        assert (await anon.get("/api/plugins/hello/notes")).status_code == 401

backend/tests/plugins/test_labels_plugin.py

@@ -0,0 +1,102 @@
+"""End-to-end test of the labels reference plugin (SPEC §11, §12 M3 acceptance).
+
+Slots + KV only, zero core diffs. Verifies the real HTTP surface (discovery ->
+router -> auth -> KV) and that labels are per-user isolated by construction: one
+user never sees another's labels or label set. Requires the plugin installed.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator
+
+import httpx
+import pytest_asyncio
+from httpx import ASGITransport
+from sqlalchemy import delete
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import get_settings
+from app.identity.passwords import hash_password
+from app.identity.sessions import create_session
+from app.main import create_app
+from app.models import User
+
+
+class _Ctx:
+    users: list[uuid.UUID]
+    client_a: httpx.AsyncClient
+    client_b: httpx.AsyncClient
+
+
+@pytest_asyncio.fixture
+async def ctx() -> AsyncIterator[_Ctx]:
+    engine = create_async_engine(get_settings().database_url, poolclass=NullPool)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+    c = _Ctx()
+    c.users = []
+    async with sm() as s:
+        for _ in range(2):
+            user = User(
+                handle=f"lb{uuid.uuid4().hex[:8]}@test.local", password_hash=hash_password("pw")
+            )
+            s.add(user)
+            await s.flush()
+            c.users.append(user.id)
+        await s.commit()
+
+    transport = ASGITransport(app=create_app())
+
+    async def client(uid: uuid.UUID) -> httpx.AsyncClient:
+        token = await create_session(uid, "pytest")
+        return httpx.AsyncClient(
+            transport=transport,
+            base_url="http://testserver",
+            cookies={"session": token, "csrf": "csrf"},
+            headers={"X-CSRF": "csrf"},
+        )
+
+    c.client_a = await client(c.users[0])
+    c.client_b = await client(c.users[1])
+    try:
+        yield c
+    finally:
+        await c.client_a.aclose()
+        await c.client_b.aclose()
+        async with sm() as s:  # cascade drops the users' plugin_kv rows
+            await s.execute(delete(User).where(User.id.in_(c.users)))
+            await s.commit()
+        await engine.dispose()
+
+
+async def test_labels_crud_and_per_user_isolation(ctx: _Ctx) -> None:
+    mid = "msg-1"
+    msg_path = f"/api/plugins/labels/message/{mid}/labels"
+
+    # A labels a message; reads it back; the label joins A's known set.
+    await ctx.client_a.put(msg_path, json={"labels": ["work", "urgent"]})
+    assert (await ctx.client_a.get(msg_path)).json() == [
+        "urgent",
+        "work",
+    ]
+    assert (await ctx.client_a.get("/api/plugins/labels/labels")).json() == ["urgent", "work"]
+
+    # B sees neither A's per-message labels nor A's label set (KV is per-user).
+    assert (await ctx.client_b.get(msg_path)).json() == []
+    assert (await ctx.client_b.get("/api/plugins/labels/labels")).json() == []
+
+    # Empties/whitespace are dropped and the set is deduped/sorted.
+    await ctx.client_a.put(msg_path, json={"labels": ["work", " ", "later"]})
+    assert (await ctx.client_a.get(msg_path)).json() == ["later", "work"]
+    assert (await ctx.client_a.get("/api/plugins/labels/labels")).json() == [
+        "later",
+        "urgent",
+        "work",
+    ]
+
+
+async def test_labels_requires_auth(ctx: _Ctx) -> None:
+    transport = ASGITransport(app=create_app())
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as anon:
+        assert (await anon.get("/api/plugins/labels/labels")).status_code == 401

backend/tests/plugins/test_sdk_messages.py

@@ -0,0 +1,67 @@
+"""SDK message-read helpers: envelope + raw header access (SPEC §11)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from email.message import EmailMessage
+
+from sqlalchemy import delete
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import get_settings
+from app.identity.passwords import hash_password
+from app.indexer import blobstore
+from app.models import Account, Mailbox, Message, User
+from app.plugins.sdk import sdk
+
+
+async def test_messages_header_reads_raw_header() -> None:
+    engine = create_async_engine(get_settings().database_url, poolclass=NullPool)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+    async with sm() as s:
+        user = User(
+            handle=f"hd{uuid.uuid4().hex[:8]}@test.local", password_hash=hash_password("pw")
+        )
+        s.add(user)
+        await s.flush()
+        account = Account(
+            user_id=user.id, email="me@example.com", imap_config={}, smtp_config={},
+            secret_ct=b"", discovery_src="manual",
+        )
+        s.add(account)
+        await s.flush()
+        mbox = Mailbox(account_id=account.id, user_id=user.id, path="INBOX", special_use="inbox")
+        s.add(mbox)
+        await s.flush()
+
+        raw = EmailMessage()
+        raw["Subject"] = "Weekly digest"
+        raw["From"] = "news@list.example"
+        raw["List-Unsubscribe"] = "<https://list.example/unsub?u=42>"
+        raw.set_content("hello")
+        sha = blobstore.store(user.id, raw.as_bytes())
+
+        msg = Message(
+            user_id=user.id, account_id=account.id, mailbox_id=mbox.id, uid=1,
+            subject="Weekly digest", flags=[], internal_date=datetime.now(UTC), blob_sha256=sha,
+        )
+        s.add(msg)
+        await s.commit()
+        user_id, message_id = user.id, msg.id
+
+    try:
+        messages = sdk("unsubscribe").messages
+        assert await messages.header(user_id, message_id, "List-Unsubscribe") == (
+            "<https://list.example/unsub?u=42>"
+        )
+        assert await messages.header(user_id, message_id, "X-Nope") is None
+        assert await messages.header(user_id, uuid.uuid4(), "List-Unsubscribe") is None
+        # Another user can't read this message's headers.
+        assert await messages.header(uuid.uuid4(), message_id, "List-Unsubscribe") is None
+    finally:
+        async with sm() as s:
+            await s.execute(delete(User).where(User.id == user_id))
+            await s.commit()
+        await engine.dispose()