Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
API tokens: scopes (read, write, upload, process, share, delete, webhooks, account) and per-token rate limits (mailr spec G1)
Murtaza Nasir8c6e3a63323f
diff --git a/src/api/api_v1.py b/src/api/api_v1.pyindex 987e6f16..7f1709e5 100644--- a/src/api/api_v1.py+++ b/src/api/api_v1.py@@ -25,6 +25,7 @@ from typing import Optionalfrom flask import Blueprint, jsonify, request, current_app, send_file, redirectfrom flask_login import login_required, current_user+from src.utils.token_auth import require_scopefrom sqlalchemy import func, extract, or_, and_from werkzeug.exceptions import RequestEntityTooLargefrom werkzeug.utils import secure_filename@@ -518,12 +519,14 @@ OPENAPI_SPEC = {@api_v1_bp.route('/openapi.json', methods=['GET'])+@require_scope('read')def get_openapi_spec():"""Return OpenAPI specification."""return jsonify(OPENAPI_SPEC)@api_v1_bp.route('/docs', methods=['GET'])+@require_scope('read')def get_docs():"""Serve Swagger UI documentation.@@ -562,6 +565,7 @@ def get_docs():# =============================================================================@api_v1_bp.route('/stats', methods=['GET'])+@require_scope('read')@login_requireddef get_stats():"""@@ -752,7 +756,63 @@ def get_stats():# Current User# =============================================================================+@api_v1_bp.route('/tokens/current', methods=['GET'])+@require_scope()+@login_required+def get_current_token():+ """The API token of this request: id, name, scopes and times (mailr spec G1)."""+ from flask import g+ from src.utils.token_auth import current_api_token+ token = current_api_token()+ if token is None:+ return jsonify({'error': 'No API token in this request', 'code': 'not_found'}), 404++ def _z(dt):+ return dt.isoformat(timespec='microseconds') + 'Z' if dt else None+ return jsonify({+ 'id': token.id,+ 'name': token.name,+ 'scopes': token.scope_list,+ 'created_at': _z(token.created_at),+ 'expires_at': _z(token.expires_at),+ 'last_used_at': _z(token.last_used_at),+ 'via': 'query' if g.get('api_token_via_query') else 'header',+ })+++# Features this server supports (mailr spec G1). A key appears when the feature+# ships; a missing key means false.+CAPABILITY_FEATURES = {+ 'token_scopes': True,+}+++@api_v1_bp.route('/capabilities', methods=['GET'])+@require_scope()+@login_required+def get_capabilities():+ """Feature discovery for API clients; read this instead of the version string."""+ from src.config.version import get_version+ features = dict(CAPABILITY_FEATURES)+ features['internal_sharing'] = os.environ.get('ENABLE_INTERNAL_SHARING', 'false').lower() == 'true'+ features['public_sharing'] = os.environ.get('ENABLE_PUBLIC_SHARING', 'true').lower() == 'true'+ features['can_share_publicly'] = bool(features['public_sharing'] and getattr(current_user, 'can_share_publicly', True))+ features['inquire'] = {+ 'enabled': os.environ.get('ENABLE_INQUIRE_MODE', 'false').lower() == 'true',+ 'agent': os.environ.get('ENABLE_INQUIRE_AGENT', 'false').lower() == 'true',+ }+ return jsonify({+ 'speakr_version': get_version(),+ 'api_version': '1.1',+ 'features': features,+ # True only when the administrator states that the text, chat and+ # embedding endpoints all run on machines they control.+ 'models_local': os.environ.get('MODELS_ARE_LOCAL', 'false').lower() == 'true',+ })++@api_v1_bp.route('/users/me', methods=['GET'])+@require_scope('read')@login_requireddef get_current_user():"""@@ -809,6 +869,7 @@ def get_current_user():# =============================================================================@api_v1_bp.route('/recordings', methods=['GET'])+@require_scope('read')@login_requireddef list_recordings():"""@@ -1001,6 +1062,7 @@ def list_recordings():# =============================================================================@api_v1_bp.route('/recordings/<int:recording_id>', methods=['GET'])+@require_scope('read')@login_requireddef get_recording(recording_id):"""@@ -1071,6 +1133,7 @@ def get_recording(recording_id):# =============================================================================@api_v1_bp.route('/recordings/<int:recording_id>/transcript', methods=['GET'])+@require_scope('read')@login_requireddef get_transcript(recording_id):"""@@ -1160,6 +1223,7 @@ def get_transcript(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/summary', methods=['GET'])+@require_scope('read')@login_requireddef get_summary(recording_id):"""Get summary markdown."""@@ -1177,6 +1241,7 @@ def get_summary(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/notes', methods=['GET'])+@require_scope('read')@login_requireddef get_notes(recording_id):"""Get notes markdown."""@@ -1198,6 +1263,7 @@ def get_notes(recording_id):# =============================================================================@api_v1_bp.route('/recordings/<int:recording_id>', methods=['PATCH'])+@require_scope('write')@login_requireddef update_recording(recording_id):"""@@ -1343,6 +1409,7 @@ def update_recording(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/notes', methods=['PUT'])+@require_scope('write')@login_requireddef replace_notes(recording_id):"""Replace notes entirely."""@@ -1364,6 +1431,7 @@ def replace_notes(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/summary', methods=['PUT'])+@require_scope('write')@login_requireddef replace_summary(recording_id):"""Replace summary entirely."""@@ -1389,6 +1457,7 @@ def replace_summary(recording_id):# =============================================================================@api_v1_bp.route('/recordings/<int:recording_id>', methods=['DELETE'])+@require_scope('delete')@login_requireddef delete_recording(recording_id):"""Delete a recording."""@@ -1420,6 +1489,7 @@ def delete_recording(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/delete-audio', methods=['POST'])+@require_scope('delete')@login_requireddef delete_recording_audio(recording_id):"""Delete a recording's media file and keep its transcript, summary and notes."""@@ -1446,6 +1516,7 @@ def delete_recording_audio(recording_id):# =============================================================================@api_v1_bp.route('/recordings/<int:recording_id>/status', methods=['GET'])+@require_scope('read')@login_requireddef get_recording_status(recording_id):"""Get processing status of a recording."""@@ -1496,6 +1567,7 @@ def _effective_diarize():@api_v1_bp.route('/recordings/<int:recording_id>/regenerate_title', methods=['POST'])+@require_scope('process')@login_requireddef api_regenerate_title(recording_id):"""Regenerate the AI title for a recording based on its existing transcription."""@@ -1508,6 +1580,7 @@ def api_regenerate_title(recording_id):# =============================================================================@api_v1_bp.route('/tags', methods=['GET'])+@require_scope('read')@login_requireddef list_tags():"""List available tags (personal + group tags user has access to)."""@@ -1567,6 +1640,7 @@ def list_tags():@api_v1_bp.route('/tags', methods=['POST'])+@require_scope('write')@login_requireddef create_tag():"""Create a new tag."""@@ -1629,6 +1703,7 @@ def create_tag():@api_v1_bp.route('/tags/<int:tag_id>', methods=['PUT'])+@require_scope('write')@login_requireddef update_tag(tag_id):"""Update a tag."""@@ -1687,6 +1762,7 @@ def update_tag(tag_id):@api_v1_bp.route('/tags/<int:tag_id>', methods=['DELETE'])+@require_scope('delete')@login_requireddef delete_tag(tag_id):"""Delete a tag."""@@ -1718,6 +1794,7 @@ def delete_tag(tag_id):@api_v1_bp.route('/recordings/<int:recording_id>/tags', methods=['POST'])+@require_scope('write')@login_requireddef add_tags_to_recording(recording_id):"""Add tag(s) to a recording."""@@ -1794,6 +1871,7 @@ def add_tags_to_recording(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/tags/<int:tag_id>', methods=['DELETE'])+@require_scope('write')@login_requireddef remove_tag_from_recording(recording_id, tag_id):"""Remove a tag from a recording."""@@ -1836,6 +1914,7 @@ def remove_tag_from_recording(recording_id, tag_id):# =============================================================================@api_v1_bp.route('/folders', methods=['GET'])+@require_scope('read')@login_requireddef list_folders():"""List folders the user can access (personal + group folders)."""@@ -1844,6 +1923,7 @@ def list_folders():@api_v1_bp.route('/folders', methods=['POST'])+@require_scope('write')@login_requireddef create_folder():"""Create a new folder. Accepts the same JSON body as the web endpoint."""@@ -1852,6 +1932,7 @@ def create_folder():@api_v1_bp.route('/folders/<int:folder_id>', methods=['GET'])+@require_scope('read')@login_requireddef get_folder(folder_id):"""Get a single folder by id."""@@ -1884,6 +1965,7 @@ def get_folder(folder_id):@api_v1_bp.route('/folders/<int:folder_id>', methods=['PATCH', 'PUT'])+@require_scope('write')@login_requireddef update_folder(folder_id):"""Update a folder. Same JSON body as the web endpoint."""@@ -1892,6 +1974,7 @@ def update_folder(folder_id):@api_v1_bp.route('/folders/<int:folder_id>', methods=['DELETE'])+@require_scope('delete')@login_requireddef delete_folder(folder_id):"""Delete a folder. Recordings in it are unassigned."""@@ -1904,6 +1987,7 @@ def delete_folder(folder_id):# =============================================================================@api_v1_bp.route('/transcription', methods=['GET'])+@require_scope('read')@login_requireddef get_transcription_info():"""@@ -2010,6 +2094,7 @@ def get_transcription_info():# =============================================================================@api_v1_bp.route('/speakers', methods=['GET'])+@require_scope('read')@login_requireddef list_speakers():"""List all speakers for the current user."""@@ -2030,6 +2115,7 @@ def list_speakers():@api_v1_bp.route('/speakers', methods=['POST'])+@require_scope('write')@login_requireddef create_speaker():"""Create a new speaker."""@@ -2062,6 +2148,7 @@ def create_speaker():@api_v1_bp.route('/speakers/<int:speaker_id>', methods=['PUT'])+@require_scope('write')@login_requireddef update_speaker(speaker_id):"""Update a speaker (cascades name changes to recordings)."""@@ -2106,6 +2193,7 @@ def update_speaker(speaker_id):@api_v1_bp.route('/speakers/<int:speaker_id>', methods=['DELETE'])+@require_scope('delete')@login_requireddef delete_speaker(speaker_id):"""Delete a speaker."""@@ -2123,6 +2211,7 @@ def delete_speaker(speaker_id):@api_v1_bp.route('/recordings/<int:recording_id>/speakers', methods=['GET'])+@require_scope('read')@login_requireddef get_recording_speakers(recording_id):"""Get speakers in a recording with suggestions."""@@ -2198,6 +2287,7 @@ def get_recording_speakers(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/speakers/assign', methods=['PUT'])+@require_scope('write')@login_requireddef assign_speakers(recording_id):"""@@ -2277,6 +2367,7 @@ def assign_speakers(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/speakers/identify', methods=['POST'])+@require_scope('process')@login_requireddef identify_speakers(recording_id):"""@@ -2326,6 +2417,7 @@ def identify_speakers(recording_id):# =============================================================================@api_v1_bp.route('/recordings/<int:recording_id>/transcribe', methods=['POST'])+@require_scope('process')@login_requireddef start_transcription(recording_id):"""Queue transcription for a recording."""@@ -2364,6 +2456,7 @@ def start_transcription(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/summarize', methods=['POST'])+@require_scope('process')@login_requireddef start_summarization(recording_id):"""Queue summarization for a recording with optional custom prompt."""@@ -2401,6 +2494,7 @@ def start_summarization(recording_id):# =============================================================================@api_v1_bp.route('/recordings/<int:recording_id>/chat', methods=['POST'])+@require_scope('process')@login_requireddef chat_with_recording(recording_id):"""Chat about a recording's content."""@@ -2483,6 +2577,7 @@ Notes: {recording.notes or 'None'}# =============================================================================@api_v1_bp.route('/recordings/<int:recording_id>/events', methods=['GET'])+@require_scope('read')@login_requireddef get_recording_events(recording_id):"""Get calendar events extracted from a recording."""@@ -2508,6 +2603,7 @@ def get_recording_events(recording_id):@api_v1_bp.route('/recordings/<int:recording_id>/events/ics', methods=['GET'])+@require_scope('read')@login_requireddef download_events_ics(recording_id):"""Download all events as ICS file."""@@ -2541,6 +2637,7 @@ def download_events_ics(recording_id):# =============================================================================@api_v1_bp.route('/recordings/<int:recording_id>/audio', methods=['GET'])+@require_scope('read')@login_requireddef download_audio(recording_id):"""Download or stream audio file."""@@ -2595,6 +2692,7 @@ def download_audio(recording_id):# =============================================================================@api_v1_bp.route('/recordings/batch', methods=['PATCH'])+@require_scope('write')@login_requireddef batch_update_recordings():"""Batch update multiple recordings."""@@ -2735,6 +2833,7 @@ def batch_update_recordings():@api_v1_bp.route('/recordings/batch', methods=['DELETE'])+@require_scope('delete')@login_requireddef batch_delete_recordings():"""Batch delete multiple recordings."""@@ -2784,6 +2883,7 @@ def batch_delete_recordings():@api_v1_bp.route('/recordings/batch/transcribe', methods=['POST'])+@require_scope('process')@login_requireddef batch_transcribe_recordings():"""Batch queue transcriptions for multiple recordings."""@@ -2832,6 +2932,7 @@ def batch_transcribe_recordings():# =============================================================================@api_v1_bp.route('/settings/auto-summarization', methods=['PUT'])+@require_scope('account')@login_requireddef update_auto_summarization():"""Toggle auto-summarization for the current user."""@@ -2895,6 +2996,7 @@ def _asr_upload_rate_cost():@api_v1_bp.route('/integrations/asr-voice-recorder/upload', methods=['POST'])+@require_scope('upload')@rate_limit(f'{_ASR_RATE_UNITS_PER_MINUTE} per minute', cost=_asr_upload_rate_cost)def upload_from_asr_voice_recorder():"""Accept an ASR Voice Recorder connection test or completed upload."""@@ -2916,6 +3018,10 @@ def upload_from_asr_voice_recorder():owner = load_user_from_token_value(secret)if owner is None:return jsonify({'error': 'Authentication failed'}), 401+ # A scoped token must carry 'upload' (mailr spec G1); full tokens pass.+ _token = request.environ.get('_speakr_secret_token')+ if _token is not None and _token.scope_set is not None and 'upload' not in _token.scope_set:+ return jsonify({'error': 'Authentication failed'}), 401uploaded_file = request.files.get('file')if uploaded_file is None:@@ -2950,6 +3056,7 @@ def upload_from_asr_voice_recorder():@api_v1_bp.route('/recordings/upload', methods=['POST'])+@require_scope('upload')@login_requireddef upload_recording():"""diff --git a/src/api/tokens.py b/src/api/tokens.pyindex 90598b12..36304a26 100644--- a/src/api/tokens.py+++ b/src/api/tokens.py@@ -103,6 +103,14 @@ def create_token():if not isinstance(expires_in_days, int) or expires_in_days < 0:return jsonify({'error': 'expires_in_days must be a non-negative integer'}), 400+ # Scopes (mailr spec G1). Absent = a full token, as before scopes existed.+ scopes_value = None+ if 'scopes' in data:+ from src.models.api_token import parse_scopes+ scopes_value, error = parse_scopes(data.get('scopes'))+ if error:+ return jsonify({'error': error, 'code': 'invalid_parameter'}), 400+# Generate the tokenplaintext_token = generate_token()token_hash = hash_token(plaintext_token)@@ -117,7 +125,8 @@ def create_token():user_id=current_user.id,token_hash=token_hash,name=name,- expires_at=expires_at+ expires_at=expires_at,+ scopes=scopes_value,)db.session.add(api_token)@@ -185,14 +194,28 @@ def update_token(token_id):if not api_token:return jsonify({'error': 'Token not found'}), 404- # Update the name- data = request.get_json()+ data = request.get_json() or {}new_name = data.get('name')-- if not new_name:+ if 'scopes' not in data and not new_name:return jsonify({'error': 'name is required'}), 400- api_token.name = new_name+ # Scopes can only be narrowed (mailr spec G1): a wider set needs a new+ # token, so a stolen session cannot silently widen an integration token.+ if 'scopes' in data:+ from src.models.api_token import parse_scopes, TOKEN_SCOPES+ new_value, error = parse_scopes(data.get('scopes'))+ if error:+ return jsonify({'error': error, 'code': 'invalid_parameter'}), 400+ current = api_token.scope_set+ new = None if new_value is None else frozenset(__import__('json').loads(new_value))+ widening = (new is None and current is not None) or (current is not None and not new <= current)+ if widening:+ return jsonify({'error': 'Scopes can only be narrowed; create a new token for more access',+ 'code': 'invalid_parameter'}), 400+ api_token.scopes = new_value++ if new_name:+ api_token.name = new_namedb.session.commit()return jsonify(api_token.to_dict()), 200diff --git a/src/api/webhooks.py b/src/api/webhooks.pyindex 4160f3d3..1c8d60df 100644--- a/src/api/webhooks.py+++ b/src/api/webhooks.py@@ -13,6 +13,7 @@ from datetime import datetimefrom flask import Blueprint, request, jsonify, current_appfrom flask_login import login_required, current_user+from src.utils.token_auth import require_scopefrom src.database import dbfrom src.models import Webhook, WebhookDelivery, WEBHOOK_EVENT_TYPES, generate_webhook_secret@@ -43,6 +44,7 @@ def _load_owned(webhook_id: int):# ---- Collection ------------------------------------------------------------@webhooks_bp.route('', methods=['GET'])+@require_scope('webhooks')@login_requireddef list_webhooks():"""List the caller's webhooks."""@@ -60,6 +62,7 @@ def list_webhooks():@webhooks_bp.route('', methods=['POST'])+@require_scope('webhooks')@login_requireddef create_webhook():"""Create a webhook.@@ -122,6 +125,7 @@ def create_webhook():# ---- Single resource -------------------------------------------------------@webhooks_bp.route('/<int:webhook_id>', methods=['GET'])+@require_scope('webhooks')@login_requireddef get_webhook(webhook_id):wh, err = _load_owned(webhook_id)@@ -131,6 +135,7 @@ def get_webhook(webhook_id):@webhooks_bp.route('/<int:webhook_id>', methods=['PATCH'])+@require_scope('webhooks')@login_requireddef update_webhook(webhook_id):wh, err = _load_owned(webhook_id)@@ -170,6 +175,7 @@ def update_webhook(webhook_id):@webhooks_bp.route('/<int:webhook_id>', methods=['DELETE'])+@require_scope('webhooks')@login_requireddef delete_webhook(webhook_id):wh, err = _load_owned(webhook_id)@@ -183,6 +189,7 @@ def delete_webhook(webhook_id):# ---- Secret rotation -------------------------------------------------------@webhooks_bp.route('/<int:webhook_id>/rotate-secret', methods=['POST'])+@require_scope('webhooks')@login_requireddef rotate_secret(webhook_id):"""Generate a fresh HMAC secret and return it once."""@@ -197,6 +204,7 @@ def rotate_secret(webhook_id):# ---- Test fire -------------------------------------------------------------@webhooks_bp.route('/<int:webhook_id>/test', methods=['POST'])+@require_scope('webhooks')@login_requireddef test_fire(webhook_id):"""Enqueue a synthetic ``webhook.test`` delivery against this webhook.@@ -235,6 +243,7 @@ def test_fire(webhook_id):# ---- Deliveries listing / replay ------------------------------------------@webhooks_bp.route('/<int:webhook_id>/deliveries', methods=['GET'])+@require_scope('webhooks')@login_requireddef list_deliveries(webhook_id):wh, err = _load_owned(webhook_id)@@ -258,6 +267,7 @@ def list_deliveries(webhook_id):@webhooks_bp.route('/<int:webhook_id>/deliveries/<int:delivery_id>', methods=['GET'])+@require_scope('webhooks')@login_requireddef get_delivery(webhook_id, delivery_id):wh, err = _load_owned(webhook_id)@@ -272,6 +282,7 @@ def get_delivery(webhook_id, delivery_id):@webhooks_bp.route('/<int:webhook_id>/deliveries/<int:delivery_id>/replay', methods=['POST'])+@require_scope('webhooks')@login_requireddef replay_delivery(webhook_id, delivery_id):"""Re-enqueue the delivery as a brand-new attempt with the same payload."""diff --git a/src/app.py b/src/app.pyindex 5ec7d556..55813672 100644--- a/src/app.py+++ b/src/app.py@@ -1,7 +1,7 @@# Speakr - Audio Transcription and Summarization Appimport osimport sys-from flask import Flask, render_template, request, jsonify, send_file, redirect, url_for, flash, Response, make_response+from flask import Flask, render_template, request, jsonify, send_file, redirect, url_for, flash, Response, make_response, sessionfrom urllib.parse import urlparse, urljoin, quotefrom email.utils import encode_rfc2231from markupsafe import Markup@@ -179,10 +179,18 @@ _markdown_instance = markdown.Markdown(extensions=[# limits (login/register/password-reset) are applied via the rate_limit# decorator in src/api/auth.py and src/api/tokens.py._RATELIMIT_ENABLED = os.environ.get('RATELIMIT_ENABLED', 'true').lower() != 'false'+def _token_request_exempt():+ # Token traffic has per-token limits (src/utils/token_auth.require_scope);+ # the app-wide per-IP defaults apply to session traffic only (mailr spec G1).+ from src.utils.token_auth import is_token_request+ return is_token_request()++limiter = Limiter(get_remote_address,app=None, # Defer initializationdefault_limits=["5000 per day", "1000 per hour"],+ default_limits_exempt_when=_token_request_exempt,enabled=_RATELIMIT_ENABLED,)@@ -535,8 +543,34 @@ login_manager.login_view = 'auth.login'login_manager.login_message_category = 'info'bcrypt = Bcrypt()bcrypt.init_app(app)+# Rate-limit headers, including Retry-After on 429 (mailr spec G1).+app.config.setdefault("RATELIMIT_HEADERS_ENABLED", True)limiter.init_app(app) # Initialize the limiter (uses in-memory storage by default)++from flask_limiter.errors import RateLimitExceeded as _RateLimitExceeded++[email protected](_RateLimitExceeded)+def _rate_limit_exceeded(e):+ """The limiter's own 429 response, plus Retry-After in seconds (mailr spec G1)."""+ import time as _time+ resp = e.get_response()+ retry = None+ try:+ current = limiter.current_limit+ if current is not None:+ retry = max(1, int(current.reset_at - _time.time()))+ except Exception:+ retry = None+ if retry is None:+ try:+ retry = int(e.limit.limit.get_expiry())+ except Exception:+ retry = 60+ resp.headers["Retry-After"] = str(retry)+ return resp+# Exempt frequently-polled status endpoints from rate limiting@limiter.request_filterdef exempt_status_endpoints():@@ -635,6 +669,37 @@ def csrf_token_aware_check():csrf.protect()[email protected]_request+def enforce_token_scopes():+ """Scoped API tokens (mailr spec G1), checked before any view runs.++ Sessions and full tokens (scopes NULL, every token made before scopes) pass+ unchanged. A scoped token must come from a header, may only reach routes+ marked with require_scope, and must hold every scope the route needs.+ A refused request therefore has no side effect and fires no webhook.+ """+ if not request.endpoint or request.endpoint == 'static':+ return+ if session.get('_user_id'):+ return # a browser session takes precedence over a token, as in Flask-Login+ from src.utils.token_auth import resolve_request_token, scope_error_response+ api_token, via_query = resolve_request_token()+ if api_token is None or api_token.scope_set is None:+ return+ if via_query:+ resp = jsonify({'error': 'Scoped tokens are accepted only in a header (Authorization: Bearer ...)',+ 'code': 'invalid_token'})+ resp.status_code = 401+ return resp+ view = app.view_functions.get(request.endpoint)+ required = getattr(view, '_required_scopes', None)+ if required is None:+ return scope_error_response(None, api_token)+ missing = required - api_token.scope_set+ if missing:+ return scope_error_response(missing, api_token)++def _csrf_rejection_message(reason):"""Turn a Flask-WTF CSRFError description into something an admin can act on.diff --git a/src/init_db.py b/src/init_db.pyindex c0408c03..5aca4e9b 100644--- a/src/init_db.py+++ b/src/init_db.py@@ -759,6 +759,11 @@ def _run_migrations(app, engine):if add_column_if_not_exists(engine, 'recording', 'title_source', 'VARCHAR(16)'):app.logger.info("Added title_source column to recording table")+ # Token scopes (mailr spec G1). NULL = full access, so existing tokens+ # keep working exactly as before; no backfill.+ if add_column_if_not_exists(engine, 'api_token', 'scopes', 'TEXT'):+ app.logger.info("Added scopes column to api_token table")+# Add file_hash column for duplicate detectionif add_column_if_not_exists(engine, 'recording', 'file_hash', 'VARCHAR(64)'):app.logger.info("Added file_hash column to recording table")diff --git a/src/models/api_token.py b/src/models/api_token.pyindex 37a6a047..5c78ddb8 100644--- a/src/models/api_token.py+++ b/src/models/api_token.py@@ -5,9 +5,35 @@ This module defines the APIToken model for managing user API tokensthat allow authentication via Bearer tokens for automation tools."""+import jsonfrom datetime import datetimefrom src.database import db+# Scopes a token can carry (mailr spec section 3). A token with scopes NULL is a+# full token: every route, as before scopes existed. 'account' covers account+# settings and is separate from 'write' (decision 2026-10-02).+TOKEN_SCOPES = ('read', 'write', 'upload', 'process', 'share', 'delete', 'webhooks', 'account')+FULL_SCOPE = 'full'+++def parse_scopes(value):+ """Validate a requested scope list. Returns (stored_value, error).++ stored_value is None for full access, else a JSON list. error is a message+ for a 400 answer, or None.+ """+ if not isinstance(value, list) or not value or not all(isinstance(v, str) for v in value):+ return None, 'scopes must be a non-empty list of scope names'+ requested = {v.strip() for v in value}+ if FULL_SCOPE in requested:+ if len(requested) > 1:+ return None, "'full' cannot be combined with other scopes"+ return None, None+ unknown = sorted(requested - set(TOKEN_SCOPES))+ if unknown:+ return None, f"Unknown scope(s): {', '.join(unknown)}. Allowed: {', '.join(TOKEN_SCOPES)} or full"+ return json.dumps(sorted(requested)), None+class APIToken(db.Model):"""API Token model for token-based authentication."""@@ -22,6 +48,8 @@ class APIToken(db.Model):last_used_at = db.Column(db.DateTime, nullable=True)expires_at = db.Column(db.DateTime, nullable=True)revoked = db.Column(db.Boolean, default=False, nullable=False, index=True)+ # JSON list of scopes; NULL = full access (every token created before scopes).+ scopes = db.Column(db.Text, nullable=True)# Relationship to Useruser = db.relationship('User', backref=db.backref('api_tokens', lazy=True, cascade='all, delete-orphan'))@@ -37,9 +65,26 @@ class APIToken(db.Model):'created_at': self.created_at.isoformat() if self.created_at else None,'last_used_at': self.last_used_at.isoformat() if self.last_used_at else None,'expires_at': self.expires_at.isoformat() if self.expires_at else None,- 'revoked': self.revoked+ 'revoked': self.revoked,+ 'scopes': self.scope_list,}+ @property+ def scope_set(self):+ """None for a full token, else the frozenset of its scopes."""+ if self.scopes is None:+ return None+ try:+ return frozenset(json.loads(self.scopes))+ except (TypeError, ValueError):+ return frozenset()++ @property+ def scope_list(self):+ """Scopes for API responses: ['full'] for a full token."""+ scopes = self.scope_set+ return [FULL_SCOPE] if scopes is None else sorted(scopes)+def is_expired(self):"""Check if token has expired."""if not self.expires_at:diff --git a/src/utils/token_auth.py b/src/utils/token_auth.pyindex 993889eb..d1f09419 100644--- a/src/utils/token_auth.py+++ b/src/utils/token_auth.py@@ -6,8 +6,10 @@ allowing users to authenticate with Bearer tokens instead of session cookies."""import hashlib+import osfrom datetime import datetime-from flask import request+from functools import wraps+from flask import request, g, has_request_contextfrom src.models import APIToken, User@@ -70,27 +72,72 @@ def hash_token(token):return hashlib.sha256(token.encode()).hexdigest()-def load_user_from_token_value(token):- """Validate a plaintext API token and return its associated user.-- The caller controls where the token came from. Keeping this separate from- request extraction lets narrow integrations authenticate an explicit field- without making that field a global token source for every route.- """+def find_api_token(token):+ """The valid APIToken row for a plaintext token, or None."""if not token:return None-- token_hash = hash_token(token)- api_token = APIToken.query.filter_by(token_hash=token_hash).first()+ api_token = APIToken.query.filter_by(token_hash=hash_token(token)).first()if not api_token or not api_token.is_valid():return None+ return api_token++def _mark_used(api_token):api_token.last_used_at = datetime.utcnow()from src.database import dbdb.session.commit()+++def load_user_from_token_value(token):+ """Validate a plaintext API token and return its associated user.++ The caller controls where the token came from. Keeping this separate from+ request extraction lets narrow integrations authenticate an explicit field+ without making that field a global token source for every route. The+ matched row is kept on flask.g.api_token for scope and rate-limit checks.+ """+ api_token = find_api_token(token)+ if api_token is None:+ return None+ _mark_used(api_token)+ if has_request_context():+ g.api_token = api_token+ request.environ['_speakr_secret_token'] = api_tokenreturn api_token.user+def resolve_request_token():+ """The API token of this request and whether it came from ?token=.++ Resolved once per request and cached on the request itself (its WSGI+ environ), never on flask.g: g lives as long as the app context, which a+ test or a background job can keep across several requests, and a token+ from an earlier request must never authenticate a later one. The scope+ check, the rate-limit key and Flask-Login's request_loader all use the+ same row. Returns (APIToken or None, via_query).+ """+ env = request.environ+ if '_speakr_api_token' not in env:+ header_value = extract_token_from_request(headers_only=True)+ value = header_value or extract_token_from_request()+ api_token = find_api_token(value)+ env['_speakr_api_token'] = (api_token, bool(api_token is not None and not header_value))+ api_token, via_query = env['_speakr_api_token']+ g.api_token = api_token+ g.api_token_via_query = via_query+ return api_token, via_query+++def current_api_token():+ """The API token authenticating this request, or None for a session request."""+ if not has_request_context():+ return None+ from flask import session+ if session.get('_user_id'):+ return None+ return resolve_request_token()[0]++def load_user_from_token():"""Load a user from an API token in the request.@@ -101,7 +148,91 @@ def load_user_from_token():Returns:User: The authenticated user, or None if authentication fails"""- return load_user_from_token_value(extract_token_from_request())+ api_token, _ = resolve_request_token()+ if api_token is None:+ return None+ _mark_used(api_token)+ return api_token.user+++# --- Scopes (mailr spec G1) -------------------------------------------------++# Per-token limits by kind of route; configurable by env. Applied only to+# requests authenticated by a token, keyed by the token id.+_RATE_LIMITS = {+ 'read': os.environ.get('API_TOKEN_RATE_LIMIT_READ', '120 per minute'),+ 'write': os.environ.get('API_TOKEN_RATE_LIMIT_WRITE', '30 per minute'),+ 'process': os.environ.get('API_TOKEN_RATE_LIMIT_PROCESS', '10 per minute'),+}+++def _rate_category(scopes):+ if 'process' in scopes:+ return 'process'+ if not scopes or scopes == {'read'}:+ return 'read'+ return 'write'+++def token_rate_key():+ """Rate-limit key: the token id for token requests, else the client address."""+ api_token = current_api_token()+ if api_token is not None:+ return f"token:{api_token.id}"+ from flask_limiter.util import get_remote_address+ return get_remote_address()+++def is_token_request():+ """True when this request is authenticated by an API token (not a session)."""+ return current_api_token() is not None+++def require_scope(*scopes):+ """Mark a view with the scopes a scoped token needs, and apply the per-token+ rate limit for its kind (read, write or process).++ require_scope() with no scopes accepts any valid token. The check itself runs+ in the before_request hook in src/app.py, before the view, so a refused+ request has no side effect. Full tokens and sessions are not restricted.+ """+ required = frozenset(scopes)+ limit_string = _RATE_LIMITS[_rate_category(set(scopes))]++ def decorator(f):+ state = {'limited': None}++ @wraps(f)+ def wrapper(*args, **kwargs):+ from src.app import limiter+ if limiter is not None and getattr(limiter, 'enabled', True):+ if state['limited'] is None:+ state['limited'] = limiter.limit(+ limit_string, key_func=token_rate_key,+ exempt_when=lambda: not is_token_request(),+ scope=lambda endpoint: f"token-{_rate_category(set(scopes))}",+ )(f)+ return state['limited'](*args, **kwargs)+ return f(*args, **kwargs)++ wrapper._required_scopes = required+ return wrapper+ return decorator+++def scope_error_response(missing, api_token):+ """The 403 answer for a scoped token without the needed scope."""+ from flask import jsonify+ names = sorted(missing or [])+ message = (f"This token does not have the '{names[0]}' scope" if len(names) == 1+ else f"This token does not have the scopes {', '.join(names)}" if names+ else "This token cannot be used on this route; use a full-access token or a session")+ resp = jsonify({'error': message, 'code': 'insufficient_scope',+ 'required_scopes': names, 'token_scopes': sorted(api_token.scope_set or [])})+ resp.status_code = 403+ resp.headers['WWW-Authenticate'] = 'Bearer error="insufficient_scope"' + (+ f', scope="{" ".join(names)}"' if names else '')+ return respdef load_user_from_token_headers_only():diff --git a/templates/account.html b/templates/account.htmlindex ba8d2922..e66211ed 100644--- a/templates/account.html+++ b/templates/account.html@@ -2460,6 +2460,28 @@ curl "https://your-speakr-instance.com/api/recordings?token=YOUR_TOKEN_HERE"</co<p class="text-xs text-[var(--text-light)] mt-1">When this token should expire</p></div>+ <div>+ <label for="tokenScopePreset" class="block text-sm font-medium text-[var(--text-secondary)] mb-1">Access</label>+ <select id="tokenScopePreset" class="w-full px-3 py-2 border border-[var(--border-secondary)] rounded-md focus:outline-none focus:ring-2 focus:ring-[var(--border-focus)] bg-[var(--bg-input)] text-[var(--text-primary)]">+ <option value="read">Read only</option>+ <option value="read,write,upload">Integration (read, write, upload)</option>+ <option value="upload">Recorder (upload only)</option>+ <option value="full">Full access (everything this account can do)</option>+ <option value="custom">Custom</option>+ </select>+ <div id="tokenScopeBoxes" class="hidden mt-2 grid gap-1">+ <label class="flex items-start gap-2 text-xs text-[var(--text-secondary)]"><input type="checkbox" class="token-scope-box mt-0.5" value="read"> <span><span class="font-medium text-[var(--text-primary)]">read</span>: Read recordings, transcripts, summaries, notes, tags and folders</span></label>+ <label class="flex items-start gap-2 text-xs text-[var(--text-secondary)]"><input type="checkbox" class="token-scope-box mt-0.5" value="write"> <span><span class="font-medium text-[var(--text-primary)]">write</span>: Edit recordings, notes, summaries, tags, folders and speakers</span></label>+ <label class="flex items-start gap-2 text-xs text-[var(--text-secondary)]"><input type="checkbox" class="token-scope-box mt-0.5" value="upload"> <span><span class="font-medium text-[var(--text-primary)]">upload</span>: Upload recordings</span></label>+ <label class="flex items-start gap-2 text-xs text-[var(--text-secondary)]"><input type="checkbox" class="token-scope-box mt-0.5" value="process"> <span><span class="font-medium text-[var(--text-primary)]">process</span>: Transcribe, summarize, chat and other model calls</span></label>+ <label class="flex items-start gap-2 text-xs text-[var(--text-secondary)]"><input type="checkbox" class="token-scope-box mt-0.5" value="share"> <span><span class="font-medium text-[var(--text-primary)]">share</span>: Create and revoke share links</span></label>+ <label class="flex items-start gap-2 text-xs text-[var(--text-secondary)]"><input type="checkbox" class="token-scope-box mt-0.5" value="delete"> <span><span class="font-medium text-[var(--text-primary)]">delete</span>: Delete recordings, audio, tags, folders and speakers</span></label>+ <label class="flex items-start gap-2 text-xs text-[var(--text-secondary)]"><input type="checkbox" class="token-scope-box mt-0.5" value="webhooks"> <span><span class="font-medium text-[var(--text-primary)]">webhooks</span>: Manage webhooks</span></label>+ <label class="flex items-start gap-2 text-xs text-[var(--text-secondary)]"><input type="checkbox" class="token-scope-box mt-0.5" value="account"> <span><span class="font-medium text-[var(--text-primary)]">account</span>: Change account settings</span></label>+ </div>+ <p class="text-xs text-[var(--text-light)] mt-1">Give an integration only the access it needs, and an expiry date. Scoped tokens work only in the Authorization header, and only on the API.</p>+ </div>+<div class="bg-amber-50 border border-amber-200 rounded-lg p-3"><div class="flex"><i class="fas fa-info-circle text-amber-500 mr-2 mt-0.5"></i>@@ -6158,6 +6180,12 @@ curl "https://your-speakr-instance.com/api/recordings?token=YOUR_TOKEN_HERE"</co</div></div>+ <!-- Scopes -->+ <div class="mt-2 text-[10px] text-[var(--text-muted)]">+ <i class="fas fa-shield-alt opacity-60"></i>+ ${(token.scopes || ['full']).includes('full') ? 'Full access' : escapeHtml((token.scopes || []).join(', '))}+ </div>+<!-- Expiration badge --><div class="mt-2">${token.expires_at ? `@@ -6319,12 +6347,25 @@ curl "https://your-speakr-instance.com/api/recordings?token=YOUR_TOKEN_HERE"</co}});+ document.getElementById('tokenScopePreset')?.addEventListener('change', (e) => {+ document.getElementById('tokenScopeBoxes').classList.toggle('hidden', e.target.value !== 'custom');+ });+// Form submission handlercreateTokenForm?.addEventListener('submit', async (e) => {e.preventDefault();const tokenName = document.getElementById('tokenNameInput').value.trim();const expiresInDays = parseInt(document.getElementById('tokenExpirationSelect').value);+ // Scopes (mailr spec G1): a preset, or the ticked boxes for Custom.+ const preset = document.getElementById('tokenScopePreset').value;+ const scopes = preset === 'custom'+ ? Array.from(document.querySelectorAll('.token-scope-box:checked')).map(b => b.value)+ : preset.split(',');+ if (!scopes.length) {+ showToast('Choose at least one kind of access', 'error');+ return;+ }if (!tokenName) {showToast('Please enter a token name', 'error');@@ -6341,7 +6382,8 @@ curl "https://your-speakr-instance.com/api/recordings?token=YOUR_TOKEN_HERE"</co},body: JSON.stringify({name: tokenName,- expires_in_days: expiresInDays+ expires_in_days: expiresInDays,+ scopes: scopes})});diff --git a/tests/test_api_token_scopes.py b/tests/test_api_token_scopes.pynew file mode 100644index 00000000..7b0e0d8b--- /dev/null+++ b/tests/test_api_token_scopes.py@@ -0,0 +1,257 @@+"""Scoped API tokens (mailr spec G1).++A token with scopes NULL is a full token and behaves exactly as before scopes+existed. A scoped token is accepted only in a header, only on routes marked+with require_scope, and only with every scope the route needs; a refused+request has no side effect.++SHARED-DB: users, tokens and recordings are removed afterwards.+"""++import io+import json+import os+import secrets+import sys+from unittest.mock import patch++import pytest+from flask import g, has_app_context+from flask.testing import FlaskClient++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from src.app import app, db+from src.models import APIToken, Recording, User, Webhook, WebhookDelivery+from src.utils.token_auth import hash_token++app.config["WTF_CSRF_ENABLED"] = False+++class _Client(FlaskClient):+ def open(self, *args, **kwargs):+ if has_app_context():+ g.pop('_login_user', None)+ return super().open(*args, **kwargs)+++def world():+ made = {"tokens": [], "recs": []}+ with app.app_context():+ n = f"scope_{secrets.token_hex(4)}"+ u = User(username=n, email=f"{n}@local.test", password="x")+ db.session.add(u)+ db.session.commit()+ r = Recording(user_id=u.id, title="Original title", status="COMPLETED", original_filename="s.wav",+ transcription="Speaker 1: hello there, this is a test transcript.")+ db.session.add(r)+ db.session.commit()+ made.update(user=u.id, rec=r.id)++ def token(scopes):+ plain = f"tok-{secrets.token_urlsafe(16)}"+ with app.app_context():+ t = APIToken(user_id=made["user"], token_hash=hash_token(plain), name="t",+ scopes=None if scopes is None else json.dumps(sorted(scopes)))+ db.session.add(t)+ db.session.commit()+ made["tokens"].append(t.id)+ return plain+ made["token"] = token+ yield made+ with app.app_context():+ db.session.rollback()+ WebhookDelivery.query.filter(WebhookDelivery.webhook_id.in_(+ [w.id for w in Webhook.query.filter_by(user_id=made["user"]).all()])).delete(synchronize_session=False)+ Webhook.query.filter_by(user_id=made["user"]).delete()+ for tid in made["tokens"]:+ obj = db.session.get(APIToken, tid)+ if obj is not None:+ db.session.delete(obj)+ APIToken.query.filter_by(user_id=made["user"]).delete()+ for rid in [made["rec"], *made["recs"]]:+ obj = db.session.get(Recording, rid)+ if obj is not None:+ db.session.delete(obj)+ db.session.delete(db.session.get(User, made["user"]))+ db.session.commit()+++def _h(plain):+ return {"Authorization": f"Bearer {plain}"}+++def _title(rid):+ with app.app_context():+ return db.session.get(Recording, rid).title+++# ------------------------------------------------------------ full tokens++def test_a_full_token_works_everywhere_as_before(world):+ plain = world["token"](None)+ with app.test_client() as c:+ assert c.get("/api/v1/recordings", headers=_h(plain)).status_code == 200+ assert c.patch(f"/api/v1/recordings/{world['rec']}", json={"title": "Renamed"}, headers=_h(plain)).status_code == 200+ assert c.get("/api/recordings", headers=_h(plain)).status_code == 200 # web-UI route+ assert c.get(f"/api/v1/recordings?token={plain}").status_code == 200 # query token+ assert _title(world["rec"]) == "Renamed"+++# ------------------------------------------------------------ read token++def test_a_read_token_reads(world):+ plain = world["token"](["read"])+ with app.test_client() as c:+ for path in ("/api/v1/users/me", "/api/v1/stats", "/api/v1/recordings", f"/api/v1/recordings/{world['rec']}",+ f"/api/v1/recordings/{world['rec']}/transcript", f"/api/v1/recordings/{world['rec']}/summary",+ f"/api/v1/recordings/{world['rec']}/notes", f"/api/v1/recordings/{world['rec']}/speakers",+ f"/api/v1/recordings/{world['rec']}/events", "/api/v1/tags", "/api/v1/folders"):+ resp = c.get(path, headers=_h(plain))+ assert resp.status_code != 403, (path, resp.get_json())++[email protected]("method,path,body,needed", [+ ("patch", "/api/v1/recordings/{rec}", {"title": "Hacked"}, "write"),+ ("put", "/api/v1/recordings/{rec}/notes", {"notes": "x"}, "write"),+ ("delete", "/api/v1/recordings/{rec}", None, "delete"),+ ("post", "/api/v1/recordings/{rec}/chat", {"message": "hi"}, "process"),+ ("post", "/api/v1/recordings/{rec}/transcribe", {}, "process"),+ ("get", "/api/v1/webhooks", None, "webhooks"),+ ("put", "/api/v1/settings/auto-summarization", {"enabled": False}, "account"),+])+def test_a_read_token_is_refused_with_no_side_effect(world, method, path, body, needed):+ plain = world["token"](["read"])+ with app.test_client() as c:+ kwargs = {"headers": _h(plain)}+ if body is not None:+ kwargs["json"] = body+ resp = getattr(c, method)(path.format(rec=world["rec"]), **kwargs)+ assert resp.status_code == 403+ data = resp.get_json()+ assert data["code"] == "insufficient_scope"+ assert data["required_scopes"] == [needed] and data["token_scopes"] == ["read"]+ assert resp.headers["WWW-Authenticate"] == f'Bearer error="insufficient_scope", scope="{needed}"'+ with app.app_context():+ r = db.session.get(Recording, world["rec"])+ assert r is not None and r.title == "Original title" and r.notes is None+++def test_a_refused_request_fires_no_webhook(world):+ with app.app_context():+ wh = Webhook(user_id=world["user"], name="mailr", url="https://example.com/hook", secret="s" * 32,+ events=json.dumps(["recording.updated"]))+ db.session.add(wh)+ db.session.commit()+ before = WebhookDelivery.query.filter_by(webhook_id=wh.id).count()+ plain = world["token"](["read"])+ with app.test_client() as c:+ assert c.patch(f"/api/v1/recordings/{world['rec']}", json={"title": "x"}, headers=_h(plain)).status_code == 403+ with app.app_context():+ assert WebhookDelivery.query.filter_by(webhook_id=wh.id).count() == before+++def test_a_scoped_token_is_refused_outside_v1(world):+ plain = world["token"](["read", "write", "share", "process"])+ with app.test_client() as c:+ assert c.post("/save", json={"id": world["rec"], "title": "x"}, headers=_h(plain)).status_code == 403+ assert c.get("/api/recordings", headers=_h(plain)).status_code == 403+ assert c.post("/api/inquire/search", json={"query": "x"}, headers=_h(plain)).status_code == 403+ assert c.get("/api/tokens", headers=_h(plain)).status_code == 403 # never manages tokens+ assert _title(world["rec"]) == "Original title"+++def test_a_scoped_token_in_the_query_string_is_refused(world):+ plain = world["token"](["read"])+ with app.test_client() as c:+ resp = c.get(f"/api/v1/recordings?token={plain}")+ assert resp.status_code == 401+++def test_asr_recorder_secret_needs_upload(world):+ up, ro = world["token"](["upload"]), world["token"](["read"])+ with app.test_client() as c:+ ok = c.post("/api/v1/integrations/asr-voice-recorder/upload", data={"secret": up},+ content_type="multipart/form-data")+ bad = c.post("/api/v1/integrations/asr-voice-recorder/upload", data={"secret": ro},+ content_type="multipart/form-data")+ assert ok.status_code == 200 and ok.get_json().get("connection_test") is True+ assert bad.status_code == 401+++# ------------------------------------------------------------ management++def _session(world):+ c = _Client(app, app.response_class, use_cookies=True)+ with c.session_transaction() as sess:+ sess["_user_id"] = str(world["user"])+ return c++[email protected]("scopes", [["bogus"], [], ["full", "read"], "read"])+def test_creating_a_token_with_bad_scopes_is_refused(world, scopes):+ resp = _session(world).post("/api/tokens", json={"name": "x", "scopes": scopes})+ assert resp.status_code == 400 and resp.get_json()["code"] == "invalid_parameter"+++def test_creating_tokens_with_and_without_scopes(world):+ c = _session(world)+ scoped = c.post("/api/tokens", json={"name": "mailr", "scopes": ["write", "read", "upload"]})+ full = c.post("/api/tokens", json={"name": "script"})+ assert scoped.status_code == 201 and scoped.get_json()["scopes"] == ["read", "upload", "write"]+ assert full.status_code == 201 and full.get_json()["scopes"] == ["full"]+ listed = {t["name"]: t["scopes"] for t in c.get("/api/tokens").get_json()["tokens"]}+ assert listed["mailr"] == ["read", "upload", "write"] and listed["script"] == ["full"]+++def test_scopes_can_only_be_narrowed(world):+ c = _session(world)+ tid = c.post("/api/tokens", json={"name": "n", "scopes": ["read", "write"]}).get_json()["id"]+ assert c.patch(f"/api/tokens/{tid}", json={"scopes": ["read", "write", "delete"]}).status_code == 400+ assert c.patch(f"/api/tokens/{tid}", json={"scopes": ["full"]}).status_code == 400+ ok = c.patch(f"/api/tokens/{tid}", json={"scopes": ["read"]})+ assert ok.status_code == 200 and ok.get_json()["scopes"] == ["read"]+ fid = c.post("/api/tokens", json={"name": "f"}).get_json()["id"]+ assert c.patch(f"/api/tokens/{fid}", json={"scopes": ["read"]}).status_code == 200+++# ------------------------------------------------------------ introspection++def test_tokens_current_and_capabilities(world):+ plain = world["token"](["read", "upload"])+ with app.test_client() as c:+ cur = c.get("/api/v1/tokens/current", headers=_h(plain))+ caps = c.get("/api/v1/capabilities", headers=_h(plain))+ assert cur.status_code == 200+ body = cur.get_json()+ assert body["scopes"] == ["read", "upload"] and body["via"] == "header"+ assert body["created_at"].endswith("Z")+ assert caps.status_code == 200 and caps.get_json()["features"]["token_scopes"] is True+ assert caps.get_json()["models_local"] in (True, False)+ assert _session(world).get("/api/v1/tokens/current").status_code == 404+++# ------------------------------------------------------------ rate limits++def test_rate_limits_are_per_token():+ from src.utils import token_auth as ta+ for tid in (41, 42):+ with app.test_request_context("/api/v1/recordings"):+ from flask import request+ request.environ["_speakr_api_token"] = (type("T", (), {"id": tid})(), False)+ assert ta.token_rate_key() == f"token:{tid}"+ assert ta._RATE_LIMITS == {"read": "120 per minute", "write": "30 per minute", "process": "10 per minute"} \+ or os.environ.get("API_TOKEN_RATE_LIMIT_READ")+ assert ta._rate_category({"read"}) == "read"+ assert ta._rate_category({"process"}) == "process"+ assert ta._rate_category({"write"}) == "write" and ta._rate_category({"delete"}) == "write"+++def test_a_token_never_carries_over_to_the_next_request(world):+ """g outlives a request when a caller holds an app context; the token must not."""+ plain = world["token"](None)+ with app.app_context():+ with _Client(app, app.response_class) as c: # drops Flask-Login's own g cache, as a new request does+ assert c.get("/api/v1/recordings", headers=_h(plain)).status_code == 200+ assert c.get("/api/v1/recordings").status_code == 401diff --git a/tests/test_api_v1_scope_coverage.py b/tests/test_api_v1_scope_coverage.pynew file mode 100644index 00000000..e073de20--- /dev/null+++ b/tests/test_api_v1_scope_coverage.py@@ -0,0 +1,59 @@+"""Every API v1 and webhook route declares its token scope (mailr spec G1).++Scoped tokens are refused on any route without require_scope, so a new route+that forgets one is unusable for scoped tokens; this test fails first, with+the endpoint named. The table is the scope design: change it deliberately.+"""++import os+import sys++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from src.app import app++EXPECTED = {+ "read": {"get_openapi_spec", "get_docs", "get_stats", "get_current_user", "list_recordings", "get_recording",+ "get_transcript", "get_summary", "get_notes", "get_recording_status", "list_tags", "list_folders",+ "get_folder", "get_transcription_info", "list_speakers", "get_recording_speakers",+ "get_recording_events", "download_events_ics", "download_audio"},+ "write": {"update_recording", "replace_notes", "replace_summary", "create_tag", "update_tag",+ "add_tags_to_recording", "remove_tag_from_recording", "create_folder", "update_folder",+ "create_speaker", "update_speaker", "assign_speakers", "batch_update_recordings"},+ "account": {"update_auto_summarization"},+ "upload": {"upload_recording", "upload_from_asr_voice_recorder"},+ "process": {"api_regenerate_title", "identify_speakers", "start_transcription", "start_summarization",+ "chat_with_recording", "batch_transcribe_recordings"},+ "delete": {"delete_recording", "delete_recording_audio", "batch_delete_recordings", "delete_tag",+ "delete_folder", "delete_speaker"},+ "webhooks": {"list_webhooks", "create_webhook", "get_webhook", "update_webhook", "delete_webhook",+ "rotate_secret", "test_fire", "list_deliveries", "get_delivery", "replay_delivery"},+ "": {"get_current_token", "get_capabilities"}, # any valid token+}+++def _actual():+ found = {}+ for rule in app.url_map.iter_rules():+ bp = rule.endpoint.split(".", 1)[0]+ if bp not in ("api_v1", "webhooks"):+ continue+ view = app.view_functions[rule.endpoint]+ name = rule.endpoint.split(".", 1)[1]+ scopes = getattr(view, "_required_scopes", None)+ found[name] = None if scopes is None else ",".join(sorted(scopes))+ return found+++def test_every_v1_and_webhook_route_declares_a_scope():+ missing = sorted(name for name, scopes in _actual().items() if scopes is None)+ assert not missing, f"routes without require_scope: {missing}"+++def test_scopes_match_the_design_table():+ expected = {name: scope for scope, names in EXPECTED.items() for name in names}+ actual = _actual()+ assert set(actual) == set(expected), (+ f"not in table: {sorted(set(actual) - set(expected))}; gone: {sorted(set(expected) - set(actual))}")+ wrong = {n: (actual[n], expected[n]) for n in actual if actual[n] != expected[n]}+ assert not wrong, f"scope differs (actual, expected): {wrong}"diff --git a/tests/test_inquire_mode.py b/tests/test_inquire_mode.pyindex 2d769369..dc902e11 100644--- a/tests/test_inquire_mode.py+++ b/tests/test_inquire_mode.py@@ -117,7 +117,17 @@ def test_chunking_functions():# not return None placeholders. sentence-transformers isn't a hard# dependency (it's absent in CI), so assert whichever applies here.from src.services.embeddings import USE_API_EMBEDDINGS, LOCAL_EMBEDDINGS_AVAILABLE- embeddings = generate_embeddings(["test sentence", "another test"])+ # In API mode the embedding server itself is stubbed: this test checks+ # the helper's contract, not a live service (a busy or remote endpoint+ # made it flaky; #412 F2).+ from contextlib import nullcontext+ from unittest.mock import patch as _patch+ import numpy as _np+ stub = (_patch("src.services.embeddings._api_embed",+ side_effect=lambda texts, user_id=None: [_np.ones(8, dtype=_np.float32) for _ in texts])+ if USE_API_EMBEDDINGS else nullcontext())+ with stub:+ embeddings = generate_embeddings(["test sentence", "another test"])assert isinstance(embeddings, list)if USE_API_EMBEDDINGS or LOCAL_EMBEDDINGS_AVAILABLE:assert len(embeddings) == 2, "one embedding per input when a backend is available"diff --git a/tests/test_upgrade_mailr_api.py b/tests/test_upgrade_mailr_api.pynew file mode 100644index 00000000..c43d6f11--- /dev/null+++ b/tests/test_upgrade_mailr_api.py@@ -0,0 +1,61 @@+"""Upgrade path for the mailr API migrations (spec section 2).++Each historical schema fixture is loaded, rows are seeded the way a real+installation holds them, the current migrations run, and the new columns are+checked: present, with their default, and no existing value changed. A second+startup must be a no-op. New migrations in this work add a case below.+"""++import os+import sqlite3+import sys++import pytest++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from tests.test_upgrade_path import FIXTURE_DIR, FIXTURES, _fixture_app+from src.init_db import initialize_database+++def _load(tmp_path, fixture):+ db_path = str(tmp_path / fixture.replace(".sql", ".db"))+ con = sqlite3.connect(db_path)+ con.executescript(open(os.path.join(FIXTURE_DIR, fixture)).read())+ con.commit()+ return db_path, con+++def _columns(con, table):+ return {row[1] for row in con.execute(f'PRAGMA table_info("{table}")')}+++def _upgrade(db_path):+ app = _fixture_app(db_path)+ with app.app_context():+ initialize_database(app)+ return app++[email protected]("fixture", FIXTURES, ids=[f[:-4] for f in FIXTURES])+def test_api_token_scopes_column(tmp_path, fixture):+ db_path, con = _load(tmp_path, fixture)+ if "api_token" not in {r[0] for r in con.execute("SELECT name FROM sqlite_master WHERE type='table'")}:+ con.close()+ pytest.skip("api_token table not in this release")+ con.execute('INSERT INTO "user" (id, username, email, password) VALUES (1, ?, ?, ?)',+ ("u", "[email protected]", "hash"))+ con.execute("INSERT INTO api_token (id, user_id, token_hash, name, created_at, expires_at, revoked) "+ "VALUES (5, 1, 'abc123', 'n8n', '2026-01-01 00:00:00', '2027-01-01 00:00:00', 1)")+ con.commit()+ con.close()++ _upgrade(db_path)+ _upgrade(db_path) # second start: no-op, no error++ con = sqlite3.connect(db_path)+ assert "scopes" in _columns(con, "api_token")+ row = con.execute("SELECT token_hash, name, expires_at, revoked, scopes FROM api_token WHERE id = 5").fetchone()+ con.close()+ assert row[:4] == ("abc123", "n8n", "2027-01-01 00:00:00", 1)+ assert row[4] is None, "existing tokens keep full access (scopes NULL)"