feat(api): personal API tokens and the AI access page

First step of milestone 461 (MCP server). A token is the credential an
MCP client presents as `Authorization: Bearer stw_…` to act as its user.

- api_tokens table (0026): sha256 hash only, display prefix, role
  ceiling, expiry, revocation, throttled last_used_at.
- steward/core/api_tokens.py: mint, list, revoke, resolve. Resolution
  re-reads the user's current role and acts with the lower of that and
  the token's ceiling, so demoting or disabling a user weakens or kills
  their tokens with nothing to revoke by hand.
- /ai-access/ (sidebar → Automation → AI access): every user manages
  their own tokens, can't grant above their own role, sees the token
  once. Session-only: a share-link viewer is refused. Create and revoke
  are audited.
- Integration tests drive the routes against real Postgres so their
  transactions run for real (#884 escaped CI behind a mocked session).

Task #4965 "MCP-1 — Personal API tokens".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/integration/test_api_tokens.py

@@ -0,0 +1,170 @@
+"""Integration: personal API tokens against real Postgres.
+
+Resolution reads the token and its user's CURRENT role in one query, so a
+demoted or disabled user's tokens weaken or die with nothing revoked by hand.
+The routes are driven through the test client so their transactions run for
+real: a mocked session cannot catch a double-begin (#884).
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import uuid
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+pytestmark = pytest.mark.integration
+
+_NEEDS_DB = pytest.mark.skipif(
+    not os.environ.get("STEWARD_DATABASE_URL"),
+    reason="integration test needs a live Postgres (STEWARD_DATABASE_URL)",
+)
+
+
+@pytest.fixture
+def app():
+    if not os.environ.get("STEWARD_DATABASE_URL"):
+        pytest.skip("needs Postgres")
+    from steward.app import create_app
+    return create_app(testing=False)
+
+
+async def _make_user(app, role):
+    from steward.models.users import User
+    uid = str(uuid.uuid4())
+    async with app.db_sessionmaker() as s:
+        async with s.begin():
+            s.add(User(id=uid, username=f"tok-{uid[:8]}", email=f"{uid}@test",
+                       password_hash="x", role=role, is_active=True))
+    return uid
+
+
+async def _mint(app, uid, user_role, role, **kw):
+    from steward.core import api_tokens
+    async with app.db_sessionmaker() as s:
+        raw, token = await api_tokens.create_token(
+            s, user_id=uid, user_role=user_role, name="it", role=role, **kw)
+        await s.commit()
+    return raw, token.id
+
+
+@_NEEDS_DB
+def test_resolve_lifecycle(app):
+    from sqlalchemy import select, update
+    from steward.core import api_tokens
+    from steward.models.api_tokens import ApiToken
+    from steward.models.users import User, UserRole
+
+    async def _go():
+        uid = await _make_user(app, UserRole.admin)
+        raw, tid = await _mint(app, uid, UserRole.admin, UserRole.operator)
+
+        caller = await api_tokens.resolve_token(app, raw)
+        assert caller is not None
+        assert (caller.user_id, caller.role, caller.token_id) == (uid, UserRole.operator, tid)
+        async with app.db_sessionmaker() as s:
+            used = (await s.execute(select(ApiToken.last_used_at).where(ApiToken.id == tid))).scalar_one()
+        assert used is not None
+
+        # A wrong token, and the right one with a character changed, resolve to nobody.
+        assert await api_tokens.resolve_token(app, api_tokens.generate_token()) is None
+        assert await api_tokens.resolve_token(app, raw[:-1] + ("A" if raw[-1] != "A" else "B")) is None
+
+        # Demoting the user caps the token at the user's new role.
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                await s.execute(update(User).where(User.id == uid).values(role=UserRole.viewer))
+        assert (await api_tokens.resolve_token(app, raw)).role == UserRole.viewer
+
+        # Disabling the user kills the token.
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                await s.execute(update(User).where(User.id == uid).values(is_active=False))
+        assert await api_tokens.resolve_token(app, raw) is None
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                await s.execute(update(User).where(User.id == uid).values(is_active=True))
+        assert await api_tokens.resolve_token(app, raw) is not None
+
+        # Revoking kills it, and only the owner can revoke.
+        other = await _make_user(app, UserRole.admin)
+        async with app.db_sessionmaker() as s:
+            assert await api_tokens.revoke_token(s, user_id=other, token_id=tid) is None
+            await s.commit()
+        assert await api_tokens.resolve_token(app, raw) is not None
+        async with app.db_sessionmaker() as s:
+            assert await api_tokens.revoke_token(s, user_id=uid, token_id=tid) is not None
+            await s.commit()
+        assert await api_tokens.resolve_token(app, raw) is None
+
+        # An expired token resolves to nobody.
+        raw2, tid2 = await _mint(app, uid, UserRole.viewer, UserRole.viewer)
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                await s.execute(update(ApiToken).where(ApiToken.id == tid2).values(
+                    expires_at=datetime.now(timezone.utc) - timedelta(seconds=1)))
+        assert await api_tokens.resolve_token(app, raw2) is None
+
+        # Deleting the user takes their tokens with them.
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                await s.execute(User.__table__.delete().where(User.id == uid))
+            left = (await s.execute(select(ApiToken).where(ApiToken.user_id == uid))).all()
+        assert left == []
+
+    asyncio.run(_go())
+
+
+@_NEEDS_DB
+def test_routes_create_list_and_revoke(app):
+    from sqlalchemy import select
+    from steward.core import api_tokens
+    from steward.models.api_tokens import ApiToken
+    from steward.models.audit import AuditEvent
+    from steward.models.users import UserRole
+
+    async def _go():
+        uid = await _make_user(app, UserRole.operator)
+        client = app.test_client()
+        async with client.session_transaction() as sess:
+            sess["user_id"] = uid
+            sess["user_role"] = "operator"
+            sess["username"] = "route-test"
+
+        resp = await client.get("/ai-access/")
+        assert resp.status_code == 200
+        page = await resp.get_data(as_text=True)
+        assert "You have no tokens yet" in page
+        # An operator can't offer admin.
+        assert 'value="admin"' not in page
+
+        resp = await client.post("/ai-access/tokens", form={
+            "name": "laptop", "role": "admin", "expires_in_days": ""})
+        assert resp.status_code == 400
+        assert "higher role" in await resp.get_data(as_text=True)
+
+        resp = await client.post("/ai-access/tokens", form={
+            "name": "laptop", "role": "operator", "expires_in_days": "30"})
+        assert resp.status_code == 200
+        raw = re.search(r'value="(stw_[^"]+)"', await resp.get_data(as_text=True)).group(1)
+        caller = await api_tokens.resolve_token(app, raw)
+        assert caller is not None and caller.role == UserRole.operator
+
+        async with app.db_sessionmaker() as s:
+            token = (await s.execute(select(ApiToken).where(ApiToken.user_id == uid))).scalar_one()
+        page = await (await client.get("/ai-access/")).get_data(as_text=True)
+        assert "laptop" in page and token.prefix in page
+        assert raw not in page
+
+        resp = await client.post(f"/ai-access/tokens/{token.id}/revoke")
+        assert resp.status_code == 302
+        assert await api_tokens.resolve_token(app, raw) is None
+
+        async with app.db_sessionmaker() as s:
+            actions = (await s.execute(
+                select(AuditEvent.action).where(AuditEvent.user_id == uid))).scalars().all()
+        assert "api_token.create" in actions and "api_token.revoke" in actions
+
+    asyncio.run(_go())

tests/test_api_tokens.py

@@ -0,0 +1,137 @@
+"""Personal API tokens: the pure rules (hashing, role ceiling, state) and the
+route gate. Resolution and the routes' transactions run against real Postgres
+in tests/integration/test_api_tokens.py."""
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime, timedelta, timezone
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from steward.core import api_tokens
+from steward.models.api_tokens import ApiToken
+from steward.models.users import UserRole
+
+V, O, A = UserRole.viewer, UserRole.operator, UserRole.admin
+
+
+def test_generated_tokens_are_prefixed_and_unique():
+    a, b = api_tokens.generate_token(), api_tokens.generate_token()
+    assert a.startswith("stw_") and b.startswith("stw_")
+    assert a != b
+    assert len(a) > 40
+
+
+def test_hash_is_sha256_of_the_plaintext():
+    raw = "stw_example"
+    assert api_tokens.hash_token(raw) == hashlib.sha256(raw.encode()).hexdigest()
+
+
+def test_display_prefix_never_reveals_the_whole_token():
+    raw = api_tokens.generate_token()
+    shown = api_tokens.display_prefix(raw)
+    assert raw.startswith(shown)
+    assert len(shown) < len(raw) // 3
+
+
+@pytest.mark.parametrize("ceiling,user_role,expected", [
+    (A, A, A), (O, A, O), (V, A, V),
+    (A, O, O), (O, O, O), (V, O, V),
+    (A, V, V), (O, V, V), (V, V, V),
+])
+def test_effective_role_is_the_lower_of_ceiling_and_user(ceiling, user_role, expected):
+    assert api_tokens.effective_role(ceiling, user_role) == expected
+
+
+def test_grantable_roles_stop_at_the_users_own():
+    assert api_tokens.grantable_roles(V) == [V]
+    assert api_tokens.grantable_roles(O) == [V, O]
+    assert api_tokens.grantable_roles(A) == [V, O, A]
+
+
+def _token(**kw) -> ApiToken:
+    return ApiToken(name="t", token_hash="x", prefix="stw_x", role=V, **kw)
+
+
+def test_token_state():
+    now = datetime.now(timezone.utc)
+    assert api_tokens.token_state(_token(), now) == "active"
+    assert api_tokens.token_state(_token(expires_at=now + timedelta(days=1)), now) == "active"
+    assert api_tokens.token_state(_token(expires_at=now), now) == "expired"
+    assert api_tokens.token_state(_token(revoked_at=now), now) == "revoked"
+    # Revoked wins over expired: it is the more deliberate fact.
+    assert api_tokens.token_state(
+        _token(revoked_at=now, expires_at=now - timedelta(days=1)), now) == "revoked"
+
+
+def _fake_db():
+    db = MagicMock()
+    db.flush = AsyncMock()
+    return db
+
+
+async def test_create_token_stores_only_the_hash():
+    db = _fake_db()
+    raw, token = await api_tokens.create_token(
+        db, user_id="u1", user_role=O, name="  laptop  ", role=O, expires_in_days=30)
+    db.add.assert_called_once_with(token)
+    assert token.token_hash == api_tokens.hash_token(raw)
+    assert raw not in (token.token_hash, token.prefix)
+    assert token.name == "laptop"
+    assert token.role == O
+    assert token.expires_at is not None
+
+
+async def test_create_token_refuses_a_ceiling_above_the_users_role():
+    db = _fake_db()
+    with pytest.raises(ValueError, match="higher role"):
+        await api_tokens.create_token(db, user_id="u1", user_role=O, name="x", role=A)
+    db.add.assert_not_called()
+
+
+async def test_create_token_requires_a_name():
+    with pytest.raises(ValueError, match="name"):
+        await api_tokens.create_token(_fake_db(), user_id="u1", user_role=A, name="  ", role=V)
+
+
+async def test_resolve_rejects_non_steward_tokens_without_touching_the_db():
+    app = MagicMock()
+    for raw in (None, "", "Bearer x", "abc123"):
+        assert await api_tokens.resolve_token(app, raw) is None
+    app.db_sessionmaker.assert_not_called()
+
+
+async def test_ai_access_requires_login(client):
+    resp = await client.get("/ai-access/")
+    assert resp.status_code == 302
+    assert "/login" in resp.headers["Location"]
+
+
+async def test_ai_access_refuses_a_request_with_no_session_user():
+    # A share-link viewer passes require_role(viewer) but has no session user to
+    # own tokens; the guard must refuse rather than act for nobody.
+    from werkzeug.exceptions import Forbidden
+    from steward.ai_access import routes
+
+    db = MagicMock()
+    db.execute = AsyncMock()
+    with patch.object(routes, "current_user_id", return_value=None):
+        with pytest.raises(Forbidden):
+            await routes._session_user(db)
+    db.execute.assert_not_called()
+
+
+async def test_ai_access_refuses_a_disabled_user():
+    from werkzeug.exceptions import Forbidden
+    from steward.ai_access import routes
+    from steward.models.users import User
+
+    user = User(id="u1", username="x", email="x@e", password_hash="h", role=A, is_active=False)
+    result = MagicMock()
+    result.scalar_one_or_none.return_value = user
+    db = MagicMock()
+    db.execute = AsyncMock(return_value=result)
+    with patch.object(routes, "current_user_id", return_value="u1"):
+        with pytest.raises(Forbidden):
+            await routes._session_user(db)