Phase 7: Bot/extension system

Bot accounts (User rows with is_bot=True), scoped API tokens (read:messages,
write:messages, manage:rooms) authenticated via Authorization: Bearer on both
REST and the WS handshake, live bot WebSocket access on the same /ws/chat
endpoint humans use, message editing (WS "edit" envelope -> message_update
broadcast, fans out cross-instance for free via the existing broadcaster),
incoming webhooks (room-scoped, no auth beyond the URL token), and outgoing
webhooks/event subscriptions (HMAC-SHA256 signed, backgrounded delivery,
creation-time SSRF validation against private/loopback/link-local targets).

Token auth is additive, not a parallel system: a bearer-token-authenticated
bot goes through the exact same room-membership/role checks a session-
authenticated human does everywhere; only read:messages/write:messages are
separately scope-gated (the two message endpoints). manage:rooms scope
enforcement, full per-delivery SSRF re-validation, and bot API rate limiting
were explicitly scoped out (confirmed with the repo owner) as disproportionate
to this phase -- documented as known gaps in backend/README.md rather than
silently skipped.

Admin portal gains a Bots tab (create bots, issue/revoke scoped tokens,
cross-room webhook visibility); RoomInfoPanel gains room-scoped webhook/
subscription management, mirroring how invites already work there. The chat
UI also gets a minimal "edit your own message" affordance -- not asked for
by the issue, but the only practical way to exercise the edit pipeline by
hand instead of only via a scripted bot client.

Along the way: fixed a real bug caught while writing the incoming-webhook
test -- offline-push notification relied on the sender being "connected" to
exclude themselves, true for WS-originated messages but not for the new
webhook path, which has no WS connection for the attributed sender at all.
Now explicitly excluded. Also discovered the REST-only test fixture never
triggered ASGI lifespan, so app.state.broadcaster/presence didn't exist for
it; moved their construction out of the lifespan into create_app() itself
(Redis client construction is synchronous/lazy) so both the WS and
REST-only paths always have them.

New tests/test_bots.py, test_message_edit.py, test_webhooks.py (full suite
now 78/78, stable across repeated runs) plus a scripted end-to-end smoke
test (bot WS join/post/edit, incoming webhook, SSRF rejection, outgoing
delivery) and a full browser walkthrough of the new admin/room UI.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-14 08:12:41 -06:00
co-authored by Claude Sonnet 5
parent 4aa8ef89c5
commit 0ab23c44a7
41 changed files with 2607 additions and 137 deletions
+209
View File
@@ -0,0 +1,209 @@
import uuid
from sqlalchemy import select
from app.models import AdminAuditLog, User
from tests.conftest import login_as, register_and_login
async def _make_admin(db_session, user_id: str) -> None:
user = await db_session.get(User, uuid.UUID(user_id))
user.is_site_admin = True
await db_session.commit()
async def test_create_bot_requires_site_admin(client, db_session):
await register_and_login(client, db_session, username="alice")
resp = await client.post("/api/admin/bots", json={"username": "helper-bot"})
assert resp.status_code == 403
async def test_create_bot_and_issue_token(client, db_session):
admin = await register_and_login(client, db_session, username="admin1")
await _make_admin(db_session, admin["id"])
bot_resp = await client.post("/api/admin/bots", json={"username": "helper-bot"})
assert bot_resp.status_code == 201
bot = bot_resp.json()
assert bot["username"] == "helper-bot"
assert bot["is_active"] is True
token_resp = await client.post(
f"/api/admin/bots/{bot['id']}/tokens",
json={"scopes": ["read:messages", "write:messages"]},
)
assert token_resp.status_code == 201
token = token_resp.json()
assert token["token"].startswith("kit_")
assert token["scopes"] == ["read:messages", "write:messages"]
result = await db_session.execute(
select(AdminAuditLog).where(AdminAuditLog.target_id == uuid.UUID(bot["id"]))
)
actions = {e.action for e in result.scalars().all()}
assert actions == {"bot.create", "bot.issue_token"}
async def test_create_token_rejects_unknown_scope(client, db_session):
admin = await register_and_login(client, db_session, username="admin1")
await _make_admin(db_session, admin["id"])
bot = (await client.post("/api/admin/bots", json={"username": "helper-bot"})).json()
resp = await client.post(
f"/api/admin/bots/{bot['id']}/tokens", json={"scopes": ["delete:everything"]}
)
assert resp.status_code == 400
async def test_list_bots_includes_created_bot(client, db_session):
admin = await register_and_login(client, db_session, username="admin1")
await _make_admin(db_session, admin["id"])
await client.post("/api/admin/bots", json={"username": "helper-bot"})
resp = await client.get("/api/admin/bots")
assert resp.status_code == 200
usernames = {b["username"] for b in resp.json()}
assert "helper-bot" in usernames
async def test_revoke_token_invalidates_it(client, db_session):
admin = await register_and_login(client, db_session, username="admin1")
await _make_admin(db_session, admin["id"])
bot = (await client.post("/api/admin/bots", json={"username": "helper-bot"})).json()
token = (
await client.post(f"/api/admin/bots/{bot['id']}/tokens", json={"scopes": ["read:messages"]})
).json()
revoke_resp = await client.delete(f"/api/admin/bots/tokens/{token['id']}")
assert revoke_resp.status_code == 204
# A revoked token should no longer authenticate anything.
resp = await client.get(
"/api/rooms", headers={"Authorization": f"Bearer {token['token']}"}
)
assert resp.status_code == 401
async def test_invalid_bearer_token_rejected(client):
resp = await client.get("/api/rooms", headers={"Authorization": "Bearer kit_not-a-real-token"})
assert resp.status_code == 401
def _unique(prefix: str) -> str:
return f"{prefix}-{uuid.uuid4().hex[:8]}"
def _register_ws(ws_client, username: str) -> dict:
from app.schemas.user import UserCreate
from app.services.auth_service import register_user
async def _seed():
async with ws_client.session_factory() as session:
await register_user(
session,
UserCreate(username=username, email=f"{username}@example.com", password="password123"),
)
ws_client.portal.call(_seed)
resp = ws_client.post(
"/api/auth/login", json={"username_or_email": username, "password": "password123"}
)
assert resp.status_code == 200, resp.text
return resp.json()
def _make_admin_ws(ws_client, user_id: str) -> None:
async def _promote():
async with ws_client.session_factory() as session:
user = await session.get(User, uuid.UUID(user_id))
user.is_site_admin = True
await session.commit()
ws_client.portal.call(_promote)
def test_bot_ws_message_with_write_scope_succeeds(ws_client_factory):
ws_client = ws_client_factory()
admin = _register_ws(ws_client, _unique("admin"))
_make_admin_ws(ws_client, admin["id"])
room = ws_client.post("/api/rooms", json={"name": _unique("general")}).json()
bot = ws_client.post("/api/admin/bots", json={"username": _unique("bot")}).json()
token = ws_client.post(
f"/api/admin/bots/{bot['id']}/tokens", json={"scopes": ["read:messages", "write:messages"]}
).json()["token"]
# Bot joins the room via REST using its own bearer token -- exercises
# bearer-token auth on the plain REST path, not just WS.
join_resp = ws_client.post(
f"/api/rooms/{room['id']}/join", headers={"Authorization": f"Bearer {token}"}
)
assert join_resp.status_code == 200
with ws_client.websocket_connect(
"/ws/chat", headers={"Authorization": f"Bearer {token}"}
) as ws:
ws.send_json({"type": "join", "room_id": room["id"]})
assert ws.receive_json()["type"] == "joined"
ws.send_json({"type": "message", "room_id": room["id"], "content": "hello from bot"})
message = ws.receive_json()
assert message["type"] == "message"
assert message["content"] == "hello from bot"
assert message["username"] == bot["username"]
def test_bot_ws_message_without_write_scope_rejected(ws_client_factory):
ws_client = ws_client_factory()
admin = _register_ws(ws_client, _unique("admin"))
_make_admin_ws(ws_client, admin["id"])
room = ws_client.post("/api/rooms", json={"name": _unique("general")}).json()
bot = ws_client.post("/api/admin/bots", json={"username": _unique("bot")}).json()
token = ws_client.post(
f"/api/admin/bots/{bot['id']}/tokens", json={"scopes": ["read:messages"]}
).json()["token"]
ws_client.post(f"/api/rooms/{room['id']}/join", headers={"Authorization": f"Bearer {token}"})
with ws_client.websocket_connect(
"/ws/chat", headers={"Authorization": f"Bearer {token}"}
) as ws:
ws.send_json({"type": "join", "room_id": room["id"]})
assert ws.receive_json()["type"] == "joined"
ws.send_json({"type": "message", "room_id": room["id"], "content": "hello"})
resp = ws.receive_json()
assert resp["type"] == "error"
assert "write:messages" in resp["detail"]
def test_bot_rest_message_history_requires_read_scope(ws_client_factory):
ws_client = ws_client_factory()
admin = _register_ws(ws_client, _unique("admin"))
_make_admin_ws(ws_client, admin["id"])
room = ws_client.post("/api/rooms", json={"name": _unique("general")}).json()
bot = ws_client.post("/api/admin/bots", json={"username": _unique("bot")}).json()
write_only_token = ws_client.post(
f"/api/admin/bots/{bot['id']}/tokens", json={"scopes": ["write:messages"]}
).json()["token"]
read_token = ws_client.post(
f"/api/admin/bots/{bot['id']}/tokens", json={"scopes": ["read:messages"]}
).json()["token"]
ws_client.post(
f"/api/rooms/{room['id']}/join", headers={"Authorization": f"Bearer {write_only_token}"}
)
no_scope_resp = ws_client.get(
f"/api/rooms/{room['id']}/messages",
headers={"Authorization": f"Bearer {write_only_token}"},
)
assert no_scope_resp.status_code == 403
with_scope_resp = ws_client.get(
f"/api/rooms/{room['id']}/messages", headers={"Authorization": f"Bearer {read_token}"}
)
assert with_scope_resp.status_code == 200
+130
View File
@@ -0,0 +1,130 @@
import uuid
from app.schemas.user import UserCreate
from app.services.auth_service import register_user
def _unique(prefix: str) -> str:
return f"{prefix}-{uuid.uuid4().hex[:8]}"
def _register_ws(ws_client, username: str) -> dict:
async def _seed():
async with ws_client.session_factory() as session:
await register_user(
session,
UserCreate(username=username, email=f"{username}@example.com", password="password123"),
)
ws_client.portal.call(_seed)
resp = ws_client.post(
"/api/auth/login", json={"username_or_email": username, "password": "password123"}
)
assert resp.status_code == 200, resp.text
return resp.json()
def test_ws_edit_updates_content_and_broadcasts(ws_client):
username = _unique("alice")
_register_ws(ws_client, username=username)
room = ws_client.post("/api/rooms", json={"name": _unique("general")}).json()
with ws_client.websocket_connect("/ws/chat") as ws:
ws.send_json({"type": "join", "room_id": room["id"]})
assert ws.receive_json()["type"] == "joined"
ws.send_json({"type": "message", "room_id": room["id"], "content": "hello"})
message = ws.receive_json()
assert message["edited_at"] is None
ws.send_json(
{
"type": "edit",
"room_id": room["id"],
"message_id": message["id"],
"content": "hello, edited",
}
)
update = ws.receive_json()
assert update["type"] == "message_update"
assert update["id"] == message["id"]
assert update["content"] == "hello, edited"
assert update["edited_at"] is not None
resp = ws_client.get(f"/api/rooms/{room['id']}/messages")
history = resp.json()
edited = next(m for m in history if m["id"] == message["id"])
assert edited["content"] == "hello, edited"
assert edited["edited_at"] is not None
def test_ws_edit_rejects_non_author(ws_client):
alice = _register_ws(ws_client, username=_unique("alice"))
room = ws_client.post("/api/rooms", json={"name": _unique("general")}).json()
bob = _register_ws(ws_client, username=_unique("bob"))
ws_client.post(f"/api/rooms/{room['id']}/join")
ws_client.post(
"/api/auth/login", json={"username_or_email": alice["username"], "password": "password123"}
)
with ws_client.websocket_connect("/ws/chat") as alice_ws:
alice_ws.send_json({"type": "join", "room_id": room["id"]})
assert alice_ws.receive_json()["type"] == "joined"
alice_ws.send_json({"type": "message", "room_id": room["id"], "content": "hello"})
message = alice_ws.receive_json()
ws_client.post(
"/api/auth/login",
json={"username_or_email": bob["username"], "password": "password123"},
)
with ws_client.websocket_connect("/ws/chat") as bob_ws:
bob_ws.send_json({"type": "join", "room_id": room["id"]})
assert bob_ws.receive_json()["type"] == "joined"
bob_ws.send_json(
{
"type": "edit",
"room_id": room["id"],
"message_id": message["id"],
"content": "hacked",
}
)
resp = bob_ws.receive_json()
assert resp["type"] == "error"
assert "own messages" in resp["detail"]
def test_edit_fans_out_across_instances(ws_client_factory):
instance1 = ws_client_factory()
instance2 = ws_client_factory()
alice = _register_ws(instance1, _unique("alice"))
room = instance1.post("/api/rooms", json={"name": _unique("general")}).json()
bob = _register_ws(instance2, _unique("bob"))
instance2.post(f"/api/rooms/{room['id']}/join")
with instance2.websocket_connect("/ws/chat") as bob_ws:
bob_ws.send_json({"type": "join", "room_id": room["id"]})
assert bob_ws.receive_json()["type"] == "joined"
with instance1.websocket_connect("/ws/chat") as alice_ws:
alice_ws.send_json({"type": "join", "room_id": room["id"]})
assert alice_ws.receive_json()["type"] == "joined"
alice_ws.send_json({"type": "message", "room_id": room["id"], "content": "hi"})
message = alice_ws.receive_json()
assert bob_ws.receive_json()["type"] == "message"
alice_ws.send_json(
{
"type": "edit",
"room_id": room["id"],
"message_id": message["id"],
"content": "hi, edited",
}
)
assert alice_ws.receive_json()["type"] == "message_update"
update = bob_ws.receive_json()
assert update["type"] == "message_update"
assert update["content"] == "hi, edited"
+164
View File
@@ -0,0 +1,164 @@
import asyncio
import hashlib
import hmac
import json
import uuid
import pytest
from app.models import PushSubscription
from app.schemas.user import UserCreate
from app.services.auth_service import register_user
from app.services.room_service import join_room
from app.services.ssrf import UnsafeWebhookUrlError, validate_target_url
from tests.conftest import register_and_login
def test_validate_target_url_rejects_loopback():
with pytest.raises(UnsafeWebhookUrlError):
validate_target_url("http://127.0.0.1/hook")
def test_validate_target_url_rejects_private_range():
with pytest.raises(UnsafeWebhookUrlError):
validate_target_url("http://10.0.0.5/hook")
def test_validate_target_url_rejects_non_http_scheme():
with pytest.raises(UnsafeWebhookUrlError):
validate_target_url("ftp://8.8.8.8/hook")
def test_validate_target_url_accepts_public_address():
# 8.8.8.8 is a stable, well-known public IP (Google's public DNS
# resolver) -- a literal IP so this resolves without any real network
# access (getaddrinfo parses a literal IP without touching DNS/the
# network), and it isn't flagged by any of ipaddress's private/
# reserved/loopback/etc checks, so it exercises the "allowed" path.
# (203.0.113.0/24, the usual RFC 5737 documentation-only choice, is
# actually flagged is_private by Python's ipaddress module -- not
# usable here.)
validate_target_url("http://8.8.8.8/hook")
async def test_event_subscription_rejects_private_target(client, db_session):
await register_and_login(client, db_session, username="alice")
room = (await client.post("/api/rooms", json={"name": "general"})).json()
resp = await client.post(
f"/api/rooms/{room['id']}/event-subscriptions",
json={"event_types": ["message.created"], "target_url": "http://127.0.0.1/hook"},
)
assert resp.status_code == 400
async def test_incoming_webhook_unknown_token_404s(client, db_session):
await register_and_login(client, db_session, username="alice")
resp = await client.post("/api/webhooks/incoming/not-a-real-token", json={"content": "hi"})
assert resp.status_code == 404
async def test_incoming_webhook_posts_message_and_pushes_offline_members(
client, db_session, monkeypatch
):
calls = []
monkeypatch.setattr("app.services.push_service.webpush", lambda **kw: calls.append(kw))
alice = await register_and_login(client, db_session, username="alice")
room = (await client.post("/api/rooms", json={"name": "general"})).json()
webhook_resp = await client.post(
f"/api/rooms/{room['id']}/webhooks/incoming", json={"description": "CI bot"}
)
assert webhook_resp.status_code == 201
webhook = webhook_resp.json()
assert webhook["token"]
bob = await register_user(
db_session, UserCreate(username="bob", email="bob@example.com", password="password123")
)
await join_room(db_session, uuid.UUID(room["id"]), bob.id)
db_session.add(
PushSubscription(
user_id=bob.id,
endpoint="https://push.example.com/bob",
p256dh_key="p256dh",
auth_key="auth",
)
)
await db_session.commit()
post_resp = await client.post(
f"/api/webhooks/incoming/{webhook['token']}", json={"content": "deploy succeeded"}
)
assert post_resp.status_code == 204
history = (await client.get(f"/api/rooms/{room['id']}/messages")).json()
assert any(m["content"] == "deploy succeeded" for m in history)
# Exactly one push -- to bob. If the sender (webhook creator, alice) were
# incorrectly included in "offline members" (no WS connection exists for
# either party in this REST-only test), this would be 2.
assert len(calls) == 1
assert "deploy succeeded" in calls[0]["data"]
async def test_outgoing_webhook_delivers_signed_payload(client, db_session, monkeypatch):
captured_tasks: list[asyncio.Task] = []
real_create_task = asyncio.create_task
def fake_create_task(coro):
task = real_create_task(coro)
captured_tasks.append(task)
return task
monkeypatch.setattr("app.services.webhook_service.asyncio.create_task", fake_create_task)
posts = []
class FakeResponse:
status_code = 200
class FakeAsyncClient:
def __init__(self, *args, **kwargs):
pass
async def __aenter__(self):
return self
async def __aexit__(self, *args):
return False
async def post(self, url, content=None, headers=None):
posts.append({"url": url, "content": content, "headers": headers})
return FakeResponse()
monkeypatch.setattr("app.services.webhook_delivery.httpx.AsyncClient", FakeAsyncClient)
await register_and_login(client, db_session, username="alice")
room = (await client.post("/api/rooms", json={"name": "general"})).json()
sub_resp = await client.post(
f"/api/rooms/{room['id']}/event-subscriptions",
json={"event_types": ["message.created"], "target_url": "http://8.8.8.8/hook"},
)
assert sub_resp.status_code == 201
secret = sub_resp.json()["signing_secret"]
webhook = (
await client.post(f"/api/rooms/{room['id']}/webhooks/incoming", json={})
).json()
resp = await client.post(
f"/api/webhooks/incoming/{webhook['token']}", json={"content": "ping"}
)
assert resp.status_code == 204
await asyncio.gather(*captured_tasks)
assert len(posts) == 1
body = posts[0]["content"]
expected_signature = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
assert posts[0]["headers"]["X-KeepItTalking-Signature"] == f"sha256={expected_signature}"
payload = json.loads(body)
assert payload["event"] == "message.created"
assert payload["data"]["content"] == "ping"