Skip to content

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.md
index 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 c
Firewall 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 Fails
If 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.py
index 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_user
from flask_bcrypt import Bcrypt
from flask_wtf import FlaskForm
-from flask_wtf.csrf import CSRFProtect
+from flask_wtf.csrf import CSRFProtect, CSRFError
from wtforms import StringField, PasswordField, SubmitField, BooleanField
from wtforms.validators import DataRequired, Length, Email, EqualTo, ValidationError
from 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.'
+
+
+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.js
index 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.js
index 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.js
index 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.js
index 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.py
new file mode 100644
index 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