account-kit 0.1.0__py3-none-any.whl

account_kit/__init__.py

@@ -0,0 +1,9 @@
+"""Shared account kit: one async user model for every app."""
+
+from account_kit.router import mount_account
+from account_kit.schema_setup import init_db
+from account_kit.seed import seed_defaults
+
+__version__ = "0.1.0"
+
+__all__ = ["init_db", "mount_account", "seed_defaults", "__version__"]

account_kit/admin_router.py

@@ -0,0 +1,181 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from account_kit.admin_schemas import AdminUserPatch, RoleBody, RoleChangeCreate, RoleChangeReview, RolePatch, TierBody, TierPatch
+from account_kit.catalog import apply_admin_user_patch, create_role, create_tier, delete_role, delete_tier, patch_role, patch_tier
+from account_kit.config import get_config
+from account_kit.deps import get_current_user, get_db, require_admin
+from account_kit.models import Role, RoleChangeRequest, User, UserTier
+from account_kit.service import assert_role_code, get_user_by_id, to_response
+
+admin_router = APIRouter(tags=["account-admin"])
+public_extra = APIRouter(tags=["auth"])
+
+
+def _role_dict(row: Role) -> dict:
+    return {
+        "code": row.code,
+        "name": row.name,
+        "sort_order": row.sort_order,
+        "description": row.description,
+        "is_default": row.is_default,
+        "allow_register": row.allow_register,
+    }
+
+
+def _tier_dict(row: UserTier) -> dict:
+    return {
+        "code": row.code,
+        "name": row.name,
+        "sort_order": row.sort_order,
+        "badge_color": row.badge_color,
+        "description": row.description,
+        "is_default": row.is_default,
+    }
+
+
+@public_extra.get("/roles")
+async def public_roles(db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(Role).where(Role.allow_register.is_(True)).order_by(Role.sort_order, Role.code))
+    return [_role_dict(row) for row in result.scalars().all()]
+
+
+@public_extra.get("/tiers")
+async def public_tiers(db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(UserTier).order_by(UserTier.sort_order, UserTier.code))
+    return [_tier_dict(row) for row in result.scalars().all()]
+
+
+@public_extra.post("/role-change-requests")
+async def request_role_change(
+    body: RoleChangeCreate,
+    current_user=Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not get_config().role_change_enabled:
+        raise HTTPException(status_code=404, detail="Not found")
+    code = assert_role_code(body.requested_role)
+    role = await db.get(Role, code)
+    if role is None:
+        raise HTTPException(status_code=400, detail="角色不存在")
+    if code == current_user.role:
+        raise HTTPException(status_code=400, detail="已经是该角色")
+    existing = await db.execute(
+        select(RoleChangeRequest).where(
+            RoleChangeRequest.user_id == current_user.id,
+            RoleChangeRequest.status == "pending",
+        )
+    )
+    if existing.scalars().first():
+        raise HTTPException(status_code=409, detail="已有待审核的角色申请")
+    row = RoleChangeRequest(user_id=current_user.id, from_role=current_user.role, to_role=code, status="pending")
+    db.add(row)
+    await db.commit()
+    await db.refresh(row)
+    return {"id": row.id, "from_role": row.from_role, "to_role": row.to_role, "status": row.status}
+
+
+@admin_router.get("/roles")
+async def list_roles(_admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(Role).order_by(Role.sort_order, Role.code))
+    return [_role_dict(row) for row in result.scalars().all()]
+
+
+@admin_router.post("/roles", status_code=201)
+async def add_role(body: RoleBody, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    return _role_dict(await create_role(db, body))
+
+
+@admin_router.patch("/roles/{code}")
+async def edit_role(code: str, body: RolePatch, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    return _role_dict(await patch_role(db, code, body))
+
+
+@admin_router.delete("/roles/{code}", status_code=204)
+async def remove_role(code: str, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    await delete_role(db, code)
+
+
+@admin_router.get("/tiers")
+async def list_tiers(_admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(UserTier).order_by(UserTier.sort_order, UserTier.code))
+    return [_tier_dict(row) for row in result.scalars().all()]
+
+
+@admin_router.post("/tiers", status_code=201)
+async def add_tier(body: TierBody, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    return _tier_dict(await create_tier(db, body))
+
+
+@admin_router.patch("/tiers/{code}")
+async def edit_tier(code: str, body: TierPatch, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    return _tier_dict(await patch_tier(db, code, body))
+
+
+@admin_router.delete("/tiers/{code}", status_code=204)
+async def remove_tier(code: str, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    await delete_tier(db, code)
+
+
+@admin_router.get("/users")
+async def list_users(_admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(User).order_by(User.created_at.desc()))
+    return [await to_response(db, user) for user in result.scalars().all()]
+
+
+@admin_router.patch("/users/{user_id}")
+async def patch_user(
+    user_id: str,
+    body: AdminUserPatch,
+    _admin=Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    user = await get_user_by_id(db, user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    user = await apply_admin_user_patch(db, user, body)
+    return await to_response(db, user)
+
+
+@admin_router.delete("/users/{user_id}", status_code=204)
+async def delete_user(user_id: str, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    config = get_config()
+    user = await get_user_by_id(db, user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    if config.on_deleted is not None:
+        await config.on_deleted(db, user)
+    await db.delete(user)
+    await db.commit()
+
+
+@admin_router.post("/role-change-requests/{request_id}/review")
+async def review_role_change(
+    request_id: str,
+    body: RoleChangeReview,
+    admin=Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    if body.status not in ("approved", "rejected"):
+        raise HTTPException(status_code=400, detail="状态无效")
+    try:
+        request_uuid = uuid.UUID(request_id)
+    except ValueError:
+        raise HTTPException(status_code=404, detail="申请不存在")
+    row = await db.get(RoleChangeRequest, request_uuid)
+    if row is None or row.status != "pending":
+        raise HTTPException(status_code=404, detail="申请不存在")
+    row.status = body.status
+    from datetime import datetime, timezone
+
+    row.reviewed_at = datetime.now(timezone.utc)
+    row.reviewed_by = admin.id
+    if body.status == "approved":
+        user = await get_user_by_id(db, row.user_id)
+        if user is not None:
+            user.role = row.to_role
+    await db.commit()
+    return {"id": row.id, "status": row.status}

account_kit/admin_schemas.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import uuid
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from account_kit.schemas import ApprovalStatus
+
+
+class RoleBody(BaseModel):
+    code: str = Field(min_length=1, max_length=50)
+    name: str = Field(min_length=1, max_length=50)
+    sort_order: int = 0
+    description: Optional[str] = None
+    is_default: bool = False
+    allow_register: bool = False
+
+
+class RolePatch(BaseModel):
+    name: Optional[str] = Field(default=None, min_length=1, max_length=50)
+    sort_order: Optional[int] = None
+    description: Optional[str] = None
+    is_default: Optional[bool] = None
+    allow_register: Optional[bool] = None
+
+
+class TierBody(BaseModel):
+    code: str = Field(min_length=1, max_length=20)
+    name: str = Field(min_length=1, max_length=50)
+    sort_order: int = 0
+    badge_color: Optional[str] = None
+    description: Optional[str] = None
+    is_default: bool = False
+
+
+class TierPatch(BaseModel):
+    name: Optional[str] = Field(default=None, min_length=1, max_length=50)
+    sort_order: Optional[int] = None
+    badge_color: Optional[str] = None
+    description: Optional[str] = None
+    is_default: Optional[bool] = None
+
+
+class AdminUserPatch(BaseModel):
+    role: Optional[str] = None
+    is_admin: Optional[bool] = None
+    is_active: Optional[bool] = None
+    approval_status: Optional[ApprovalStatus] = None
+    tier_code: Optional[str] = None
+
+
+class RoleChangeCreate(BaseModel):
+    requested_role: str = Field(min_length=1, max_length=50)
+
+
+class RoleChangeReview(BaseModel):
+    status: ApprovalStatus

account_kit/catalog.py

@@ -0,0 +1,167 @@
+"""Role and tier catalog. Limits stay in the host; this only stores names."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from fastapi import HTTPException
+from sqlalchemy import func, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from account_kit.models import Role, User, UserTier, UserTierAssignment
+from account_kit.service import assert_role_code
+
+
+async def _clear_default_role(db: AsyncSession) -> None:
+    await db.execute(update(Role).values(is_default=False))
+
+
+async def _clear_default_tier(db: AsyncSession) -> None:
+    await db.execute(update(UserTier).values(is_default=False))
+
+
+async def create_role(db: AsyncSession, body) -> Role:
+    code = assert_role_code(body.code)
+    if await db.get(Role, code):
+        raise HTTPException(status_code=409, detail="角色已存在")
+    if body.is_default:
+        await _clear_default_role(db)
+    row = Role(
+        code=code,
+        name=body.name.strip(),
+        sort_order=body.sort_order,
+        description=body.description,
+        is_default=body.is_default,
+        allow_register=body.allow_register,
+    )
+    db.add(row)
+    await db.commit()
+    await db.refresh(row)
+    return row
+
+
+async def patch_role(db: AsyncSession, code: str, body) -> Role:
+    row = await db.get(Role, code)
+    if row is None:
+        raise HTTPException(status_code=404, detail="角色不存在")
+    if body.name is not None:
+        row.name = body.name.strip()
+    if body.sort_order is not None:
+        row.sort_order = body.sort_order
+    if body.description is not None:
+        row.description = body.description
+    if body.allow_register is not None:
+        row.allow_register = body.allow_register
+    if body.is_default is True:
+        await _clear_default_role(db)
+        row.is_default = True
+    elif body.is_default is False and row.is_default:
+        raise HTTPException(status_code=400, detail="请先把另一个角色设为默认")
+    await db.commit()
+    await db.refresh(row)
+    return row
+
+
+async def delete_role(db: AsyncSession, code: str) -> None:
+    row = await db.get(Role, code)
+    if row is None:
+        raise HTTPException(status_code=404, detail="角色不存在")
+    if row.is_default:
+        raise HTTPException(status_code=400, detail="不能删除默认角色")
+    used = await db.scalar(select(func.count()).select_from(User).where(User.role == code))
+    if used:
+        raise HTTPException(status_code=409, detail="仍有用户使用该角色")
+    await db.delete(row)
+    await db.commit()
+
+
+async def create_tier(db: AsyncSession, body) -> UserTier:
+    code = (body.code or "").strip()
+    if not code:
+        raise HTTPException(status_code=400, detail="等级代码无效")
+    if await db.get(UserTier, code):
+        raise HTTPException(status_code=409, detail="等级已存在")
+    if body.is_default:
+        await _clear_default_tier(db)
+    row = UserTier(
+        code=code,
+        name=body.name.strip(),
+        sort_order=body.sort_order,
+        badge_color=body.badge_color,
+        description=body.description,
+        is_default=body.is_default,
+    )
+    db.add(row)
+    await db.commit()
+    await db.refresh(row)
+    return row
+
+
+async def patch_tier(db: AsyncSession, code: str, body) -> UserTier:
+    row = await db.get(UserTier, code)
+    if row is None:
+        raise HTTPException(status_code=404, detail="等级不存在")
+    if body.name is not None:
+        row.name = body.name.strip()
+    if body.sort_order is not None:
+        row.sort_order = body.sort_order
+    if body.badge_color is not None:
+        row.badge_color = body.badge_color
+    if body.description is not None:
+        row.description = body.description
+    if body.is_default is True:
+        await _clear_default_tier(db)
+        row.is_default = True
+    elif body.is_default is False and row.is_default:
+        raise HTTPException(status_code=400, detail="请先把另一个等级设为默认")
+    await db.commit()
+    await db.refresh(row)
+    return row
+
+
+async def delete_tier(db: AsyncSession, code: str) -> None:
+    row = await db.get(UserTier, code)
+    if row is None:
+        raise HTTPException(status_code=404, detail="等级不存在")
+    if row.is_default:
+        raise HTTPException(status_code=400, detail="不能删除默认等级")
+    used = await db.scalar(
+        select(func.count()).select_from(UserTierAssignment).where(UserTierAssignment.tier_code == code)
+    )
+    if used:
+        raise HTTPException(status_code=409, detail="仍有用户属于该等级")
+    await db.delete(row)
+    await db.commit()
+
+
+async def set_user_tier(db: AsyncSession, user: User, tier_code: str) -> None:
+    tier = await db.get(UserTier, tier_code)
+    if tier is None:
+        raise HTTPException(status_code=400, detail="等级不存在")
+    row = await db.get(UserTierAssignment, user.id)
+    if row is None:
+        db.add(UserTierAssignment(user_id=user.id, tier_code=tier.code))
+    else:
+        row.tier_code = tier.code
+        row.updated_at = datetime.now(timezone.utc)
+
+
+async def apply_admin_user_patch(db, user: User, body) -> User:
+    if body.role is not None:
+        code = assert_role_code(body.role)
+        if await db.get(Role, code) is None:
+            raise HTTPException(status_code=400, detail="角色不存在")
+        user.role = code
+    if body.is_admin is not None:
+        user.is_admin = body.is_admin
+    if body.is_active is not None:
+        user.is_active = body.is_active
+    if body.approval_status is not None:
+        user.approval_status = body.approval_status
+        if body.approval_status == "approved" and user.approved_at is None:
+            user.approved_at = datetime.now(timezone.utc)
+    if body.tier_code is not None:
+        await set_user_tier(db, user, body.tier_code)
+    await db.commit()
+    await db.refresh(user)
+    return user

account_kit/config.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Awaitable, Callable, Optional, Tuple
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+@dataclass
+class SmtpConfig:
+    host: str = ""
+    port: int = 587
+    user: str = ""
+    password: str = ""
+    from_email: str = ""
+    tls: bool = True
+
+
+# to, purpose, code, language
+Mailer = Callable[[str, str, str, str], Awaitable[None]]
+UserHook = Callable[..., Awaitable[None]]
+# request, username
+BeforeLogin = Callable[[object, str], Awaitable[None]]
+# request
+BeforeRegister = Callable[[object], Awaitable[None]]
+
+
+@dataclass
+class AccountKitConfig:
+    """Runtime settings supplied by the host app. Nothing here is a quota."""
+
+    jwt_secret: str
+    jwt_algorithm: str = "HS256"
+    access_token_expire_minutes: int = 1440
+    # stateless | single_device
+    session_mode: str = "stateless"
+    session_active_hours: int = 12
+    require_approval: bool = False
+    email_domain_restriction: bool = False
+    allowed_email_domains: Tuple[str, ...] = ()
+    brand_name: str = "Account"
+    password_min_length: int = 6
+    smtp: SmtpConfig = field(default_factory=SmtpConfig)
+    # HMAC material for email codes and recovery codes. Falls back to jwt_secret.
+    secret_key: str = ""
+    # Fernet material for TOTP secrets. Falls back to secret_key, then jwt_secret.
+    file_encryption_key: str = ""
+    two_factor_enabled: bool = True
+    role_change_enabled: bool = False
+    trusted_device_days: int = 30
+    forbid_admin_like_usernames: bool = False
+    reserved_usernames: Tuple[str, ...] = ()
+    api_prefix: str = "/api/auth"
+    admin_prefix: str = "/api/admin/account"
+    mailer: Optional[Mailer] = None
+    before_login: Optional[BeforeLogin] = None
+    before_register: Optional[BeforeRegister] = None
+    on_registered: Optional[UserHook] = None
+    on_login: Optional[UserHook] = None
+    on_password_changed: Optional[UserHook] = None
+    on_deleted: Optional[UserHook] = None
+
+    def code_secret(self) -> str:
+        return self.secret_key or self.jwt_secret
+
+    def encryption_material(self) -> str:
+        return self.file_encryption_key or self.secret_key or self.jwt_secret
+
+
+_config: Optional[AccountKitConfig] = None
+
+
+def set_config(config: AccountKitConfig) -> None:
+    global _config
+    _config = config
+
+
+def get_config() -> AccountKitConfig:
+    if _config is None:
+        raise RuntimeError("account-kit is not configured")
+    return _config

account_kit/crypto.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+
+from cryptography.fernet import Fernet
+
+
+def fernet_for(material: str) -> Fernet:
+    key = base64.urlsafe_b64encode(hashlib.sha256(material.encode("utf-8")).digest())
+    return Fernet(key)

account_kit/db.py

@@ -0,0 +1,14 @@
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+NAMING = {
+    "ix": "ix_%(column_0_label)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData(naming_convention=NAMING)

account_kit/deps.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from fastapi import Depends, HTTPException, Query, Request, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from account_kit.config import get_config
+from account_kit.service import get_user_by_id
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login", auto_error=False)
+
+
+async def get_db(request: Request):
+    agen = request.app.state.account_get_db()
+    session = await agen.__anext__()
+    try:
+        yield session
+    finally:
+        await agen.aclose()
+
+
+async def user_from_access_token(db: AsyncSession, raw: Optional[str]):
+    credentials = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    if not raw:
+        raise credentials
+    config = get_config()
+    try:
+        payload = jwt.decode(raw, config.jwt_secret, algorithms=[config.jwt_algorithm])
+        sub = payload.get("sub")
+        user_id = uuid.UUID(str(sub))
+    except (JWTError, ValueError, TypeError):
+        raise credentials
+
+    user = await get_user_by_id(db, user_id)
+    if user is None:
+        raise credentials
+    if not user.is_active:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="User is disabled")
+
+    if config.session_mode == "single_device":
+        sid = payload.get("sid")
+        if not sid or sid != user.current_session_id:
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="SESSION_REPLACED")
+        now = datetime.now(timezone.utc)
+        last = user.session_last_seen_at
+        if last is not None and last.tzinfo is None:
+            last = last.replace(tzinfo=timezone.utc)
+        if last is None or now - last > timedelta(seconds=60):
+            user.session_last_seen_at = now
+            await db.commit()
+    return user
+
+
+async def get_current_user(
+    token: Optional[str] = Depends(oauth2_scheme),
+    query_token: Optional[str] = Query(None, alias="token"),
+    db: AsyncSession = Depends(get_db),
+):
+    return await user_from_access_token(db, token or query_token)
+
+
+async def require_admin(current_user=Depends(get_current_user)):
+    if not current_user.is_admin:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin required")
+    return current_user

account_kit/emailer.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import os
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+from jinja2 import Environment, FileSystemLoader
+
+from account_kit.config import AccountKitConfig
+
+_template_dir = os.path.join(os.path.dirname(__file__), "templates", "emails")
+_jinja = Environment(loader=FileSystemLoader(_template_dir))
+
+_ACTIONS = {
+    "zh": {
+        "register": "注册账户",
+        "reset_password": "重置密码",
+        "change_password": "修改密码",
+        "login_2fa": "登录验证",
+        "disable_2fa": "关闭两步验证",
+    },
+    "en": {
+        "register": "register",
+        "reset_password": "reset your password",
+        "change_password": "change your password",
+        "login_2fa": "sign in",
+        "disable_2fa": "turn off two-factor authentication",
+    },
+}
+
+
+def render_code_email(config: AccountKitConfig, purpose: str, code: str, language: str) -> tuple[str, str]:
+    lang = language if language in ("zh", "en") else "zh"
+    action = _ACTIONS[lang].get(purpose, purpose)
+    brand = config.brand_name
+    if lang == "zh":
+        subject = f"【{brand}】验证码"
+    else:
+        subject = f"[{brand}] Verification code"
+    body = _jinja.get_template(f"verification_{lang}.html").render(action=action, code=code, brand=brand)
+    return subject, body
+
+
+def deliver_smtp(config: AccountKitConfig, to_email: str, subject: str, body: str) -> None:
+    cfg = config.smtp
+    if not cfg.user or not cfg.password:
+        return
+    msg = MIMEMultipart()
+    sender = cfg.from_email or cfg.user
+    msg["From"] = f"{config.brand_name} <{sender}>"
+    msg["To"] = to_email
+    msg["Subject"] = subject
+    msg.attach(MIMEText(body, "html", "utf-8"))
+    if cfg.port == 465:
+        server = smtplib.SMTP_SSL(cfg.host, cfg.port)
+    else:
+        server = smtplib.SMTP(cfg.host, cfg.port)
+        if cfg.tls:
+            server.starttls()
+    server.login(cfg.user, cfg.password)
+    server.send_message(msg)
+    server.quit()
+
+
+async def send_code_email(config: AccountKitConfig, to_email: str, purpose: str, code: str, language: str = "zh") -> None:
+    if config.mailer is not None:
+        await config.mailer(to_email, purpose, code, language)
+        return
+    subject, body = render_code_email(config, purpose, code, language)
+    deliver_smtp(config, to_email, subject, body)