Add optional permission scopes to API tokens

A token may carry a scopes list: it then grants only those permissions,
intersected with what the owner holds at use time, with the admin role
bypass suspended and role-gated routes denied - a scoped token from an
admin account is genuinely limited. Scope ceiling enforced at
create/update too (only permissions the owner holds; 400 lists
violations) and the picker only offers what you hold. Token management
itself now requires the new apitokens.create permission (admin by
default, grantable via roles). Unscoped tokens keep the exact prior
act-as-owner behavior; imports need an unscoped admin token.
Migration 7d22.

756 tests pass; live-verified scoped 201/403 matrix.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

shopdb/utils/apitoken_auth.py

@@ -95,6 +95,12 @@ def install_apitoken_auth(app):
             'username': user.username,
             'roles': [role.rolename for role in user.roles],
         }
+        # A scoped token carries a patscopes claim; authz reads it to grant ONLY
+        # the listed permissions and to deny role gates + import mode. Unscoped
+        # tokens carry no such claim and mint exactly as a login JWT would.
+        scopelist = token.scopelist
+        if scopelist is not None:
+            claims['patscopes'] = scopelist
         # Expose the token/user for audit and introspection if a handler wants it.
         g.apitokenid = token.tokenid
         g.apitokenuser = user

shopdb/utils/authz.py

@@ -21,13 +21,18 @@ Usage:
 
 from functools import wraps
 
-from flask_jwt_extended import verify_jwt_in_request, current_user
+from flask_jwt_extended import verify_jwt_in_request, current_user, get_jwt
 
 from shopdb.utils.responses import error_response, ErrorCodes
 
 
 def require_permission(permission_name: str):
-    """Gate a route behind a single permission. Admin role bypasses."""
+    """Gate a route behind a single permission. Admin role bypasses.
+
+    A scoped personal API token (patscopes claim present) does NOT bypass: it
+    grants only the permissions in its scope list, intersected with what the
+    owner actually holds. See shopdb/utils/apitoken_auth.py.
+    """
     def decorator(view_func):
         @wraps(view_func)
         def wrapper(*args, **kwargs):
@@ -40,6 +45,22 @@ def require_permission(permission_name: str):
                     'Authentication required',
                     http_code=401
                 )
+            patscopes = get_jwt().get('patscopes')
+            if patscopes is not None:
+                # Scoped PAT: allowed only when this permission is in the scope
+                # list AND the owner actually holds it. haspermission still
+                # returns True for an admin owner (who legitimately holds
+                # everything), so the scope list is the real limiter - the
+                # admin bypass is suspended.
+                allowed = (permission_name in patscopes
+                           and current_user.haspermission(permission_name))
+                if not allowed:
+                    return error_response(
+                        ErrorCodes.FORBIDDEN,
+                        'This API token is not scoped for this action',
+                        http_code=403
+                    )
+                return view_func(*args, **kwargs)
             if not current_user.haspermission(permission_name):
                 return error_response(
                     ErrorCodes.FORBIDDEN,
@@ -52,7 +73,12 @@ def require_permission(permission_name: str):
 
 
 def require_role(rolename: str):
-    """Gate a route behind a single role (e.g. 'admin')."""
+    """Gate a route behind a single role (e.g. 'admin').
+
+    A scoped personal API token (patscopes claim present) is ALWAYS denied here:
+    scopes gate individual permissions, not roles, so role-gated admin surfaces
+    require an unscoped token. See shopdb/utils/apitoken_auth.py.
+    """
     def decorator(view_func):
         @wraps(view_func)
         def wrapper(*args, **kwargs):
@@ -63,6 +89,12 @@ def require_role(rolename: str):
                     'Authentication required',
                     http_code=401
                 )
+            if get_jwt().get('patscopes') is not None:
+                return error_response(
+                    ErrorCodes.FORBIDDEN,
+                    'Scoped API tokens cannot access role-gated endpoints',
+                    http_code=403
+                )
             if not current_user.hasrole(rolename):
                 return error_response(
                     ErrorCodes.FORBIDDEN,

shopdb/utils/import_mode.py

@@ -16,7 +16,7 @@ regular users. See docs/IMPORT-API.md for the operator manual.
 from datetime import datetime, timezone
 
 from flask import request
-from flask_jwt_extended import verify_jwt_in_request, current_user
+from flask_jwt_extended import verify_jwt_in_request, current_user, get_jwt
 
 
 # Request header a migration client sets to opt a request into import mode.
@@ -48,7 +48,14 @@ def import_mode_active():
         return False
     verify_jwt_in_request(optional=True)
     user = current_user
-    return bool(user is not None and user.hasrole('admin'))
+    if user is None or not user.hasrole('admin'):
+        return False
+    # A scoped PAT never gets import mode: import mode is an admin-role
+    # capability and a scoped token suspends the admin bypass. get_jwt is safe
+    # here - an admin user means a valid JWT was decoded above.
+    if get_jwt().get('patscopes') is not None:
+        return False
+    return True
 
 
 def parse_import_datetime(value):