Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
fix: answer CSRF rejections with a JSON reason and log them, so a proxy that strips the Referer or rewrites the Host is reported as such instead of retried and shown as a generic failure (#388)
Murtaza Nasirf8e0422ea202
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdindex 27623704..e5c00763 100644--- a/docs/troubleshooting.md+++ b/docs/troubleshooting.md@@ -24,6 +24,12 @@ When Speakr starts successfully but you can't reach the web interface, network cFirewall rules often block access, especially on cloud servers. Ensure port 8899 is open in your firewall, security groups (AWS), or network policies. If accessing from another machine, remember that `localhost` won't work - use the server's actual IP address or hostname.+### Actions Fail Behind a Reverse Proxy with a Referer or Host Error++Over HTTPS, Speakr's CSRF protection requires the browser's Referer header to match the host the server receives. If every action that changes something (reprocessing, resetting a status, saving) fails with HTTP 400 and a message naming the Referer header or two different host names, the reverse proxy is the cause. The server log shows a matching `CSRF validation failed` warning with both hosts.++Two proxy settings produce this. The proxy may strip the Referer header, either directly or through a `Referrer-Policy: no-referrer` header it adds; use `strict-origin-when-cross-origin` or leave the header to Speakr. Alternatively, the proxy may forward a different Host header than the address in the browser (for example the container name); forward the original Host (in Nginx, `proxy_set_header Host $host;`) or set `X-Forwarded-Host`, and set `TRUSTED_PROXY_HOPS` to the number of proxies in front of Speakr. Reloading the page does not help with either, because every request fails the same check.+### Admin Login FailsIf you can't log in with your [admin credentials](getting-started.md#step-4-configure-admin-account), first verify you're using the exact username and password from your environment file. For user management issues, see the [admin guide](admin-guide/user-management.md). These are case-sensitive and must match exactly. Check the Docker logs for admin user creation messages - you should see "Admin user created successfully" during first startup.diff --git a/src/app.py b/src/app.pyindex 6e539f47..27e23e75 100644--- a/src/app.py+++ b/src/app.py@@ -33,7 +33,7 @@ mimetypes.add_type('audio/ogg', '.ogg')from flask_login import LoginManager, UserMixin, login_user, logout_user, login_required, current_userfrom flask_bcrypt import Bcryptfrom flask_wtf import FlaskForm-from flask_wtf.csrf import CSRFProtect+from flask_wtf.csrf import CSRFProtect, CSRFErrorfrom wtforms import StringField, PasswordField, SubmitField, BooleanFieldfrom wtforms.validators import DataRequired, Length, Email, EqualTo, ValidationErrorfrom flask_limiter import Limiter@@ -633,6 +633,58 @@ def csrf_token_aware_check():csrf.protect()++def _csrf_rejection_message(reason):+ """Turn a Flask-WTF CSRFError description into something an admin can act on.++ Token failures (missing, expired, mismatched) are fixed by reloading the+ page. The two referrer failures are not: Flask-WTF checks the Referer+ header on every HTTPS request, so a proxy that strips it or rewrites the+ Host header makes every POST fail, however often the token is refreshed+ (issue #388). Those get a message that names the proxy setting.+ """+ if 'referrer header is missing' in reason:+ return False, ('The request was rejected because the browser sent no Referer header, '+ 'which HTTPS requests require. A reverse proxy, browser extension or '+ 'Referrer-Policy header that removes it causes this.')+ if 'referrer does not match' in reason:+ referrer_host = urlparse(request.referrer or '').netloc or 'unknown'+ return False, (f'The request was rejected because this page was loaded from '+ f'{referrer_host}, but the server received the request for {request.host}. '+ f'The reverse proxy must forward the original Host header (or '+ f'X-Forwarded-Host), and TRUSTED_PROXY_HOPS must match the number of proxies.')+ return True, 'Your session has expired. Please reload the page and try again.'++[email protected](CSRFError)+def handle_csrf_error(error):+ """Answer fetch/XHR callers with JSON that says why CSRF validation failed.++ Flask-WTF's default is an HTML 400 page. The frontend cannot tell a+ referrer failure from an expired token in that page, so it refreshes the+ token, retries, fails again and shows a generic error, while the server+ logs nothing. Browser form posts still get the HTML page.+ """+ reason = error.description or ''+ retryable, message = _csrf_rejection_message(reason.lower())+ app.logger.warning(+ 'CSRF validation failed for %s %s: %s (Referer host: %s, request host: %s, scheme: %s)',+ request.method, request.path, reason,+ urlparse(request.referrer or '').netloc or '-', request.host, request.scheme,+ )+ is_form_navigation = (+ request.mimetype in ('application/x-www-form-urlencoded', 'multipart/form-data')+ and 'text/html' in request.headers.get('Accept', '')+ )+ if is_form_navigation:+ return error+ return jsonify({+ 'error': message,+ 'csrf_reason': reason,+ 'csrf_retryable': retryable,+ }), 400++@app.errorhandler(RequestEntityTooLarge)def handle_request_entity_too_large(_error):"""Keep oversized requests JSON-shaped even when parsing fails early."""diff --git a/static/js/csrf-refresh.js b/static/js/csrf-refresh.jsindex a8ce1e55..cfedc278 100644--- a/static/js/csrf-refresh.js+++ b/static/js/csrf-refresh.js@@ -111,16 +111,22 @@ class CSRFManager {try {const errorData = await responseClone.json();- const errorMessage = errorData.error || '';- isCSRFError = errorMessage.toLowerCase().includes('csrf') ||- errorMessage.toLowerCase().includes('token');+ if (typeof errorData.csrf_retryable === 'boolean') {+ // The server's CSRF handler says whether a fresh token+ // can help. Referrer failures cannot (#388).+ isCSRFError = errorData.csrf_retryable;+ } else {+ const errorMessage = errorData.error || '';+ isCSRFError = errorMessage.toLowerCase().includes('csrf') ||+ errorMessage.toLowerCase().includes('token');+ }} catch (jsonError) {- // If JSON parsing fails, check if it's an HTML error page+ // Not JSON: only an error page that mentions the token+ // is worth a refresh. Any other HTML page (a proxy's own+ // 400/403) fails the same way on retry.const textResponse = await response.clone().text();- isCSRFError = textResponse.toLowerCase().includes('csrf') ||- textResponse.toLowerCase().includes('token') ||- textResponse.includes('<!doctype') || // HTML error page- textResponse.includes('<html');+ isCSRFError = textResponse.toLowerCase().includes('csrf') ||+ textResponse.toLowerCase().includes('token');}if (isCSRFError) {diff --git a/static/js/modules/csrf.js b/static/js/modules/csrf.jsindex 0c6dc16b..3413579d 100644--- a/static/js/modules/csrf.js+++ b/static/js/modules/csrf.js@@ -76,9 +76,20 @@ export async function getUploadCsrfToken() {* Heuristic for "the server rejected our CSRF token", mirroring the* detection in csrf-refresh.js's fetch interceptor: a 400/403 whose* body (JSON error message or HTML error page) mentions csrf/token.+ *+ * The server's CSRF handler says explicitly whether a fresh token can+ * help (`csrf_retryable`). A referrer failure cannot: the proxy strips or+ * rewrites the header on every request, so it is not treated as a token+ * rejection and the server's explanation reaches the user (#388).*/export function isCsrfRejection(status, responseText) {if (status !== 400 && status !== 403) return false;+ try {+ const data = JSON.parse(responseText || '');+ if (data && typeof data.csrf_retryable === 'boolean') return data.csrf_retryable;+ } catch (e) {+ // Not JSON; fall through to the text heuristic.+ }const text = (responseText || '').toLowerCase();return text.includes('csrf') || text.includes('token');}diff --git a/static/js/modules/csrf.test.js b/static/js/modules/csrf.test.jsindex 19d9e02a..61d6672c 100644--- a/static/js/modules/csrf.test.js+++ b/static/js/modules/csrf.test.js@@ -125,5 +125,23 @@ describe('csrf helpers', () => {expect(isCsrfRejection(400, '')).toBe(false);expect(isCsrfRejection(400, null)).toBe(false);});++ it('trusts the server when it says a fresh token will not help (#388)', () => {+ const body = JSON.stringify({+ error: 'The request was rejected because the browser sent no Referer header.',+ csrf_reason: 'The referrer header is missing.',+ csrf_retryable: false,+ });+ expect(isCsrfRejection(400, body)).toBe(false);+ });++ it('trusts the server when it says a fresh token will help', () => {+ const body = JSON.stringify({+ error: 'Your session has expired. Please reload the page and try again.',+ csrf_reason: 'The CSRF token has expired.',+ csrf_retryable: true,+ });+ expect(isCsrfRejection(400, body)).toBe(true);+ });});});diff --git a/static/js/modules/utils/response.test.js b/static/js/modules/utils/response.test.jsindex 3af65867..37514406 100644--- a/static/js/modules/utils/response.test.js+++ b/static/js/modules/utils/response.test.js@@ -30,6 +30,16 @@ describe('readJsonResponse', () => {.rejects.toMatchObject({ isCsrfRejection: true });});+ it('shows the server explanation for a referrer rejection, not an expired session (#388)', async () => {+ const body = JSON.stringify({+ error: 'The request was rejected because the browser sent no Referer header.',+ csrf_reason: 'The referrer header is missing.',+ csrf_retryable: false,+ });+ await expect(readJsonResponse(res({ ok: false, status: 400, body }), t, 'errors.reprocessSummaryFailed'))+ .rejects.toThrow('The request was rejected because the browser sent no Referer header.');+ });+it('never surfaces a raw JSON parse error', async () => {const html = '<!doctype html><h1>500 Internal Server Error</h1>';try {diff --git a/tests/test_csrf_error_response.py b/tests/test_csrf_error_response.pynew file mode 100644index 00000000..e1dc99aa--- /dev/null+++ b/tests/test_csrf_error_response.py@@ -0,0 +1,92 @@+"""CSRF rejections tell the caller why, and whether a fresh token can help (#388).++Flask-WTF checks the Referer header on every HTTPS POST. A reverse proxy that+strips it, or forwards a different Host, fails that check on every request.+Its default answer is an HTML 400 page mentioning neither "csrf" nor "token",+so the frontend refreshed the token, retried, failed identically and showed+"Could not start summary reprocessing" with nothing in the server log.+"""++import os+import sys+import uuid++import pytest++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from src.app import app, db+from src.models import User+++def client():+ previous = app.config.get('WTF_CSRF_ENABLED', True)+ app.config['WTF_CSRF_ENABLED'] = True+ with app.app_context():+ suffix = uuid.uuid4().hex[:8]+ user = User(username=f'csrf_{suffix}', email=f'csrf_{suffix}@local.test',+ password='placeholder-bcrypt-hash')+ db.session.add(user)+ db.session.commit()+ c = app.test_client()+ with c.session_transaction() as sess:+ sess['_user_id'] = str(user.id)+ sess['_fresh'] = True+ yield c+ app.config['WTF_CSRF_ENABLED'] = previous+++def _post(client, base_url, headers=None, token=True, **kwargs):+ h = dict(headers or {})+ if token:+ h['X-CSRFToken'] = client.get('/api/csrf-token', base_url=base_url).get_json()['csrf_token']+ kwargs.setdefault('data', '{}')+ kwargs.setdefault('content_type', 'application/json')+ return client.post('/recording/999999/reset_status', base_url=base_url, headers=h, **kwargs)+++def test_missing_referer_over_https_is_json_and_not_retryable(client):+ r = _post(client, 'https://speakr.example')+ assert r.status_code == 400+ body = r.get_json()+ assert body['csrf_retryable'] is False+ assert 'Referer' in body['error']+ assert 'referrer header is missing' in body['csrf_reason'].lower()+++def test_host_mismatch_names_both_hosts(client):+ r = _post(client, 'https://speakr:8899', headers={'Referer': 'https://speakr.example/recordings'})+ body = r.get_json()+ assert r.status_code == 400+ assert body['csrf_retryable'] is False+ assert 'speakr.example' in body['error'] and 'speakr:8899' in body['error']+ assert 'TRUSTED_PROXY_HOPS' in body['error']+++def test_missing_token_is_retryable(client):+ r = _post(client, 'http://speakr.example', token=False)+ body = r.get_json()+ assert r.status_code == 400+ assert body['csrf_retryable'] is True+ assert 'token' in body['csrf_reason'].lower()+++def test_valid_same_origin_request_passes_csrf(client):+ r = _post(client, 'https://speakr.example', headers={'Referer': 'https://speakr.example/'})+ assert r.status_code != 400+++def test_browser_form_post_keeps_the_html_page(client):+ r = client.post('/recording/999999/reset_status', base_url='http://speakr.example',+ data={'x': '1'}, headers={'Accept': 'text/html,application/xhtml+xml'})+ assert r.status_code == 400+ assert r.mimetype == 'text/html'+++def test_rejection_is_logged_with_hosts(client, caplog):+ with caplog.at_level('WARNING'):+ _post(client, 'https://speakr:8899', headers={'Referer': 'https://speakr.example/'})+ logged = ' '.join(rec.getMessage() for rec in caplog.records)+ assert 'CSRF validation failed' in logged+ assert 'speakr.example' in logged and 'speakr:8899' in logged