route-analysis

Skill: Route Analysis

Use this skill to analyse, audit, or modify HTTP and WebSocket routes in VoxBento. All routes live in portal/routers/.

---

Route Categories

---

Auth Patterns

User page routes

payload = get_booth_session(request)   # checks session_token then user_token
if payload is None:
    return safe_redirect(url=f'/login?next={path}', ...)
granted_role = await resolve_booth_role(payload, booth_id)

Admin routes

@app.get('/admin/...', dependencies=[Depends(require_admin)])

require_admin checks user_token (is_admin=True or event_admin membership) then falls back to admin_token.

API routes (optional auth)

_require_access(credentials, token)   # passes if booth_access_token is unset

WebSocket

• Cookies read at connect time: session_token then user_token.
• Role resolved via resolve_booth_role(payload, booth_id).
• Token scope validated: session_token.event_slug + language_code must match the booth.
• Connection rejected with code 4003 on scope mismatch; 4001 on invalid token.

---

Role Resolution (portal/auth.py)

resolve_booth_role(payload, booth_id) returns the most privileged applicable role:

1. super_admin — if is_admin=True in user token.
2. event_admin — if user has EventMembership.role == 'event_admin' for the booth's event.
3. Role from BoothMembership for the specific booth.
4. Role from EventMembership for the booth's event.
5. Role embedded in participant session_token — but only if event_slug + language_code match.
6. Returns None if no applicable role found → 403 on page routes.

---

Redirect Safety

All redirects MUST use safe_redirect(url, status_code):

def safe_redirect(url: str, status_code: int) -> RedirectResponse:
    url = url.replace('\\', '').strip()
    parsed = urlparse(url)
    if url and not parsed.netloc and not parsed.scheme and url.startswith('/'):
        return RedirectResponse(url=url, status_code=status_code)
    return RedirectResponse(url='/', status_code=status_code)  # fallback

Never call RedirectResponse(url=user_input) directly.

---

Adding a New Route

1. Add handler to portal/routers/.
2. Use correct auth pattern (see above).
3. Use safe_redirect for all redirects.
4. Return templates.TemplateResponse(request, 'template.html', context) for HTML.
5. Raise HTTPException for errors — never return raw error strings.
6. Add test to tests/test_fastapi_app.py.

---

Critical Endpoints Reference

---

Common Route Bugs to Check

• Missing safe_redirect → open redirect risk.
• Missing auth dependency on admin route → unauthenticated access.
• data['role'] used directly from WS message → role injection vulnerability.
• token path param passed directly to DB query without validation → injection risk (mitigated by redeem_invite_token validation).
• next_url / next query param used in redirect without safe_redirect → open redirect.