447 lines
15 KiB
Markdown
447 lines
15 KiB
Markdown
# l4d2 Web Auth Pages Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. Do not use git worktrees.
|
|
|
|
**Goal:** Add a real login page, remove signup, and redirect anonymous users back to their requested page after login when safe.
|
|
|
|
**Architecture:** Keep the current username/password data model and Flask session authentication. Add a small safe-redirect helper in `l4d2web/auth.py`, render login through Jinja, and keep routing changes scoped to auth decorators plus the app root route.
|
|
|
|
**Tech Stack:** Flask, Jinja templates, SQLAlchemy models, pytest, existing custom CSS tokens.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
- `l4d2web/auth.py`: owns password hashing, session helpers, current user lookup, login-required/admin-required decorators, and safe local redirect target validation.
|
|
- `l4d2web/routes/auth_routes.py`: owns login GET/POST and logout. Signup handlers will be removed from this file.
|
|
- `l4d2web/app.py`: owns app setup, CSRF exemptions, and public root/health routes. Root will become auth-aware.
|
|
- `l4d2web/templates/base.html`: owns shared shell navigation. It will hide app navigation for anonymous users.
|
|
- `l4d2web/templates/login.html`: new server-rendered login page.
|
|
- `l4d2web/static/css/components.css`: minor form-control styling only if needed for the login form.
|
|
- `l4d2web/tests/test_auth.py`: auth route tests for login page, signup removal, safe next redirect, and unsafe next fallback.
|
|
- `l4d2web/tests/test_pages.py`: protected-page redirect and root redirect tests.
|
|
- `l4d2web/tests/test_security.py`: CSRF/rate-limit regression tests after signup is removed from exemptions.
|
|
|
|
## Task 1: Remove Signup and Add Login Page Tests
|
|
|
|
**Files:**
|
|
- Modify: `l4d2web/tests/test_auth.py`
|
|
- Modify: `l4d2web/tests/test_pages.py`
|
|
|
|
- [ ] **Step 1: Update auth tests for login page, signup removal, and next redirects**
|
|
|
|
Replace `test_public_signup` in `l4d2web/tests/test_auth.py` with these tests, and update existing login test data keys only if needed:
|
|
|
|
```python
|
|
def test_login_page_renders_form(client) -> None:
|
|
response = client.get("/login")
|
|
text = response.get_data(as_text=True)
|
|
|
|
assert response.status_code == 200
|
|
assert '<form method="post" action="/login"' in text
|
|
assert 'name="username"' in text
|
|
assert 'name="password"' in text
|
|
assert "signup" not in text.lower()
|
|
|
|
|
|
def test_login_page_drops_unsafe_encoded_next(client) -> None:
|
|
response = client.get("/login?next=/%5Cevil.com")
|
|
text = response.get_data(as_text=True)
|
|
|
|
assert response.status_code == 200
|
|
assert 'name="next"' not in text
|
|
assert "evil.com" not in text
|
|
|
|
|
|
def test_signup_routes_are_gone(client) -> None:
|
|
assert client.get("/signup").status_code == 404
|
|
assert client.post("/signup", data={"username": "alice", "password": "secret"}).status_code == 404
|
|
|
|
|
|
def test_login_redirects_to_safe_next(client) -> None:
|
|
with session_scope() as session:
|
|
session.add(User(username="alice", password_digest=hash_password("secret"), admin=False))
|
|
|
|
response = client.post(
|
|
"/login",
|
|
data={"username": "alice", "password": "secret", "next": "/servers"},
|
|
)
|
|
|
|
assert response.status_code == 302
|
|
assert response.headers["Location"].endswith("/servers")
|
|
|
|
|
|
def test_login_ignores_unsafe_next(client) -> None:
|
|
with session_scope() as session:
|
|
session.add(User(username="alice", password_digest=hash_password("secret"), admin=False))
|
|
|
|
response = client.post(
|
|
"/login",
|
|
data={"username": "alice", "password": "secret", "next": "https://example.com/steal"},
|
|
)
|
|
|
|
assert response.status_code == 302
|
|
assert response.headers["Location"].endswith("/dashboard")
|
|
|
|
|
|
def test_login_ignores_backslash_next(client) -> None:
|
|
with session_scope() as session:
|
|
session.add(User(username="alice", password_digest=hash_password("secret"), admin=False))
|
|
|
|
response = client.post(
|
|
"/login",
|
|
data={"username": "alice", "password": "secret", "next": "/\\evil.com"},
|
|
)
|
|
|
|
assert response.status_code == 302
|
|
assert response.headers["Location"].endswith("/dashboard")
|
|
|
|
|
|
def test_login_ignores_percent_encoded_backslash_next(client) -> None:
|
|
with session_scope() as session:
|
|
session.add(User(username="alice", password_digest=hash_password("secret"), admin=False))
|
|
|
|
response = client.post(
|
|
"/login",
|
|
data={"username": "alice", "password": "secret", "next": "/%5Cevil.com"},
|
|
)
|
|
|
|
assert response.status_code == 302
|
|
assert response.headers["Location"].endswith("/dashboard")
|
|
```
|
|
|
|
- [ ] **Step 2: Add protected-page and root redirect tests**
|
|
|
|
Append these tests to `l4d2web/tests/test_pages.py`:
|
|
|
|
```python
|
|
def test_anonymous_protected_page_redirects_to_login_with_next(tmp_path, monkeypatch) -> None:
|
|
db_url = f"sqlite:///{tmp_path/'anonymous-pages.db'}"
|
|
monkeypatch.setenv("DATABASE_URL", db_url)
|
|
app = create_app({"TESTING": True, "DATABASE_URL": db_url, "SECRET_KEY": "test"})
|
|
init_db()
|
|
client = app.test_client()
|
|
|
|
response = client.get("/servers")
|
|
|
|
assert response.status_code == 302
|
|
assert response.headers["Location"].endswith("/login?next=/servers")
|
|
|
|
|
|
def test_root_redirects_by_auth_state(tmp_path, monkeypatch) -> None:
|
|
db_url = f"sqlite:///{tmp_path/'root-redirect.db'}"
|
|
monkeypatch.setenv("DATABASE_URL", db_url)
|
|
app = create_app({"TESTING": True, "DATABASE_URL": db_url, "SECRET_KEY": "test"})
|
|
init_db()
|
|
client = app.test_client()
|
|
|
|
anonymous_response = client.get("/")
|
|
assert anonymous_response.status_code == 302
|
|
assert anonymous_response.headers["Location"].endswith("/login")
|
|
|
|
with session_scope() as session:
|
|
user = User(username="alice", password_digest=hash_password("secret"), admin=False)
|
|
session.add(user)
|
|
session.flush()
|
|
user_id = user.id
|
|
|
|
with client.session_transaction() as sess:
|
|
sess["user_id"] = user_id
|
|
|
|
logged_in_response = client.get("/")
|
|
assert logged_in_response.status_code == 302
|
|
assert logged_in_response.headers["Location"].endswith("/dashboard")
|
|
```
|
|
|
|
- [ ] **Step 3: Run tests and verify they fail**
|
|
|
|
Run: `pytest l4d2web/tests/test_auth.py::test_login_page_renders_form l4d2web/tests/test_auth.py::test_signup_routes_are_gone l4d2web/tests/test_auth.py::test_login_redirects_to_safe_next l4d2web/tests/test_auth.py::test_login_ignores_unsafe_next l4d2web/tests/test_pages.py::test_anonymous_protected_page_redirects_to_login_with_next l4d2web/tests/test_pages.py::test_root_redirects_by_auth_state -q`
|
|
|
|
Expected: FAIL because `/login` is still plain text, signup routes still exist, `next` is not implemented, and `/` still returns JSON.
|
|
|
|
## Task 2: Implement Safe Redirects and Remove Signup
|
|
|
|
**Files:**
|
|
- Modify: `l4d2web/auth.py`
|
|
- Modify: `l4d2web/routes/auth_routes.py`
|
|
- Modify: `l4d2web/app.py`
|
|
|
|
- [ ] **Step 1: Add safe redirect helpers and next-aware decorators**
|
|
|
|
Update `l4d2web/auth.py` imports and add helpers near the session helpers:
|
|
|
|
```python
|
|
from urllib.parse import quote, unquote
|
|
|
|
from flask import abort, g, redirect, request, session
|
|
```
|
|
|
|
```python
|
|
def is_safe_next(target: str | None) -> bool:
|
|
if not target:
|
|
return False
|
|
if not target.startswith("/"):
|
|
return False
|
|
if target.startswith("//"):
|
|
return False
|
|
if "://" in target:
|
|
return False
|
|
if "\\" in target:
|
|
return False
|
|
decoded_target = unquote(target)
|
|
if decoded_target.startswith("//"):
|
|
return False
|
|
if "://" in decoded_target:
|
|
return False
|
|
if "\\" in decoded_target:
|
|
return False
|
|
return True
|
|
|
|
|
|
def login_redirect_for_current_request():
|
|
target = request.full_path.rstrip("?")
|
|
if is_safe_next(target):
|
|
return redirect(f"/login?next={quote(target, safe='/')}")
|
|
return redirect("/login")
|
|
```
|
|
|
|
Change `require_login` and the anonymous branch of `require_admin` to call `login_redirect_for_current_request()`:
|
|
|
|
```python
|
|
def require_login(func: F) -> F:
|
|
@wraps(func)
|
|
def wrapper(*args, **kwargs):
|
|
if current_user() is None:
|
|
return login_redirect_for_current_request()
|
|
return func(*args, **kwargs)
|
|
|
|
return wrapper # type: ignore[return-value]
|
|
|
|
|
|
def require_admin(func: F) -> F:
|
|
@wraps(func)
|
|
def wrapper(*args, **kwargs):
|
|
user = current_user()
|
|
if user is None:
|
|
return login_redirect_for_current_request()
|
|
if not user.admin:
|
|
abort(403)
|
|
return func(*args, **kwargs)
|
|
|
|
return wrapper # type: ignore[return-value]
|
|
```
|
|
|
|
- [ ] **Step 2: Remove signup and render login template**
|
|
|
|
Update `l4d2web/routes/auth_routes.py` imports:
|
|
|
|
```python
|
|
from flask import Blueprint, Response, redirect, render_template, request
|
|
```
|
|
|
|
Update the auth import:
|
|
|
|
```python
|
|
from l4d2web.auth import hash_password, is_safe_next, login_user, logout_user, verify_password
|
|
```
|
|
|
|
Delete the `@bp.get("/signup")` and `@bp.post("/signup")` route functions.
|
|
|
|
Replace `login_form` with:
|
|
|
|
```python
|
|
@bp.get("/login")
|
|
def login_form() -> str:
|
|
next_target = request.args.get("next", "")
|
|
return render_template("login.html", next_target=next_target if is_safe_next(next_target) else "")
|
|
```
|
|
|
|
Replace the final line of `login` with a safe redirect target:
|
|
|
|
```python
|
|
next_target = request.form.get("next", "")
|
|
return redirect(next_target if is_safe_next(next_target) else "/dashboard")
|
|
```
|
|
|
|
Keep the existing rate limiting and invalid credential behavior unchanged.
|
|
|
|
- [ ] **Step 3: Update CSRF exemptions and root route**
|
|
|
|
In `l4d2web/app.py`, update imports:
|
|
|
|
```python
|
|
from flask import Flask, Response, jsonify, redirect, request, session
|
|
|
|
from l4d2web.auth import current_user, load_current_user
|
|
```
|
|
|
|
Change the CSRF exemptions to remove signup:
|
|
|
|
```python
|
|
CSRF_EXEMPT_PATHS={"/login", "/health"},
|
|
```
|
|
|
|
Replace the root route with:
|
|
|
|
```python
|
|
@app.get("/")
|
|
def root():
|
|
if current_user() is None:
|
|
return redirect("/login")
|
|
return redirect("/dashboard")
|
|
```
|
|
|
|
- [ ] **Step 4: Run focused tests and verify they still fail only for missing template/nav**
|
|
|
|
Run: `pytest l4d2web/tests/test_auth.py::test_login_page_renders_form l4d2web/tests/test_auth.py::test_signup_routes_are_gone l4d2web/tests/test_auth.py::test_login_redirects_to_safe_next l4d2web/tests/test_auth.py::test_login_ignores_unsafe_next l4d2web/tests/test_pages.py::test_anonymous_protected_page_redirects_to_login_with_next l4d2web/tests/test_pages.py::test_root_redirects_by_auth_state -q`
|
|
|
|
Expected: FAIL only because `login.html` does not exist or the rendered page does not yet contain the expected form markup.
|
|
|
|
## Task 3: Add Login Template and Anonymous Shell Behavior
|
|
|
|
**Files:**
|
|
- Create: `l4d2web/templates/login.html`
|
|
- Modify: `l4d2web/templates/base.html`
|
|
- Modify: `l4d2web/static/css/components.css`
|
|
|
|
- [ ] **Step 1: Hide main app navigation for anonymous users**
|
|
|
|
Update the header section in `l4d2web/templates/base.html` so the main section links render only for logged-in users:
|
|
|
|
```html
|
|
<nav class="primary-nav" aria-label="Main navigation">
|
|
<a class="brand" href="{{ '/dashboard' if g.user else '/login' }}">left4me</a>
|
|
{% if g.user %}
|
|
<a href="/servers">servers</a>
|
|
<a href="/blueprints">blueprints</a>
|
|
<a href="/overlays">overlays</a>
|
|
{% endif %}
|
|
</nav>
|
|
```
|
|
|
|
Keep the existing account nav wrapped in `{% if g.user %}`.
|
|
|
|
- [ ] **Step 2: Create the login template**
|
|
|
|
Create `l4d2web/templates/login.html`:
|
|
|
|
```html
|
|
{% extends "base.html" %}
|
|
|
|
{% block title %}Log In | left4me{% endblock %}
|
|
|
|
{% block content %}
|
|
<section class="panel auth-panel">
|
|
<h1>Log in to left4me</h1>
|
|
<p class="muted">Use your local account to manage Left 4 Dead 2 servers.</p>
|
|
|
|
<form method="post" action="/login" class="stack">
|
|
{% if next_target %}<input type="hidden" name="next" value="{{ next_target }}">{% endif %}
|
|
<label>
|
|
Username
|
|
<input name="username" autocomplete="username" required autofocus>
|
|
</label>
|
|
<label>
|
|
Password
|
|
<input name="password" type="password" autocomplete="current-password" required>
|
|
</label>
|
|
<button type="submit">log in</button>
|
|
</form>
|
|
</section>
|
|
{% endblock %}
|
|
```
|
|
|
|
- [ ] **Step 3: Add minimal form styling if needed**
|
|
|
|
Append to `l4d2web/static/css/components.css`:
|
|
|
|
```css
|
|
label {
|
|
display: grid;
|
|
gap: var(--space-xs);
|
|
}
|
|
|
|
input,
|
|
select,
|
|
textarea {
|
|
background: var(--color-surface);
|
|
border: var(--line);
|
|
border-radius: var(--radius-s);
|
|
color: var(--color-text);
|
|
padding: var(--space-s) var(--space-m);
|
|
}
|
|
|
|
input:focus,
|
|
select:focus,
|
|
textarea:focus,
|
|
button:focus-visible,
|
|
a:focus-visible {
|
|
outline: 2px solid var(--color-focus);
|
|
outline-offset: 2px;
|
|
}
|
|
|
|
.auth-panel {
|
|
max-width: 28rem;
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run focused tests and verify they pass**
|
|
|
|
Run: `pytest l4d2web/tests/test_auth.py::test_login_page_renders_form l4d2web/tests/test_auth.py::test_signup_routes_are_gone l4d2web/tests/test_auth.py::test_login_redirects_to_safe_next l4d2web/tests/test_auth.py::test_login_ignores_unsafe_next l4d2web/tests/test_pages.py::test_anonymous_protected_page_redirects_to_login_with_next l4d2web/tests/test_pages.py::test_root_redirects_by_auth_state -q`
|
|
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 5: Commit auth page implementation**
|
|
|
|
```bash
|
|
git add l4d2web/auth.py l4d2web/routes/auth_routes.py l4d2web/app.py l4d2web/templates/base.html l4d2web/templates/login.html l4d2web/static/css/components.css l4d2web/tests/test_auth.py l4d2web/tests/test_pages.py
|
|
git commit -m "feat(l4d2-web): add login page and safe redirects"
|
|
```
|
|
|
|
## Task 4: Security Regression and Full Web Verification
|
|
|
|
**Files:**
|
|
- Modify: `l4d2web/tests/test_security.py` only if existing tests need path-specific updates.
|
|
- Modify: `docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md` only if stale public-signup requirements should be corrected after implementation.
|
|
- Modify: `AGENTS.md` only if the auth contract must be changed from public signup to admin-created local users.
|
|
|
|
- [ ] **Step 1: Run security tests**
|
|
|
|
Run: `pytest l4d2web/tests/test_security.py -q`
|
|
|
|
Expected: PASS. `test_csrf_required` should still prove protected POSTs require CSRF. `test_login_rate_limit` should still pass with `/login` exempt from CSRF.
|
|
|
|
- [ ] **Step 2: Run page tests**
|
|
|
|
Run: `pytest l4d2web/tests/test_pages.py -q`
|
|
|
|
Expected: PASS. Existing logged-in shell tests should still see app navigation; new anonymous tests should see login redirects.
|
|
|
|
- [ ] **Step 3: Run auth tests**
|
|
|
|
Run: `pytest l4d2web/tests/test_auth.py -q`
|
|
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 4: Run full web test suite**
|
|
|
|
Run: `pytest l4d2web/tests -q`
|
|
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 5: Commit test/doc cleanup if needed**
|
|
|
|
If Task 4 required changes, commit them:
|
|
|
|
```bash
|
|
git add l4d2web/tests/test_security.py docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md AGENTS.md
|
|
git commit -m "test(l4d2-web): cover auth redirect regressions"
|
|
```
|
|
|
|
If no files changed in Task 4, do not create an empty commit.
|
|
|
|
## Final Verification
|
|
|
|
- [ ] Run `pytest l4d2web/tests -q` and confirm all tests pass.
|
|
- [ ] Run `git status --short` and confirm only intentional changes remain.
|
|
- [ ] Report exact command results and commits created.
|