simple-module-users 0.0.39__tar.gz → 0.0.41__tar.gz

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_users
-Version: 0.0.39
+Version: 0.0.41
 Summary: Email + password user management, admin invites, RBAC-ready — replaces Keycloak for simple_module apps
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -23,12 +23,12 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: cachetools<8,>=5.3
 Requires-Dist: fastapi-users[oauth,sqlalchemy]<16,>=15
-Requires-Dist: simple-module-auth==0.0.39
-Requires-Dist: simple-module-core==0.0.39
-Requires-Dist: simple-module-db==0.0.39
-Requires-Dist: simple-module-hosting==0.0.39
-Requires-Dist: simple-module-mail==0.0.39
-Requires-Dist: simple-module-settings==0.0.39
+Requires-Dist: simple-module-auth==0.0.41
+Requires-Dist: simple-module-core==0.0.41
+Requires-Dist: simple-module-db==0.0.41
+Requires-Dist: simple-module-hosting==0.0.41
+Requires-Dist: simple-module-mail==0.0.41
+Requires-Dist: simple-module-settings==0.0.41
 Requires-Dist: typer<0.28,>=0.12
 Description-Content-Type: text/markdown
 

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simple-module-py/users",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "private": true,
   "description": "Frontend assets for the Users module",
   "peerDependencies": {

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_users"
-version = "0.0.39"
+version = "0.0.41"
 description = "Email + password user management, admin invites, RBAC-ready — replaces Keycloak for simple_module apps"
 readme = "README.md"
 license = "MIT"
@@ -21,14 +21,14 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "simple_module_core==0.0.39",
-    "simple_module_db==0.0.39",
-    "simple_module_hosting==0.0.39",
-    "simple_module_settings==0.0.39",
-    "simple_module_auth==0.0.39",
+    "simple_module_core==0.0.41",
+    "simple_module_db==0.0.41",
+    "simple_module_hosting==0.0.41",
+    "simple_module_settings==0.0.41",
+    "simple_module_auth==0.0.41",
     # Sends through the framework mail sender; `mail` owns the SMTP transport
     # (GH #496), so an upgrade keeps delivering mail.
-    "simple_module_mail==0.0.39",
+    "simple_module_mail==0.0.41",
     # Pinned to a narrow range: `deps.py` relies on mutating CookieTransport
     # fields after construction (see reconfigure_cookie_transport in backend.py).
     # Bumping the major version requires re-checking those field names.

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/tests/_users_oauth_support.py

@@ -25,12 +25,15 @@ class _FakeOAuthClient:
     async def get_id_email(self, access_token: str) -> tuple[str, str]:
         return self._account_id, self._account_email
 
+    async def get_profile(self, access_token: str) -> dict:
+        return {"sub": self._account_id, "email": self._account_email, "email_verified": True}
+
 
 def install_fake_provider(app, account_id: str, account_email: str) -> None:
     from users.oauth import OAuthProvider
 
-    app.state.users.oauth_clients["microsoft"] = OAuthProvider(
-        "microsoft", "Microsoft", _FakeOAuthClient(account_id, account_email)
+    app.state.users.oauth_clients["oidc"] = OAuthProvider(
+        "oidc", "OIDC", _FakeOAuthClient(account_id, account_email)
     )
 
 
@@ -70,11 +73,11 @@ async def seed_password_user(app, email: str, **fields) -> uuid.UUID:
 
 async def oauth_callback(client: httpx.AsyncClient) -> httpx.Response:
     """Drive /login then /callback; return the callback response."""
-    login = await client.get("/api/users/auth/microsoft/login", follow_redirects=False)
+    login = await client.get("/api/users/auth/oidc/login", follow_redirects=False)
     assert login.status_code == 302
     state = parse_qs(urlparse(login.headers["location"]).query)["state"][0]
     return await client.get(
-        f"/api/users/auth/microsoft/callback?code=abc&state={state}",
+        f"/api/users/auth/oidc/callback?code=abc&state={state}",
         follow_redirects=False,
     )
 

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/tests/demo/test_users_demo_credentials.py

@@ -7,6 +7,7 @@ from api_tokens.service import ApiTokenService
 from simple_module_test import forge_session_cookie
 from users.auth_local.token_api import _create_token_pair
 from users.demo import ensure_demo_users
+from users.models import User
 
 
 @pytest.fixture
@@ -37,11 +38,18 @@ async def test_demo_token_writes_follow_read_only_setting(
     demo_app.state.users.settings.demo_read_only = read_only
     headers = {"Authorization": f"Bearer {demo_credentials[credential]}"}
     # A successful read proves this credential actually resolves the demo identity.
-    target = demo_app.state.users.demo_user_ids[1]
     assert (await demo_client.get("/api/users/admin", headers=headers)).status_code == 200
+    # A role-less account: the PAT's scopes (users.manage, api_tokens.use) cover it, so
+    # only the demo read-only gate decides. A target holding permissions beyond the
+    # token's scopes is refused regardless (#624).
+    async with demo_app.state.sm.db.session_factory() as db:
+        plain = User(email="plain@example.com", hashed_password=None, is_external=True)
+        db.add(plain)
+        await db.commit()
+        target = str(plain.id)
     response = await demo_client.patch(
         f"/api/users/admin/{target}",
-        json={"email": demo_app.state.users.settings.demo_user_email, "full_name": "Changed"},
+        json={"email": "plain@example.com", "full_name": "Changed"},
         headers=headers,
     )
     assert response.status_code == (403 if read_only else 200), response.text

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/tests/test_bearer_token_age.py

@@ -9,6 +9,7 @@ clause or the two disagree about what "expired" means.
 
 from __future__ import annotations
 
+import hashlib
 import uuid
 from datetime import UTC, datetime, timedelta
 
@@ -27,17 +28,18 @@ async def _mint(users_app) -> str:
         user_id = (
             await session.execute(select(User.id).where(User.email == "admin@example.com"))
         ).scalar_one()
-        token = UserAccessToken(token=uuid.uuid4().hex, user_id=user_id)
+        secret = uuid.uuid4().hex
+        token = UserAccessToken(token=hashlib.sha256(secret.encode()).hexdigest(), user_id=user_id)
         session.add(token)
         await session.commit()
-        return token.token
+        return secret
 
 
 async def _backdate(users_app, token: str, *, seconds: int) -> None:
     async with users_app.state.sm.db.session_factory() as session:
         await session.execute(
             update(UserAccessToken)
-            .where(UserAccessToken.token == token)
+            .where(UserAccessToken.token == hashlib.sha256(token.encode()).hexdigest())
             .values(created_at=datetime.now(UTC) - timedelta(seconds=seconds))
         )
         await session.commit()

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/tests/test_bearer_token_expiry.py

@@ -17,6 +17,7 @@ under, and both bearer read paths enforce them: ``ExpiringDatabaseStrategy``
 
 from __future__ import annotations
 
+import hashlib
 import uuid
 from datetime import UTC, datetime, timedelta
 
@@ -31,6 +32,30 @@ _ME = "/api/users/me"
 _CREDS = {"username": "admin@example.com", "password": "AdminPass1!"}
 
 
+async def _cookie_strategy_user(app, client):
+    """Resolve the ``sm_auth`` cookie through the cookie strategy itself.
+
+    ``/api/users/me`` now resolves the request principal (session or bearer,
+    #658), so it no longer exercises ``ExpiringDatabaseStrategy``; read the row
+    the way ``fastapi_users.current_user`` does instead.
+    """
+    from users.backend import build_strategy
+    from users.db_adapter import PruningAccessTokenDatabase
+    from users.models import UserAccessToken
+
+    async with app.state.sm.db.session_factory() as session:
+
+        class _Manager:
+            def parse_id(self, value):
+                return value if isinstance(value, uuid.UUID) else uuid.UUID(str(value))
+
+            async def get(self, user_id):
+                return await session.get(User, user_id)
+
+        strategy = build_strategy(PruningAccessTokenDatabase(session, UserAccessToken), 900)
+        return await strategy.read_token(client.cookies.get("sm_auth"), _Manager())
+
+
 async def _tokens(app) -> list[UserAccessToken]:
     async with app.state.sm.db.session_factory() as session:
         return list((await session.execute(select(UserAccessToken))).scalars())
@@ -78,7 +103,7 @@ async def _expire(app, token: str) -> None:
     out.
     """
     async with app.state.sm.db.session_factory() as session:
-        row = await session.get(UserAccessToken, token)
+        row = await session.get(UserAccessToken, hashlib.sha256(token.encode()).hexdigest())
         row.expires_at = datetime.now(UTC) - timedelta(seconds=1)
         await session.commit()
 
@@ -128,15 +153,14 @@ class TestAnExpiredRowStopsAuthenticating:
     async def test_the_cookie_strategy_path_refuses_it(self, users_app, anon_client):
         """`fastapi_users.current_user`, via ExpiringDatabaseStrategy.
 
-        ``/api/users/me`` is the probe because it depends on ``current_user``,
-        which is what reads the ``sm_auth`` row. The row stays well inside the
-        thirty-day read ceiling — only the deadline it was issued for has passed.
+        The row stays well inside the thirty-day read ceiling — only the
+        deadline it was issued for has passed.
         """
         assert (await anon_client.post(_LOGIN, data=_CREDS)).status_code == 204
-        assert (await anon_client.get(_ME)).status_code == 200
+        assert await _cookie_strategy_user(users_app, anon_client) is not None
 
         await _expire_all(users_app)
-        assert (await anon_client.get(_ME)).status_code == 401
+        assert await _cookie_strategy_user(users_app, anon_client) is None
 
     @pytest.mark.anyio
     async def test_the_provider_path_refuses_it(self, users_app, anon_client):
@@ -234,7 +258,8 @@ class TestTheMintedCounterIsCurrent:
             row = (
                 await session.execute(
                     select(UserAccessToken).where(
-                        UserAccessToken.token == rotated.json()["access_token"]
+                        UserAccessToken.token
+                        == hashlib.sha256(rotated.json()["access_token"].encode()).hexdigest()
                     )
                 )
             ).scalar_one()

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/tests/test_remember_me.py

@@ -77,6 +77,30 @@ async def _age_access_tokens(app, *, days: int) -> None:
         await session.commit()
 
 
+async def _cookie_strategy_user(app, client):
+    """Resolve the ``sm_auth`` cookie through the cookie strategy itself.
+
+    ``/api/users/me`` now resolves the request principal (session or bearer,
+    #658), so it no longer exercises ``ExpiringDatabaseStrategy``; read the row
+    the way ``fastapi_users.current_user`` does instead.
+    """
+    from users.backend import build_strategy
+    from users.db_adapter import PruningAccessTokenDatabase
+    from users.models import UserAccessToken
+
+    async with app.state.sm.db.session_factory() as session:
+
+        class _Manager:
+            def parse_id(self, value):
+                return value if isinstance(value, uuid.UUID) else uuid.UUID(str(value))
+
+            async def get(self, user_id):
+                return await session.get(User, user_id)
+
+        strategy = build_strategy(PruningAccessTokenDatabase(session, UserAccessToken), 900)
+        return await strategy.read_token(client.cookies.get("sm_auth"), _Manager())
+
+
 class TestRemembered:
     @pytest.mark.anyio
     async def test_the_auth_cookie_lasts_thirty_days(self, anon_client, users_db):
@@ -104,14 +128,13 @@ class TestRemembered:
         know which sign-ins asked to be remembered — a row minted to last
         thirty days therefore has to be accepted for thirty, or the cookie
         outlives the credential it carries and the checkbox starts lying on
-        day fourteen. ``/api/users/me`` is the probe because it depends on
-        ``current_user``, which is the code path that reads the row.
+        day fourteen.
         """
         await _make_user(users_db, "remember-token@example.com")
         await _login(anon_client, "remember-token@example.com", remember=True)
 
         await _age_access_tokens(users_app, days=29)
-        assert (await anon_client.get("/api/users/me")).status_code == 200
+        assert await _cookie_strategy_user(users_app, anon_client) is not None
 
     @pytest.mark.anyio
     async def test_a_token_past_the_window_stops_being_read(self, anon_client, users_db, users_app):
@@ -121,7 +144,7 @@ class TestRemembered:
         await _login(anon_client, "stale-token@example.com", remember=True)
 
         await _age_access_tokens(users_app, days=31)
-        assert (await anon_client.get("/api/users/me")).status_code == 401
+        assert await _cookie_strategy_user(users_app, anon_client) is None
 
 
 class TestTheWindowSurvivesLaterRequests:

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/tests/test_service_admin_crud.py

@@ -144,7 +144,11 @@ async def test_delete_user_removes_user_and_all_child_rows(users_app):
                 account_email="todelete@example.com",
             )
         )
-        session.add(RefreshToken(user_id=user.id, expires_at=datetime.now(UTC) + timedelta(days=1)))
+        session.add(
+            RefreshToken(
+                token="a" * 64, user_id=user.id, expires_at=datetime.now(UTC) + timedelta(days=1)
+            )
+        )
         await session.flush()
 
         svc = _build_service(session, users_app)

{simple_module_users-0.0.39 → simple_module_users-0.0.41}/tests/test_sessions_revoke.py

@@ -104,6 +104,7 @@ class TestRevokeAll:
 
         async with users_app.state.sm.db.session_factory() as session:
             token = RefreshToken(
+                token="a" * 64,
                 user_id=signed_in_admin,
                 expires_at=datetime.now(UTC) + timedelta(days=1),
             )

simple_module_users-0.0.41/tests/test_users_admin_effective_permissions.py

@@ -0,0 +1,70 @@
+"""Delegated management compares effective permissions (#624): direct grants and token scopes."""
+
+import httpx
+import pytest
+from api_tokens.constants import TokenKind
+from api_tokens.service import ApiTokenService
+from simple_module_test import forge_session_cookie
+from sqlalchemy import select
+from test_api_admin import _make_user
+from users.models import Role, User
+
+pytestmark = pytest.mark.anyio
+
+
+async def _client(app, headers=None, cookies=None):
+    return httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app),
+        base_url="http://testserver",
+        headers=headers,
+        cookies=cookies,
+    )
+
+
+async def test_delegate_cannot_manage_user_with_unheld_direct_grant(users_app, users_db):
+    users_db.add(Role(name="manager"))
+    await users_db.commit()
+    users_app.state.sm.permissions.map_role("manager", ["users.manage"])
+    actor = await _make_user(users_db, "manager@example.com", role_names=["manager", "user"])
+    target = await _make_user(users_db, "granted@example.com", role_names=["user"])
+    ordinary = await _make_user(users_db, "plain@example.com", role_names=["user"])
+
+    async def direct_grants(request, user):
+        return {"files.delete"} if user.id == str(target.id) else set()
+
+    users_app.state.sm.permissions.add_grant_source(direct_grants)
+    cookie = forge_session_cookie(
+        str(users_app.state.sm.settings.secret_key), {"user_id": str(actor.id)}
+    )
+    async with await _client(users_app, cookies={"session": cookie}) as client:
+        denied = await client.patch(f"/api/users/admin/{target.id}/disable")
+        allowed = await client.patch(f"/api/users/admin/{ordinary.id}/disable")
+    assert denied.status_code == 403
+    assert allowed.status_code == 200
+    await users_db.refresh(target)
+    assert target.is_active is True
+
+
+async def test_admin_pat_cannot_grant_role_beyond_its_scopes(users_app, users_db):
+    users_db.add(Role(name="deleter"))
+    await users_db.commit()
+    users_app.state.sm.permissions.map_role("deleter", ["files.delete"])
+    admin = (
+        await users_db.execute(select(User).where(User.email == "admin@example.com"))
+    ).scalar_one()
+    target = await _make_user(users_db, "target@example.com", role_names=[])
+    _, pat = await ApiTokenService(users_db).create(
+        kind=TokenKind.PERSONAL,
+        name="scoped admin",
+        scopes=["users.manage", "api_tokens.use"],
+        expires_in_days=1,
+        max_lifetime_days=30,
+        owner_user_id=admin.id,
+    )
+    await users_db.commit()
+    async with await _client(users_app, headers={"Authorization": f"Bearer {pat}"}) as client:
+        url = f"/api/users/admin/{target.id}/roles"
+        beyond = await client.put(url, json={"role_names": ["deleter"]})
+        assert beyond.status_code == 403
+        within = await client.put(url, json={"role_names": []})
+        assert within.status_code == 200

simple_module_users-0.0.41/tests/test_users_admin_privilege_guards.py

@@ -0,0 +1,167 @@
+"""Delegated user management must not grant access to stronger accounts (#624)."""
+
+import httpx
+import pytest
+from fastapi import FastAPI
+from simple_module_test import forge_session_cookie
+from sqlalchemy import select
+from test_api_admin import _make_user
+from test_service_admin import _build_service
+from users.errors import install_exception_handlers
+from users.exceptions import AdminAccountSafetyError, AdminPermissionError
+from users.models import Role, User, UserRole
+
+pytestmark = pytest.mark.anyio
+
+
+@pytest.mark.parametrize(
+    "error, status", [(AdminPermissionError, 403), (AdminAccountSafetyError, 400)]
+)
+async def test_admin_guard_http_status(error, status):
+    app = FastAPI()
+    install_exception_handlers(app)
+
+    @app.post("/guarded")
+    async def guarded():
+        raise error("Refused")
+
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        response = await client.post("/guarded")
+    assert response.status_code == status
+    assert response.json() == {"detail": "Refused"}
+
+
+@pytest.fixture
+async def delegated_client(users_app, users_db):
+    users_db.add(Role(name="manager"))
+    users_db.add(Role(name="powerful"))
+    await users_db.commit()
+    users_app.state.sm.permissions.map_role("manager", ["users.manage"])
+    users_app.state.sm.permissions.map_role("powerful", ["files.delete"])
+    actor = await _make_user(users_db, "manager@example.com", role_names=["manager", "user"])
+    cookie = forge_session_cookie(
+        str(users_app.state.sm.settings.secret_key), {"user_id": str(actor.id)}
+    )
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=users_app),
+        base_url="http://testserver",
+        cookies={"session": cookie},
+    ) as client:
+        yield client, actor.id
+
+
+@pytest.mark.parametrize("role", ["admin", "powerful"])
+@pytest.mark.parametrize("operation", ["roles", "create", "invite", "bulk"])
+async def test_delegate_cannot_grant_unheld_role(delegated_client, users_db, operation, role):
+    client, actor_id = delegated_client
+    data = {"role_names": [role]}
+    if operation == "roles":
+        response = await client.put(f"/api/users/admin/{actor_id}/roles", json=data)
+    else:
+        data.update(email="escalated@example.com", password="SecurePass1!")
+        path = {"create": "", "invite": "/invite", "bulk": "/invite/bulk"}[operation]
+        if operation == "bulk":
+            data["emails"] = [data.pop("email")]
+        response = await client.post(f"/api/users/admin{path}", json=data)
+    assert response.status_code == 403
+    assert (
+        await users_db.execute(select(User).where(User.email == "escalated@example.com"))
+    ).scalar_one_or_none() is None
+    roles = (
+        (
+            await users_db.execute(
+                select(Role.name).join(UserRole).where(UserRole.user_id == actor_id)
+            )
+        )
+        .scalars()
+        .all()
+    )
+    assert set(roles) == {"manager", "user"}
+
+
+@pytest.mark.parametrize("kind", ["admin", "superuser", "powerful"])
+@pytest.mark.parametrize("operation", ["reset", "roles", "disable", "email", "delete"])
+async def test_delegate_cannot_control_privileged_target(
+    delegated_client, users_db, kind, operation
+):
+    client, _ = delegated_client
+    target = await _make_user(
+        users_db, "protected@example.com", role_names=[] if kind == "superuser" else [kind]
+    )
+    if kind == "superuser":
+        target.is_superuser = True
+        await users_db.commit()
+    url = f"/api/users/admin/{target.id}"
+    if operation == "reset":
+        response = await client.post(f"{url}/reset-password-link")
+    elif operation == "roles":
+        response = await client.put(f"{url}/roles", json={"role_names": ["user"]})
+    elif operation == "disable":
+        response = await client.patch(f"{url}/disable")
+    elif operation == "email":
+        response = await client.patch(url, json={"email": "stolen@example.com"})
+    else:
+        response = await client.delete(url)
+    assert response.status_code == 403
+    await users_db.refresh(target)
+    assert target.email == "protected@example.com"
+    assert target.is_active is True
+
+
+async def test_delegate_can_manage_ordinary_user(delegated_client, users_db):
+    client, _ = delegated_client
+    target = await _make_user(users_db, "ordinary@example.com", role_names=["user"])
+    url = f"/api/users/admin/{target.id}"
+    response = await client.put(f"{url}/roles", json={"role_names": ["user"]})
+    assert response.status_code == 200
+    response = await client.post(f"{url}/reset-password-link")
+    assert response.status_code == 200
+    assert "token=" in response.json()["link"]
+    response = await client.patch(f"{url}/disable")
+    assert response.status_code == 200
+
+
+@pytest.mark.parametrize("operation", ["disable", "roles"])
+async def test_admin_cannot_disable_or_demote_self(admin_client, users_db, operation):
+    admin = (
+        await users_db.execute(select(User).where(User.email == "admin@example.com"))
+    ).scalar_one()
+    # Self-protection also applies when another administrator exists.
+    await _make_user(users_db, "other-admin@example.com", role_names=["admin"])
+    url = f"/api/users/admin/{admin.id}/{operation}"
+    if operation == "roles":
+        response = await admin_client.put(url, json={"role_names": ["user"]})
+    else:
+        response = await admin_client.patch(url)
+    assert response.status_code == 400
+    await users_db.refresh(admin)
+    assert admin.is_active is True
+    assert (
+        await users_db.execute(select(Role.name).join(UserRole).where(UserRole.user_id == admin.id))
+    ).scalars().all() == ["admin"]
+
+
+@pytest.mark.parametrize("operation", ["disable", "roles", "delete"])
+async def test_service_preserves_last_active_admin(users_app, users_db, operation):
+    admin = (
+        await users_db.execute(select(User).where(User.email == "admin@example.com"))
+    ).scalar_one()
+    inactive = await _make_user(users_db, "inactive-admin@example.com", role_names=["admin"])
+    inactive.is_active = False
+    await users_db.commit()
+    # The legacy superuser flag alone grants no framework admin permissions.
+    roleless = await _make_user(users_db, "roleless-superuser@example.com")
+    roleless.is_superuser = True
+    await users_db.commit()
+    service = _build_service(users_db, users_app)
+    with pytest.raises(AdminAccountSafetyError):
+        if operation == "roles":
+            await service.set_roles(admin.id, ["user"])
+        elif operation == "delete":
+            await service.delete_user(admin.id)
+        else:
+            await service.disable(admin.id)
+    await users_db.refresh(admin)
+    assert admin.is_active is True

simple_module_users-0.0.41/tests/test_users_admin_role_grant_rules.py

@@ -0,0 +1,56 @@
+"""Who may grant which roles (#624): compared by effective permissions, not role names."""
+
+import pytest
+from auth.contracts.schemas import UserContext
+from simple_module_hosting.permissions import apply_scope_cap, resolve_permissions
+from users.admin.safety import check_role_assignment
+from users.exceptions import AdminPermissionError
+
+ROLE_MAP = {
+    "admin": ["*"],
+    "helpdesk": ["users.manage"],
+    "editor": ["pages.edit"],
+    "billing": ["billing.manage"],
+    "files": ["files.delete"],
+    "empty": [],
+}
+
+
+def _check(roles, wanted, scopes=None):
+    actor = UserContext(id="a", email="a@x", name="a", roles=roles, scopes=scopes)
+    held = apply_scope_cap(resolve_permissions(roles, ROLE_MAP), actor)
+    check_role_assignment(actor, wanted, held, ROLE_MAP)
+
+
+def test_full_admin_grants_admin():
+    _check(["admin"], ["admin", "editor"])
+
+
+def test_admin_scoped_token_cannot_grant_admin():
+    with pytest.raises(AdminPermissionError):
+        _check(["admin"], ["admin"], scopes=["users.manage"])
+
+
+def test_admin_scoped_token_grants_only_roles_within_its_scopes():
+    _check(["admin"], ["helpdesk", "empty"], scopes=["users.manage"])
+    with pytest.raises(AdminPermissionError):
+        _check(["admin"], ["files"], scopes=["users.manage"])
+
+
+def test_delegate_grants_roles_its_permissions_cover():
+    _check(["helpdesk", "editor"], ["editor", "empty"])
+    for wanted in (["admin"], ["billing"], ["files"]):
+        with pytest.raises(AdminPermissionError):
+            _check(["helpdesk", "editor"], wanted)
+
+
+def test_delegate_holding_equivalent_permissions_via_another_role_may_grant():
+    ROLE_MAP["twin"] = ["pages.edit"]
+    try:
+        _check(["editor"], ["twin"])
+    finally:
+        del ROLE_MAP["twin"]
+
+
+def test_trusted_in_process_caller_is_unrestricted():
+    check_role_assignment(None, ["admin"], set(), ROLE_MAP)