feat: implement role-based access control for miniapp

- Introduced a new roles table in the database to manage user roles ('user' and 'admin') for access control.
- Updated the user model to include a foreign key reference to the roles table, allowing for role assignment.
- Enhanced command handlers to support the `/set_role` command for admins to assign roles to users.
- Refactored access control logic to utilize role checks instead of username/phone allowlists, improving security and maintainability.
- Updated documentation to reflect changes in access control mechanisms and role management.
- Added unit tests to ensure correct functionality of role assignment and access checks.

duty_teller/api/dependencies.py

@@ -9,7 +9,11 @@ from sqlalchemy.orm import Session
 
 import duty_teller.config as config
 from duty_teller.api.telegram_auth import validate_init_data_with_reason
-from duty_teller.db.repository import get_duties, get_user_by_telegram_id
+from duty_teller.db.repository import (
+    get_duties,
+    get_user_by_telegram_id,
+    can_access_miniapp_for_telegram_user,
+)
 from duty_teller.db.schemas import DUTY_EVENT_TYPES, DutyWithUser
 from duty_teller.db.session import session_scope
 from duty_teller.i18n import t
@@ -181,22 +185,27 @@ def get_authenticated_username(
         raise HTTPException(
             status_code=403, detail=_auth_error_detail(auth_reason, lang)
         )
-    if username and config.can_access_miniapp(username):
-        return username
-    failed_phone: str | None = None
-    if telegram_user_id is not None:
-        user = get_user_by_telegram_id(session, telegram_user_id)
-        if user and user.phone and config.can_access_miniapp_by_phone(user.phone):
-            return username or (user.full_name or "") or f"id:{telegram_user_id}"
-        if user and user.phone:
-            failed_phone = config.normalize_phone(user.phone)
-    log.warning(
-        "username/phone not in allowlist (username=%s, telegram_id=%s, phone=%s)",
-        username,
-        telegram_user_id,
-        failed_phone if failed_phone else "—",
-    )
-    raise HTTPException(status_code=403, detail=t(lang, "api.access_denied"))
+    if telegram_user_id is None:
+        log.warning("initData valid but telegram_user_id missing")
+        raise HTTPException(status_code=403, detail=t(lang, "api.access_denied"))
+    user = get_user_by_telegram_id(session, telegram_user_id)
+    if not user:
+        log.warning(
+            "user not in DB (username=%s, telegram_id=%s)",
+            username,
+            telegram_user_id,
+        )
+        raise HTTPException(status_code=403, detail=t(lang, "api.access_denied"))
+    if not can_access_miniapp_for_telegram_user(session, telegram_user_id):
+        failed_phone = config.normalize_phone(user.phone) if user.phone else None
+        log.warning(
+            "access denied (username=%s, telegram_id=%s, phone=%s)",
+            username,
+            telegram_user_id,
+            failed_phone or "—",
+        )
+        raise HTTPException(status_code=403, detail=t(lang, "api.access_denied"))
+    return username or (user.full_name or "") or f"id:{telegram_user_id}"
 
 
 def fetch_duties_response(

duty_teller/db/__init__.py

@@ -1,6 +1,6 @@
 """Database layer: SQLAlchemy models, Pydantic schemas, repository, init."""
 
-from duty_teller.db.models import Base, User, Duty
+from duty_teller.db.models import Base, User, Duty, Role
 from duty_teller.db.schemas import (
     UserCreate,
     UserInDb,
@@ -28,6 +28,7 @@ __all__ = [
     "Base",
     "User",
     "Duty",
+    "Role",
     "UserCreate",
     "UserInDb",
     "DutyCreate",

duty_teller/db/models.py

@@ -10,6 +10,17 @@ class Base(DeclarativeBase):
     pass
 
 
+class Role(Base):
+    """Role for access control: 'user' (miniapp access), 'admin' (admin actions)."""
+
+    __tablename__ = "roles"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(Text, nullable=False, unique=True)
+
+    users: Mapped[list["User"]] = relationship("User", back_populates="role")
+
+
 class User(Base):
     """Telegram user and display name; may have telegram_user_id=None for import-only users."""
 
@@ -27,7 +38,11 @@ class User(Base):
     name_manually_edited: Mapped[bool] = mapped_column(
         Boolean, nullable=False, server_default="0", default=False
     )
+    role_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("roles.id"), nullable=True
+    )
 
+    role: Mapped["Role | None"] = relationship("Role", back_populates="users")
     duties: Mapped[list["Duty"]] = relationship("Duty", back_populates="user")
 
 

duty_teller/db/repository.py

@@ -7,9 +7,19 @@ from datetime import datetime, timezone
 from sqlalchemy.orm import Session
 
 import duty_teller.config as config
-from duty_teller.db.models import User, Duty, GroupDutyPin, CalendarSubscriptionToken
+from duty_teller.db.models import (
+    User,
+    Duty,
+    GroupDutyPin,
+    CalendarSubscriptionToken,
+    Role,
+)
 from duty_teller.utils.dates import parse_utc_iso_naive, to_date_exclusive_iso
 
+# Role names stored in DB (table roles).
+ROLE_USER = "user"
+ROLE_ADMIN = "admin"
+
 
 def get_user_by_telegram_id(session: Session, telegram_user_id: int) -> User | None:
     """Find user by Telegram user ID.
@@ -24,22 +34,123 @@ def get_user_by_telegram_id(session: Session, telegram_user_id: int) -> User | N
     return session.query(User).filter(User.telegram_user_id == telegram_user_id).first()
 
 
+def get_user_by_username(session: Session, username: str) -> User | None:
+    """Find user by Telegram username (case-insensitive, optional @ prefix).
+
+    Args:
+        session: DB session.
+        username: Telegram username with or without @.
+
+    Returns:
+        User or None if not found.
+    """
+    from sqlalchemy import func
+
+    name = (username or "").strip().lstrip("@").lower()
+    if not name:
+        return None
+    return session.query(User).filter(func.lower(User.username) == name).first()
+
+
+def get_user_role(session: Session, user_id: int) -> str | None:
+    """Return role name for user by internal user id, or None if no role.
+
+    Args:
+        session: DB session.
+        user_id: Internal user id (users.id).
+
+    Returns:
+        Role name ('user' or 'admin') or None.
+    """
+    user = session.get(User, user_id)
+    if not user or not user.role:
+        return None
+    return user.role.name
+
+
 def is_admin_for_telegram_user(session: Session, telegram_user_id: int) -> bool:
-    """Check if the Telegram user is admin (by username or by stored phone).
+    """Check if the Telegram user is admin.
+
+    If user has a role in DB, returns True only for role 'admin'.
+    If user has no role in DB, fallback: True if in ADMIN_USERNAMES or ADMIN_PHONES.
 
     Args:
         session: DB session.
         telegram_user_id: Telegram user id.
 
     Returns:
-        True if user is in ADMIN_USERNAMES or their stored phone is in ADMIN_PHONES.
+        True if admin (by DB role or env fallback).
     """
     user = get_user_by_telegram_id(session, telegram_user_id)
     if not user:
         return False
+    if user.role is not None:
+        return user.role.name == ROLE_ADMIN
     return config.is_admin(user.username or "") or config.is_admin_by_phone(user.phone)
 
 
+def can_access_miniapp_for_telegram_user(
+    session: Session, telegram_user_id: int
+) -> bool:
+    """Check if Telegram user can access the calendar miniapp.
+
+    Access if: user has role 'user' or 'admin' in DB, or (no role in DB and
+    env fallback: in ADMIN_USERNAMES or ADMIN_PHONES). No user in DB -> no access.
+
+    Args:
+        session: DB session.
+        telegram_user_id: Telegram user id.
+
+    Returns:
+        True if user may open the miniapp.
+    """
+    user = get_user_by_telegram_id(session, telegram_user_id)
+    return can_access_miniapp_for_user(session, user) if user else False
+
+
+def can_access_miniapp_for_user(session: Session, user: User | None) -> bool:
+    """Check if user (already loaded) can access the calendar miniapp.
+
+    Access if: user has role 'user' or 'admin' in DB, or (no role in DB and
+    env fallback: in ADMIN_USERNAMES or ADMIN_PHONES).
+
+    Args:
+        session: DB session (unused; kept for API consistency).
+        user: User instance or None.
+
+    Returns:
+        True if user may open the miniapp.
+    """
+    if not user:
+        return False
+    if user.role is not None:
+        return user.role.name in (ROLE_USER, ROLE_ADMIN)
+    return config.is_admin(user.username or "") or config.is_admin_by_phone(user.phone)
+
+
+def set_user_role(session: Session, user_id: int, role_name: str) -> User | None:
+    """Set user role by internal user id and role name.
+
+    Args:
+        session: DB session.
+        user_id: Internal user id (users.id).
+        role_name: 'user' or 'admin'.
+
+    Returns:
+        Updated User or None if user or role not found.
+    """
+    user = session.get(User, user_id)
+    if not user:
+        return None
+    role = session.query(Role).filter(Role.name == role_name).first()
+    if not role:
+        return None
+    user.role_id = role.id
+    session.commit()
+    session.refresh(user)
+    return user
+
+
 def get_or_create_user(
     session: Session,
     telegram_user_id: int,

duty_teller/handlers/__init__.py

@@ -15,6 +15,7 @@ def register_handlers(app: Application) -> None:
     app.add_handler(commands.help_handler)
     app.add_handler(commands.set_phone_handler)
     app.add_handler(commands.calendar_link_handler)
+    app.add_handler(commands.set_role_handler)
     app.add_handler(import_duty_schedule.import_duty_schedule_handler)
     app.add_handler(import_duty_schedule.handover_time_handler)
     app.add_handler(import_duty_schedule.duty_schedule_document_handler)

duty_teller/handlers/commands.py

@@ -6,11 +6,18 @@ import duty_teller.config as config
 from telegram import Update
 from telegram.ext import CommandHandler, ContextTypes
 
+from duty_teller.db.models import User
 from duty_teller.db.session import session_scope
 from duty_teller.db.repository import (
     get_or_create_user,
+    get_user_by_telegram_id,
+    get_user_by_username,
     set_user_phone,
     create_calendar_token,
+    can_access_miniapp_for_telegram_user,
+    set_user_role,
+    ROLE_USER,
+    ROLE_ADMIN,
 )
 from duty_teller.handlers.common import is_admin_async
 from duty_teller.i18n import get_lang, t
@@ -98,7 +105,6 @@ async def calendar_link(update: Update, context: ContextTypes.DEFAULT_TYPE) -> N
         await update.message.reply_text(t(lang, "calendar_link.private_only"))
         return
     telegram_user_id = update.effective_user.id
-    username = (update.effective_user.username or "").strip()
     full_name = build_full_name(
         update.effective_user.first_name, update.effective_user.last_name
     )
@@ -113,9 +119,7 @@ async def calendar_link(update: Update, context: ContextTypes.DEFAULT_TYPE) -> N
                 first_name=update.effective_user.first_name,
                 last_name=update.effective_user.last_name,
             )
-            if not config.can_access_miniapp(
-                username
-            ) and not config.can_access_miniapp_by_phone(user.phone):
+            if not can_access_miniapp_for_telegram_user(session, telegram_user_id):
                 return (None, "denied")
             token = create_calendar_token(session, user.id)
             base = (config.MINI_APP_BASE_URL or "").rstrip("/")
@@ -153,10 +157,78 @@ async def help_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     ]
     if await is_admin_async(update.effective_user.id):
         lines.append(t(lang, "help.import_schedule"))
+        lines.append(t(lang, "help.set_role"))
     await update.message.reply_text("\n".join(lines))
 
 
+async def set_role(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Handle /set_role: set user role (admin only). Usage: /set_role @username user|admin or reply + user|admin."""
+    if not update.message or not update.effective_user:
+        return
+    lang = get_lang(update.effective_user)
+    if not await is_admin_async(update.effective_user.id):
+        await update.message.reply_text(t(lang, "import.admin_only"))
+        return
+    args = (context.args or [])[:2]
+    # Resolve target: reply -> telegram_user_id; or first arg @username / numeric telegram_id
+    target_user = None
+    role_name = None
+    if update.message.reply_to_message and update.message.reply_to_message.from_user:
+        target_telegram_id = update.message.reply_to_message.from_user.id
+        role_name = (args[0] or "").strip().lower() if args else None
+
+        def do_get_reply() -> User | None:
+            with session_scope(config.DATABASE_URL) as session:
+                return get_user_by_telegram_id(session, target_telegram_id)
+
+        target_user = await asyncio.get_running_loop().run_in_executor(
+            None, do_get_reply
+        )
+    elif len(args) >= 2:
+        first = (args[0] or "").strip()
+        role_name = (args[1] or "").strip().lower()
+        if first.lstrip("@").isdigit():
+            target_telegram_id = int(first.lstrip("@"))
+
+            def do_get_by_tid() -> User | None:
+                with session_scope(config.DATABASE_URL) as session:
+                    return get_user_by_telegram_id(session, target_telegram_id)
+
+            target_user = await asyncio.get_running_loop().run_in_executor(
+                None, do_get_by_tid
+            )
+        else:
+
+            def do_get_by_username() -> User | None:
+                with session_scope(config.DATABASE_URL) as session:
+                    return get_user_by_username(session, first)
+
+            target_user = await asyncio.get_running_loop().run_in_executor(
+                None, do_get_by_username
+            )
+    if not role_name or role_name not in (ROLE_USER, ROLE_ADMIN):
+        await update.message.reply_text(t(lang, "set_role.usage"))
+        return
+    if not target_user:
+        await update.message.reply_text(t(lang, "set_role.user_not_found"))
+        return
+
+    def do_set_role() -> bool:
+        with session_scope(config.DATABASE_URL) as session:
+            updated = set_user_role(session, target_user.id, role_name)
+            return updated is not None
+
+    ok = await asyncio.get_running_loop().run_in_executor(None, do_set_role)
+    if ok:
+        await update.message.reply_text(
+            t(lang, "set_role.done", name=target_user.full_name, role=role_name)
+        )
+    else:
+        await update.message.reply_text(t(lang, "set_role.error"))
+
+
 start_handler = CommandHandler("start", start)
 help_handler = CommandHandler("help", help_cmd)
 set_phone_handler = CommandHandler("set_phone", set_phone)
 calendar_link_handler = CommandHandler("calendar_link", calendar_link)
+set_role_handler = CommandHandler("set_role", set_role)

duty_teller/i18n/messages.py

@@ -22,6 +22,11 @@ MESSAGES: dict[str, dict[str, str]] = {
         ),
         "calendar_link.error": "Could not generate link. Please try again later.",
         "help.import_schedule": "/import_duty_schedule — Import duty schedule (JSON)",
+        "help.set_role": "/set_role — Set user role (user | admin)",
+        "set_role.usage": "Usage: /set_role @username user|admin or reply to a message and send /set_role user|admin",
+        "set_role.user_not_found": "User not found.",
+        "set_role.done": "Role set: {name} → {role}",
+        "set_role.error": "Could not set role.",
         "errors.generic": "An error occurred. Please try again later.",
         "pin_duty.group_only": "The /pin_duty command works only in groups.",
         "pin_duty.no_message": "There is no duty message in this chat yet. Add the bot to the group — it will create one automatically.",
@@ -81,6 +86,11 @@ MESSAGES: dict[str, dict[str, str]] = {
         "calendar_link.help_hint": "Подпишитесь на эту ссылку в Google Календаре, Календаре Apple или Outlook, чтобы видеть только свои дежурства.",
         "calendar_link.error": "Не удалось сформировать ссылку. Попробуйте позже.",
         "help.import_schedule": "/import_duty_schedule — Импорт расписания дежурств (JSON)",
+        "help.set_role": "/set_role — Выдать роль пользователю (user | admin)",
+        "set_role.usage": "Использование: /set_role @username user|admin или ответьте на сообщение и отправьте /set_role user|admin",
+        "set_role.user_not_found": "Пользователь не найден.",
+        "set_role.done": "Роль установлена: {name} → {role}",
+        "set_role.error": "Не удалось установить роль.",
         "errors.generic": "Произошла ошибка. Попробуйте позже.",
         "pin_duty.group_only": "Команда /pin_duty работает только в группах.",
         "pin_duty.no_message": "В этом чате ещё нет сообщения о дежурстве. Добавьте бота в группу — оно создастся автоматически.",