Skip to content

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.py
index 987e6f16..7f1709e5 100644
--- a/src/api/api_v1.py
+++ b/src/api/api_v1.py
@@ -25,6 +25,7 @@ from typing import Optional
from flask import Blueprint, jsonify, request, current_app, send_file, redirect
from flask_login import login_required, current_user
+from src.utils.token_auth import require_scope
from sqlalchemy import func, extract, or_, and_
from werkzeug.exceptions import RequestEntityTooLarge
from 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_required
def 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_required
def get_current_user():
"""
@@ -809,6 +869,7 @@ def get_current_user():
# =============================================================================
@api_v1_bp.route('/recordings', methods=['GET'])
+@require_scope('read')
@login_required
def list_recordings():
"""
@@ -1001,6 +1062,7 @@ def list_recordings():
# =============================================================================
@api_v1_bp.route('/recordings/<int:recording_id>', methods=['GET'])
+@require_scope('read')
@login_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def get_transcription_info():
"""
@@ -2010,6 +2094,7 @@ def get_transcription_info():
# =============================================================================
@api_v1_bp.route('/speakers', methods=['GET'])
+@require_scope('read')
@login_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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'}), 401
uploaded_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_required
def upload_recording():
"""
diff --git a/src/api/tokens.py b/src/api/tokens.py
index 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 token
plaintext_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_name
db.session.commit()
return jsonify(api_token.to_dict()), 200
diff --git a/src/api/webhooks.py b/src/api/webhooks.py
index 4160f3d3..1c8d60df 100644
--- a/src/api/webhooks.py
+++ b/src/api/webhooks.py
@@ -13,6 +13,7 @@ from datetime import datetime
from flask import Blueprint, request, jsonify, current_app
from flask_login import login_required, current_user
+from src.utils.token_auth import require_scope
from src.database import db
from 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_required
def list_webhooks():
"""List the caller's webhooks."""
@@ -60,6 +62,7 @@ def list_webhooks():
@webhooks_bp.route('', methods=['POST'])
+@require_scope('webhooks')
@login_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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_required
def 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.py
index 5ec7d556..55813672 100644
--- a/src/app.py
+++ b/src/app.py
@@ -1,7 +1,7 @@
# Speakr - Audio Transcription and Summarization App
import os
import 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, session
from urllib.parse import urlparse, urljoin, quote
from email.utils import encode_rfc2231
from 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 initialization
default_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_filter
def exempt_status_endpoints():
@@ -635,6 +669,37 @@ def csrf_token_aware_check():
csrf.protect()
+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.py
index 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 detection
if 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.py
index 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 tokens
that allow authentication via Bearer tokens for automation tools.
"""
+import json
from datetime import datetime
from 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 User
user = 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.py
index 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 os
from datetime import datetime
-from flask import request
+from functools import wraps
+from flask import request, g, has_request_context
from 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 db
db.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_token
return 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 resp
def load_user_from_token_headers_only():
diff --git a/templates/account.html b/templates/account.html
index 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 handler
createTokenForm?.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.py
new file mode 100644
index 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 == 401
diff --git a/tests/test_api_v1_scope_coverage.py b/tests/test_api_v1_scope_coverage.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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)"