Skip to content

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

Python
21.7 KB
Raw Blame
"""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)


@pytest.fixture
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())


@pytest.mark.parametrize("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


@pytest.mark.parametrize("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_the_account_budget_defaults_to_twice_the_token_budget():
    from src.utils import token_auth as ta
    assert ta._doubled("120 per minute") == "240 per minute"
    assert ta._doubled("10/second; 100 per 5 minutes") == "20 per second; 200 per 5 minute"
    assert ta._doubled("not a limit") is None
    if not any(os.environ.get(f"API_USER_RATE_LIMIT_{k}") for k in ("READ", "WRITE", "PROCESS")):
        assert ta._USER_RATE_LIMITS == {k: ta._doubled(v) for k, v in ta._RATE_LIMITS.items()}


@pytest.fixture
def live_limiter():
    """An enabled limiter with small budgets in place of the suite's disabled one.

    RATELIMIT_ENABLED is false under test, so the app's own limiter was never
    set up; this one is initialised on a throwaway app and counts in memory.
    Token budget 3, account budget 5 (read); 2 and 4 (write).
    """
    from flask import Flask
    from flask_limiter import Limiter
    from flask_limiter.util import get_remote_address
    import src.app as app_module
    from src.api import api_v1
    from src.utils import token_auth as ta
    live = Limiter(get_remote_address, storage_uri="memory://", enabled=True)
    live.init_app(Flask("limiter-host"))
    # The route limits in api_v1 use the same limiter, as in the app.
    with patch.object(app_module, "limiter", live), patch.object(api_v1, "limiter", live), \
         patch.dict(ta._RATE_LIMITS, {"read": "3 per minute", "write": "2 per minute"}), \
         patch.dict(ta._USER_RATE_LIMITS, {"read": "5 per minute", "write": "4 per minute"}):
        yield live


def _read(c, plain, path="/api/v1/recordings"):
    return c.get(path, headers=_h(plain))


def test_tokens_of_one_account_share_the_account_budget(world, live_limiter):
    first, second = world["token"](None), world["token"](["read"])
    with app.app_context():
        c = _Client(app, app.response_class)
        assert [_read(c, first).status_code for _ in range(3)] == [200, 200, 200]
        over_token = _read(c, first)
        assert [_read(c, second).status_code for _ in range(2)] == [200, 200]
        over_account = _read(c, second)
    # The first token runs out of its own budget; that refusal is not counted
    # against the account, which the second token then exhausts at 5.
    assert over_token.status_code == 429 and over_token.headers.get("Retry-After")
    assert over_token.get_json()["code"] == "token_rate_limit_exceeded"
    assert "this token" in over_token.get_json()["error"]
    assert over_account.status_code == 429 and over_account.headers.get("Retry-After")
    body = over_account.get_json()
    assert body["code"] == "account_rate_limit_exceeded"
    assert "your account" in body["error"] and body["limit"] == "5 per 1 minute"


def test_a_single_token_meets_its_own_budget_first(world, live_limiter):
    plain = world["token"](None)
    with app.app_context():
        c = _Client(app, app.response_class)
        codes = [_read(c, plain).status_code for _ in range(4)]
        refused = _read(c, plain)
    assert codes == [200, 200, 200, 429]
    assert refused.get_json()["code"] == "token_rate_limit_exceeded"


def test_one_token_polling_several_endpoints_is_never_held_by_the_account(world, live_limiter):
    """Both budgets are per endpoint: a sync client at its token limit on each
    of three endpoints (9 reads, account budget 5) meets only its token limit."""
    plain = world["token"](None)
    paths = ["/api/v1/recordings", "/api/v1/tags", "/api/v1/users/me"]
    with app.app_context():
        c = _Client(app, app.response_class)
        codes = [_read(c, plain, path).status_code for path in paths for _ in range(3)]
        refused = _read(c, plain, "/api/v1/tags")
        write = c.patch(f"/api/v1/recordings/{world['rec']}", json={"title": "Still allowed"},
                        headers=_h(plain))
    assert codes == [200] * 9
    assert refused.status_code == 429 and refused.get_json()["code"] == "token_rate_limit_exceeded"
    assert write.status_code == 200


def test_session_traffic_is_not_held_by_token_budgets(world, live_limiter):
    c = _session(world)
    assert {c.get("/api/v1/recordings").status_code for _ in range(8)} == {200}


def _codes(send, n):
    return [send().status_code for _ in range(n)]


def test_the_asr_upload_limit_counts_each_request_once(live_limiter):
    """520 units a minute at 52 per request: ten uploads, not five."""
    c = app.test_client()

    def send():
        # A wrong secret is refused after the limit has counted the request.
        return c.post("/api/v1/integrations/asr-voice-recorder/upload", data={"secret": "wrong"},
                      content_type="multipart/form-data", environ_base={"REMOTE_ADDR": "203.0.113.48"})
    assert _codes(send, 11) == [401] * 10 + [429]


def test_the_search_limit_counts_each_request_once(world, live_limiter):
    from src.utils import token_auth as ta
    plain = world["token"](None)
    with patch.dict(ta._RATE_LIMITS, {"read": "100 per minute"}), \
         patch.dict(ta._USER_RATE_LIMITS, {"read": "100 per minute"}):
        with app.app_context():
            c = _Client(app, app.response_class)
            codes = _codes(lambda: c.get("/api/v1/search?q=x", headers=_h(plain)), 31)
    assert codes == [400] * 30 + [429]   # API_SEARCH_RATE_LIMIT: 30 per minute


@pytest.mark.parametrize("token_limit,account_limit,code", [
    ("4 per minute", "100 per minute", "token_rate_limit_exceeded"),
    ("100 per minute", "4 per minute", "account_rate_limit_exceeded"),
])
def test_token_and_account_budgets_count_once_on_a_route_with_its_own_limit(world, live_limiter, token_limit,
                                                                            account_limit, code):
    from src.utils import token_auth as ta
    plain = world["token"](None)
    with patch.dict(ta._RATE_LIMITS, {"read": token_limit}), \
         patch.dict(ta._USER_RATE_LIMITS, {"read": account_limit}):
        with app.app_context():
            c = _Client(app, app.response_class)
            codes = _codes(lambda: c.get("/api/v1/search?q=x", headers=_h(plain)), 4)
            refused = c.get("/api/v1/search?q=x", headers=_h(plain))
    assert codes == [400] * 4
    assert refused.status_code == 429 and refused.get_json()["code"] == code


def test_registering_the_limits_again_still_counts_each_request_once(world, live_limiter):
    """A second registration on the same limiter (two threads that both saw the
    route unregistered) must not add a second copy of each limit."""
    plain = world["token"](None)
    view = app.view_functions["api_v1.list_recordings"]
    with app.app_context():
        c = _Client(app, app.response_class)
        first = _read(c, plain)
        view._limit_state["limiter"] = None     # as the thread that lost the race sees it
        rest = [_read(c, plain).status_code for _ in range(3)]
    assert [first.status_code] + rest == [200, 200, 200, 429]   # token budget 3


def test_concurrent_first_requests_register_the_limits_once(world, live_limiter):
    import threading
    plain = world["token"](None)
    barrier = threading.Barrier(6)
    codes = []

    def first_request():
        with app.app_context():
            c = _Client(app, app.response_class)
            barrier.wait()
            codes.append(_read(c, plain, "/api/v1/tags").status_code)

    threads = [threading.Thread(target=first_request) for _ in range(6)]
    for t in threads:
        t.start()
    for t in threads:
        t.join()
    # Token budget 3 on this route: three pass, three are refused, whatever
    # the interleaving; a doubled registration would let only one through.
    assert sorted(codes) == [200, 200, 200, 429, 429, 429]


def test_a_decorator_between_require_scope_and_rate_limit_is_never_skipped(live_limiter):
    """functools.wraps copies _rate_limit onto a decorator above rate_limit();
    require_scope may unwrap only rate_limit's own wrapper."""
    from functools import wraps
    from src.api.api_v1 import rate_limit
    from src.utils.token_auth import require_scope

    def deny(f):
        @wraps(f)
        def check(*args, **kwargs):
            return "denied"
        return check

    def view():
        return "view ran"

    guarded = require_scope("read")(deny(rate_limit("5 per minute")(view)))
    direct = require_scope("read")(rate_limit("5 per minute")(view))
    with app.test_request_context("/"):
        assert guarded() == "denied"
        assert direct() == "view ran"


# ------------------------------------------------------------ token cap

def test_the_token_cap_refuses_another_active_token_until_one_is_revoked(world):
    from datetime import datetime, timedelta
    from src.api import tokens as tokens_api
    c = _session(world)
    with app.app_context():
        # A revoked or an expired token does not take a slot.
        for kwargs in ({"revoked": True}, {"expires_at": datetime.utcnow() - timedelta(days=1)}):
            t = APIToken(user_id=world["user"], token_hash=hash_token(secrets.token_urlsafe(16)), name="old",
                         **kwargs)
            db.session.add(t)
            db.session.commit()
            world["tokens"].append(t.id)
    with patch.object(tokens_api, "API_MAX_TOKENS_PER_USER", 2):
        made = [c.post("/api/tokens", json={"name": f"t{i}"}) for i in range(2)]
        refused = c.post("/api/tokens", json={"name": "t3"})
        assert c.delete(f"/api/tokens/{made[0].get_json()['id']}").status_code == 200
        after_revoke = c.post("/api/tokens", json={"name": "t3"})
    assert [r.status_code for r in made] == [201, 201]
    assert refused.status_code == 409
    body = refused.get_json()
    assert body["code"] == "token_limit_reached" and body["max_tokens"] == 2 and body["active_tokens"] == 2
    assert "Revoke" in body["error"]
    assert after_revoke.status_code == 201


def test_tokens_above_a_lowered_cap_keep_working(world):
    from src.api import tokens as tokens_api
    plains = [world["token"](None) for _ in range(3)]
    with patch.object(tokens_api, "API_MAX_TOKENS_PER_USER", 1):
        assert _session(world).post("/api/tokens", json={"name": "x"}).status_code == 409
        with app.app_context():
            c = _Client(app, app.response_class)
            assert {_read(c, p).status_code for p in plains} == {200}


def test_a_token_cap_of_zero_means_no_limit(world):
    from src.api import tokens as tokens_api
    c = _session(world)
    with patch.object(tokens_api, "API_MAX_TOKENS_PER_USER", 0):
        assert {c.post("/api/tokens", json={"name": f"t{i}"}).status_code for i in range(4)} == {201}


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