Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python
12.2 KB
Raw Blame
"""
Token authentication utilities.

This module provides token-based authentication for API access,
allowing users to authenticate with Bearer tokens instead of session cookies.
"""

import hashlib
import os
import threading
from datetime import datetime
from functools import wraps
from flask import request, g, has_request_context
from src.models import APIToken, User


def extract_token_from_request(headers_only=False):
    """
    Extract API token from various possible locations in the request.

    Checks in order:
    1. Authorization header with Bearer scheme
    2. X-API-Token header
    3. API-Token header
    4. 'token' query parameter (only when ``headers_only=False``)

    The ``headers_only`` flag exists because the query-string token can
    be triggered by a Simple Cross-Origin Request without CORS preflight
    (see GHSA-x4q4-3ww4-h329). Code paths that make security decisions
    based on whether a request is API-token-authenticated MUST pass
    ``headers_only=True`` so an attacker cannot place ``?token=...`` on
    a victim-browser URL to fake API authentication.

    Returns:
        str: The extracted token, or None if not found
    """
    # Check Authorization header (Bearer token)
    auth_header = request.headers.get('Authorization', '')
    if auth_header.startswith('Bearer '):
        return auth_header[7:]  # Remove 'Bearer ' prefix

    # Check X-API-Token header
    token = request.headers.get('X-API-Token')
    if token:
        return token

    # Check API-Token header
    token = request.headers.get('API-Token')
    if token:
        return token

    if headers_only:
        return None

    # Check query parameter
    token = request.args.get('token')
    if token:
        return token

    return None


def hash_token(token):
    """
    Hash a token using SHA-256.

    Args:
        token (str): The plaintext token to hash

    Returns:
        str: The hexadecimal hash of the token
    """
    return hashlib.sha256(token.encode()).hexdigest()


def find_api_token(token):
    """The valid APIToken row for a plaintext token, or None."""
    if not token:
        return None
    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.

    This function is used by Flask-Login's request_loader to authenticate
    users via API tokens instead of sessions.

    Returns:
        User: The authenticated user, or None if authentication fails
    """
    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 _doubled(limit_string):
    """The same limit with twice the requests, or None when it cannot be parsed."""
    from limits import parse_many
    try:
        items = parse_many(limit_string)
    except ValueError:
        return None
    return '; '.join(
        f"{2 * item.amount} per {'' if item.multiples == 1 else f'{item.multiples} '}{item.GRANULARITY.name}"
        for item in items)


# Account limits (#484): on each endpoint, all tokens of one user draw on one
# budget per kind, so another token adds no throughput there. Like the token
# budget it is counted per endpoint, so a client that polls several endpoints
# is not held by it. The default is twice the per-token limit, so a client
# with a single token is held by its token limit.
_USER_RATE_LIMITS = {
    kind: os.environ.get(f'API_USER_RATE_LIMIT_{kind.upper()}') or _doubled(limit) or limit
    for kind, limit in _RATE_LIMITS.items()
}


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 user_rate_key():
    """Rate-limit key for the account budget: the owner of the token."""
    api_token = current_api_token()
    if api_token is not None:
        return f"user:{api_token.user_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
    and the per-account rate limits 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)
    category = _rate_category(set(scopes))

    # Built once, so a second registration (another limiter in tests) yields
    # limits equal to the first and Flask-Limiter keeps one of each.
    def token_limit():
        return _RATE_LIMITS[category]

    def user_limit():
        return _USER_RATE_LIMITS[category]

    def is_exempt():
        return not is_token_request()

    def token_scope(endpoint):
        return f"token-{category}"

    def token_message():
        return f"Rate limit reached for this token: {_RATE_LIMITS[category]} ({category} requests)."

    def user_scope(endpoint):
        return f"user-{category}"

    def user_message():
        return (f"Rate limit reached for your account: {_USER_RATE_LIMITS[category]} "
                f"({category} requests on this endpoint), shared by all your API tokens.")

    def decorator(f):
        state = {'limiter': None, 'limited': None}
        # gthread workers serve the first requests of a route at the same time;
        # registering the limits twice would count every request twice.
        lock = threading.Lock()
        # A route limit from a lazy rate_limit() decorator under this one
        # (src/api/api_v1.py). Its own wrapper would run a second limiter check
        # per request, and each check counts every limit of the route, so the
        # route limit joins this stack instead and the view runs unwrapped.
        # Only when f is that wrapper itself: a decorator in between (an
        # access check, say) inherits its attributes through functools.wraps
        # and must not be skipped.
        route_limit = route_view = None
        if getattr(f, '_rate_limit_wrapper', None) is f:
            route_limit = f._rate_limit
            route_view = f.__wrapped__

        @wraps(f)
        def wrapper(*args, **kwargs):
            from src.app import limiter
            if limiter is not None and getattr(limiter, 'enabled', True):
                if state['limiter'] is not limiter:
                    with lock:
                        if state['limiter'] is not limiter:
                            state['limited'] = _register(limiter)
                            state['limiter'] = limiter
                return state['limited'](*args, **kwargs)
            return f(*args, **kwargs)

        def _register(limiter):
            # Both limits register under the view's name, so one check
            # evaluates the two. With equal windows the token limit is checked
            # first, and a request it refuses is not counted against the
            # account. Both are counted per route: the bucket is the endpoint
            # plus the token or the user.
            target = f
            if route_view is not None:
                target = limiter.limit(route_limit, **getattr(f, '_rate_limit_options', {}))(route_view)
            per_token = limiter.limit(
                token_limit, key_func=token_rate_key, exempt_when=is_exempt,
                scope=token_scope, error_message=token_message,
            )(target)
            return limiter.limit(
                user_limit, key_func=user_rate_key, exempt_when=is_exempt,
                scope=user_scope, error_message=user_message,
            )(per_token)

        wrapper._required_scopes = required
        wrapper._limit_state = state
        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():
    """Validate a header-only API token against the database.

    Same DB lookup as :func:`load_user_from_token` but ignores the
    ``?token=`` query parameter. Used by the CSRF protection hook
    because Simple Cross-Origin Requests can carry an attacker-supplied
    query string without triggering CORS preflight, while the three
    accepted headers (Authorization, X-API-Token, API-Token) all do
    trigger preflight and so cannot be set by a CSRF attack page.

    Returns the authenticated User, or None.
    """
    return load_user_from_token_value(extract_token_from_request(headers_only=True))