dwy-auth 0.1.0__py3-none-any.whl

dwy_auth/__init__.py

@@ -0,0 +1,92 @@
+"""独立认证核心；旧 EAPI 服务/HTTP 入口按需加载，不成为核心的反向依赖。"""
+
+from importlib import import_module
+
+from .contracts import AuthPrincipal, SessionBackend, SessionTokens, VerifiedIdentity
+from .email_auth import (
+    EapiEmailCodeSender,
+    EmailAuthConfig,
+    EmailCodeChallenge,
+    EmailCodeSender,
+    SessionPolicy,
+)
+from .google import OfficialGoogleVerifier
+from .models import (
+    AccountDeletion,
+    AuthError,
+    DevicePage,
+    DeviceQuery,
+    DeviceSummary,
+    GoogleConfig,
+    GoogleIdentity,
+    GoogleVerifier,
+    TokenResponse,
+    UserProfile,
+)
+from .session_backend import JWTSessionBackend
+from .session_storage import SessionTables, register_session_tables
+from .storage import AuthTables, build_auth_tables
+
+# 兼容旧消费者的显式导入；import dwy_auth 不隐式加载 EAPI/FastAPI。
+_LAZY_EXPORTS = {
+    "AuthService": (".service", "AuthService"),
+    "install_auth_routes": (".http", "install_auth_routes"),
+    "AuthRuntime": (".runtime", "AuthRuntime"),
+    "RuntimeTables": (".runtime_storage", "RuntimeTables"),
+    "build_runtime_tables": (".runtime_storage", "build_runtime_tables"),
+    "SubjectAdapter": (".subjects", "SubjectAdapter"),
+    "SubjectRegistration": (".subjects", "SubjectRegistration"),
+    "ExternalIdentity": (".providers", "ExternalIdentity"),
+    "ExternalIdentityProvider": (".providers", "ExternalIdentityProvider"),
+    "GoogleIdentityProvider": (".providers", "GoogleIdentityProvider"),
+}
+
+
+def __getattr__(name: str):
+    """保留既有入口；新 runtime 使用独立合同，不依赖旧业务用户表。"""
+    target = _LAZY_EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(name)
+    module, attribute = target
+    value = getattr(import_module(module, __name__), attribute)
+    globals()[name] = value
+    return value
+
+
+__all__ = [
+    "AuthPrincipal",
+    "AuthRuntime",
+    "ExternalIdentity",
+    "ExternalIdentityProvider",
+    "GoogleIdentityProvider",
+    "JWTSessionBackend",
+    "RuntimeTables",
+    "SessionBackend",
+    "SessionTables",
+    "SessionTokens",
+    "SubjectAdapter",
+    "SubjectRegistration",
+    "VerifiedIdentity",
+    "build_runtime_tables",
+    "register_session_tables",
+    "AccountDeletion",
+    "AuthError",
+    "EmailAuthConfig",
+    "EapiEmailCodeSender",
+    "EmailCodeSender",
+    "EmailCodeChallenge",
+    "SessionPolicy",
+    "AuthService",
+    "AuthTables",
+    "DevicePage",
+    "DeviceQuery",
+    "DeviceSummary",
+    "GoogleConfig",
+    "GoogleIdentity",
+    "GoogleVerifier",
+    "OfficialGoogleVerifier",
+    "TokenResponse",
+    "UserProfile",
+    "build_auth_tables",
+    "install_auth_routes",
+]

dwy_auth/admin/__init__.py

@@ -0,0 +1,14 @@
+"""管理员 Cookie 认证入口，与 Google 用户会话独立。"""
+
+from .config import AdminAuthConfig
+from .http import AdminAuthBinding, install_admin_auth
+from .service import COOKIE_NAME, AdminAuth, AdminSession
+
+__all__ = [
+    "COOKIE_NAME",
+    "AdminAuth",
+    "AdminAuthBinding",
+    "AdminAuthConfig",
+    "AdminSession",
+    "install_admin_auth",
+]

dwy_auth/admin/config.py

@@ -0,0 +1,40 @@
+"""管理员认证配置由宿主显式注入，不读取环境变量或业务配置。"""
+
+from urllib.parse import urlsplit
+
+from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field, SecretStr, field_validator
+
+
+class AdminAuthConfig(BaseModel):
+    """一个独立管理员 Cookie 边界；生产宿主负责启用策略与密码强度。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True, hide_input_in_errors=True)
+    username: str = Field(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_.@-]+$")
+    password: SecretStr = Field(min_length=12, max_length=256, repr=False)
+    session_seconds: int = Field(default=28800, ge=300, le=86400)
+    secure_cookie: bool = False
+    origin: str | None = Field(default=None, max_length=2048)
+
+    @field_validator("origin")
+    @classmethod
+    def validate_origin(cls, value: str | None) -> str | None:
+        """只接受单个完整 HTTP origin，保持与可信部署值精确比较。"""
+        if value is None:
+            return None
+        if any(ord(char) <= 32 or ord(char) == 127 for char in value):
+            raise ValueError("origin must be a single HTTP origin")
+        parsed = urlsplit(value)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.netloc
+            or parsed.path
+            or "?" in value
+            or "#" in value
+            or "\\" in value
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.netloc.endswith(":")
+        ):
+            raise ValueError("origin must contain only scheme, host and optional port")
+        AnyHttpUrl(value)
+        return value

dwy_auth/admin/http.py

@@ -0,0 +1,175 @@
+"""独立 Cookie 登录装配；业务路由只复用返回的依赖，不进入认证包。"""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Annotated
+from urllib.parse import urlsplit
+
+from dwyeapi import ApiResponse
+from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request, Response
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ConfigDict, Field
+from starlette.concurrency import run_in_threadpool
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from ..http import install_safe_validation_handler
+from .config import AdminAuthConfig
+from .service import COOKIE_NAME, AdminAuth
+
+
+class LoginRequest(BaseModel):
+    """固定有界登录 schema，错误响应不得回显密码。"""
+
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+    username: str = Field(min_length=1, max_length=64)
+    password: str = Field(min_length=1, max_length=256, repr=False)
+
+
+class AdminSecurityMiddleware:
+    """独立登录装配的有界请求与禁止缓存，不读取或拦截业务请求。"""
+
+    def __init__(self, app: ASGIApp):
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send):
+        if scope["type"] != "http" or not scope["path"].startswith("/api/admin/auth/"):
+            await self.app(scope, receive, send)
+            return
+
+        async def secure_send(message: Message):
+            if message["type"] == "http.response.start":
+                message["headers"] = [
+                    *message.get("headers", []),
+                    (b"cache-control", b"no-store"),
+                    (b"x-content-type-options", b"nosniff"),
+                ]
+            await send(message)
+
+        body = bytearray()
+        while True:
+            message = await receive()
+            if message["type"] == "http.disconnect":
+                return
+            chunk = message.get("body", b"")
+            if len(body) + len(chunk) > 4096:
+                response = JSONResponse(
+                    status_code=413,
+                    content=ApiResponse(code="REQUEST_TOO_LARGE", message="请求体超过限制").model_dump(),
+                )
+                await response(scope, receive, secure_send)
+                return
+            body.extend(chunk)
+            if not message.get("more_body", False):
+                break
+        delivered = False
+
+        async def replay() -> Message:
+            nonlocal delivered
+            if not delivered:
+                delivered = True
+                return {"type": "http.request", "body": bytes(body), "more_body": False}
+            return await receive()
+
+        await self.app(scope, replay, secure_send)
+
+
+@dataclass(frozen=True)
+class AdminAuthBinding:
+    """供宿主业务装配使用的管理员依赖，不授予任何用户 Principal。"""
+
+    auth: AdminAuth
+    require_admin: Callable[[Request], Awaitable[str]]
+    same_origin: Callable[[Request], Awaitable[None]]
+
+
+def install_admin_auth(
+    app: FastAPI, config: AdminAuthConfig, *, install_security: bool = True
+) -> AdminAuthBinding:
+    """装配登录、当前会话及退出；宿主可保留覆盖全部管理 API 的既有安全中间件。"""
+    auth = AdminAuth(config)
+    app.state.admin_auth = auth
+    install_safe_validation_handler(app)
+    if install_security:
+        app.add_middleware(AdminSecurityMiddleware)
+    router = APIRouter(prefix="/api/admin", tags=["admin"])
+
+    async def same_origin(request: Request):
+        """JSON + Strict cookie 为默认边界，额外拒绝带跨域 Origin 的写请求。"""
+        origin = request.headers.get("origin")
+        if origin is not None:
+            if len(origin) > 2048:
+                raise HTTPException(403)
+            if config.origin is not None:
+                if origin != config.origin:
+                    raise HTTPException(403)
+                return
+            try:
+                parsed = urlsplit(origin)
+            except ValueError:
+                # 无效 IPv6 等外部输入不能穿过解析边界成为内部错误。
+                raise HTTPException(403) from None
+            if parsed.scheme != request.url.scheme or parsed.netloc != request.url.netloc:
+                raise HTTPException(403)
+
+    async def require_admin(request: Request) -> str:
+        """仅接受宿主 cookie，不能将任一应用 Bearer 提升为管理员。"""
+        token = request.cookies.get(COOKIE_NAME, "")
+        session = auth.resolve(token)
+        if session is None:
+            raise HTTPException(401)
+        return session.username
+
+    @router.post("/auth/login", dependencies=[Depends(same_origin)])
+    async def login(body: LoginRequest, request: Request, response: Response):
+        """失败原因统一；密码派生移到框架线程池避免阻塞事件循环。"""
+        address = request.client.host if request.client else "unknown"
+        if not auth.allow_attempt(address):
+            # 通用 HTTPException handler 刻意丢弃 detail；此处只返回固定安全文案。
+            return JSONResponse(
+                status_code=429,
+                content=ApiResponse(
+                    code="ADMIN_RATE_LIMITED", message="登录尝试过于频繁，请在5分钟后重试"
+                ).model_dump(mode="json"),
+                headers={"Retry-After": "300"},
+            )
+        if not await run_in_threadpool(auth.authenticate, body.username, body.password):
+            return JSONResponse(
+                status_code=401,
+                content=ApiResponse(code="ADMIN_INVALID_CREDENTIALS", message="用户名或密码错误").model_dump(
+                    mode="json"
+                ),
+            )
+        previous = request.cookies.get(COOKIE_NAME, "")
+        if previous:
+            auth.revoke(previous)
+        response.set_cookie(
+            COOKIE_NAME,
+            auth.create_session(),
+            max_age=auth.lifetime,
+            httponly=True,
+            secure=config.secure_cookie,
+            samesite="strict",
+            path="/api/admin",
+        )
+        return ApiResponse.ok({"username": auth.username})
+
+    @router.get("/auth/me")
+    async def me(username: Annotated[str, Depends(require_admin)]):
+        """刷新页面只确认管理身份，不读取业务库。"""
+        return ApiResponse.ok({"username": username})
+
+    @router.post("/auth/logout", dependencies=[Depends(require_admin), Depends(same_origin)])
+    async def logout(request: Request, response: Response):
+        """退出即时撤销服务端状态，删除 cookie 使用一致路径与安全属性。"""
+        auth.revoke(request.cookies[COOKIE_NAME])
+        response.delete_cookie(
+            COOKIE_NAME,
+            path="/api/admin",
+            httponly=True,
+            secure=config.secure_cookie,
+            samesite="strict",
+        )
+        return ApiResponse.ok(None)
+
+    app.include_router(router)
+    return AdminAuthBinding(auth, require_admin, same_origin)

dwy_auth/admin/service.py

@@ -0,0 +1,81 @@
+"""单进程管理员会话：随机 cookie、内存撤销和固定窗口限速。"""
+
+import hashlib
+import hmac
+import secrets
+import time
+from dataclasses import dataclass
+
+from .config import AdminAuthConfig
+
+COOKIE_NAME = "app_cloud_admin"
+
+
+@dataclass(frozen=True)
+class AdminSession:
+    """只保存服务端摘要与到期时间，应用 token 永远不参与验证。"""
+
+    username: str
+    expires_at: float
+
+
+class AdminAuth:
+    """最小单管理员认证；重启撤销全部会话，部署应使用单宿主 worker。"""
+
+    def __init__(self, settings: AdminAuthConfig):
+        """密码只在启动时经 PBKDF2 派生，后续常量时间比较派生值。"""
+        self.username = settings.username
+        self.lifetime = settings.session_seconds
+        self.salt = secrets.token_bytes(32)
+        self.password_hash = self._derive(settings.password.get_secret_value())
+        self.sessions: dict[str, AdminSession] = {}
+        self.attempts: dict[str, tuple[float, int]] = {}
+
+    def _derive(self, password: str) -> bytes:
+        """复用标准库 PBKDF2，保持密码验证成本固定。"""
+        return hashlib.pbkdf2_hmac("sha256", password.encode(), self.salt, 600_000)
+
+    def allow_attempt(self, address: str) -> bool:
+        """每来源五分钟最多五次；不信任可伪造的代理头，且限制内存键数。"""
+        now = time.monotonic()
+        self.attempts = {key: value for key, value in self.attempts.items() if value[0] > now}
+        expiry, count = self.attempts.get(address, (now + 300, 0))
+        if count >= 5 or (address not in self.attempts and len(self.attempts) >= 2048):
+            return False
+        self.attempts[address] = (expiry, count + 1)
+        return True
+
+    def authenticate(self, username: str, password: str) -> bool:
+        """用户名不存在时也执行同等密码派生，不向调用方区分失败原因。"""
+        valid_password = hmac.compare_digest(self.password_hash, self._derive(password))
+        return hmac.compare_digest(username.encode(), self.username.encode()) and valid_password
+
+    def create_session(self) -> str:
+        """原始随机 token 只交给 cookie；会话总数有上限，避免内存无限增长。"""
+        now = time.monotonic()
+        self.sessions = {key: value for key, value in self.sessions.items() if value.expires_at > now}
+        if len(self.sessions) >= 1024:
+            del self.sessions[next(iter(self.sessions))]
+        token = secrets.token_urlsafe(32)
+        self.sessions[self._digest(token)] = AdminSession(self.username, now + self.lifetime)
+        return token
+
+    @staticmethod
+    def _digest(token: str) -> str:
+        """服务端仅索引 cookie 摘要；不保存可重放的原始会话值。"""
+        return hashlib.sha256(token.encode()).hexdigest()
+
+    def resolve(self, token: str) -> AdminSession | None:
+        """拒绝无界或错误格式 cookie；到期即删除对应服务端状态。"""
+        if len(token) != 43 or not all(c.isascii() and (c.isalnum() or c in "-_") for c in token):
+            return None
+        key = self._digest(token)
+        session = self.sessions.get(key)
+        if session is not None and session.expires_at <= time.monotonic():
+            del self.sessions[key]
+            return None
+        return session
+
+    def revoke(self, token: str) -> None:
+        """退出同时撤销服务端状态，复制过的 cookie 也立即失效。"""
+        self.sessions.pop(self._digest(token), None)

dwy_auth/contracts.py

@@ -0,0 +1,61 @@
+"""认证方式和 transport 共用的最小身份合同，不携带业务用户资料。"""
+
+from dataclasses import dataclass, field
+from typing import Protocol
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+@dataclass(frozen=True)
+class VerifiedIdentity:
+    """认证结果，subject 为不透明主体；proof 字段仅供 runtime 在五分钟内核销。
+
+    自定义 SessionBackend 可继续使用前三字段；HTTP 不接收客户端自报的证明对象。
+    密码/绑定变更后旧证明失效，业务资料不进入本合同。
+    """
+
+    app_id: str
+    subject: str
+    method: str
+    authenticated_at: int = 0
+    credential_version: str | None = field(default=None, repr=False)
+    proof_id: UUID | None = field(default=None, repr=False)
+    purpose: str = "login"
+
+
+@dataclass(frozen=True)
+class AuthPrincipal:
+    """已验证的会话身份；设备不是账号标识，Web transport 可以不提供设备。"""
+
+    app_id: str
+    subject: str
+    session_id: UUID
+    method: str
+    device_id: UUID | None
+
+
+@dataclass(frozen=True)
+class SessionTokens:
+    """transport 自行选择 JSON 或 Cookie；repr 永远不包含凭据。"""
+
+    access_token: str = field(repr=False)
+    refresh_token: str = field(repr=False)
+    expires_in: int
+    principal: AuthPrincipal
+
+
+class SessionBackend(Protocol):
+    """可替换会话实现；传入 db 的操作必须加入宿主事务，不得自行提交或关闭。"""
+
+    async def issue(
+        self, identity: VerifiedIdentity, *, device_id: UUID | None, db: AsyncSession
+    ) -> SessionTokens: ...
+
+    async def verify(self, token: str) -> AuthPrincipal: ...
+
+    async def refresh(self, refresh_token: str) -> SessionTokens: ...
+
+    async def revoke(self, principal: AuthPrincipal) -> None: ...
+
+    async def revoke_subject(self, subject: str, *, db: AsyncSession) -> None: ...