Richie8430/AdaptiveMemoryAnalysis

# MemShield Auth 一个生产级的 OAuth 2.0 认证系统，支持 Google 和 GitHub 社交登录、邮箱/密码降级登录、JWT 会话管理以及账号关联。 ``` Frontend: React + Vite + Tailwind CSS + Lucide React Backend: Flask + SQLAlchemy + JWT Extended Database: PostgreSQL ``` ## ✦ 功能特性 ### 核心功能 (必选) - **OAuth 2.0** — 具有品牌准确按钮的 Google 和 GitHub 社交登录 - **邮箱/密码** — 带有服务端和客户端验证的注册与登录 - **JWT 会话** — 短期访问 Token (15 分钟) + 长期刷新 Token (7 天) - **CSRF 防护** — 在前端和后端均生成并验证 `state` 参数 - **PostgreSQL** — 存储包含 `email`、`name`、`profile_picture`、`oauth_provider_id` 的用户信息 - **基于环境变量的密钥** — 所有 Client ID/Secret 均通过 `python-dotenv` 从 `.env` 文件加载 - **加载状态** — OAuth 按钮在重定向期间显示加载动画；带有动画效果的回调屏幕 - **服务条款** — 包含 ToS 和隐私政策链接的免责声明 ### 附加功能 (额外) - **刷新 Token 流程** — Axios 拦截器可静默自动刷新过期的访问 Token - **账号关联** — 来自不同提供商的相同邮箱将合并为一个用户记录 (无重复) - **密码强度指示器** — 注册期间的实时视觉反馈 - **时间安全的登录** — 虚假的 bcrypt 调用可防止通过响应时间进行邮箱枚举 - **输入净化** — 客户端和服务端验证，并附带清晰、具体的错误消息 - **显示/隐藏密码** — 所有密码字段均可切换可见性 - **无障碍表单** — 全面使用 `aria-invalid`、`aria-describedby`、`role="alert"` - **受保护的路由** — 用于认证和未认证页面的 React Router 守卫 - **控制面板** — 登录后展示用户资料和会话状态的页面 - **Docker Compose** — 一键启动本地技术栈 (PostgreSQL + Flask + React) ## ✦ 文件结构 ``` auth-project/ ├── frontend/ # React + Vite application │ ├── src/ │ │ ├── components/ │ │ │ ├── OAuthButton.jsx # Google + GitHub brand buttons │ │ │ ├── LoginForm.jsx # Email/password login with validation │ │ │ └── RegisterForm.jsx # Registration with password strength meter │ │ ├── hooks/ │ │ │ └── useAuth.jsx # Auth context + token persistence │ │ ├── pages/ │ │ │ ├── AuthPage.jsx # Main auth card (OAuth + email toggle) │ │ │ ├── OAuthCallback.jsx # Handles OAuth redirect back │ │ │ └── Dashboard.jsx # Protected post-login page │ │ ├── utils/ │ │ │ ├── api.js # Axios instance + auto-refresh interceptor │ │ │ ├── oauth.js # State generation + validation + redirect │ │ │ └── validation.js # Client-side form validation rules │ │ ├── App.jsx # Router + AuthProvider + route guards │ │ ├── main.jsx │ │ └── index.css # Tailwind + custom component classes │ ├── index.html │ ├── vite.config.js │ ├── tailwind.config.js │ └── package.json │ ├── backend/ # Flask Python application │ ├── models/ │ │ └── user.py # SQLAlchemy User model + bcrypt helpers │ ├── routes/ │ │ └── auth.py # All auth endpoints (OAuth + email + JWT) │ ├── utils/ │ │ └── oauth.py # Provider URL builders + token exchange │ ├── migrations/ │ │ └── schema.sql # Reference PostgreSQL schema │ ├── __init__.py # Flask app factory │ └── requirements.txt │ ├── run.py # Flask entry point ├── .env.example # Environment variable template ├── docker-compose.yml # Full local stack ├── Dockerfile.backend └── README.md ``` ## ✦ 快速开始 ### 选项 A: Docker Compose (推荐) ``` # 1. Clone 并进入目录 git clone && cd auth-project # 2. 复制并填写环境文件 cp .env.example .env # 编辑 .env — 添加你的 Google 和 GitHub OAuth 凭据 # 3. 启动一切 docker-compose up --build # App 运行于： # Frontend → http://localhost:3000 # Backend → http://localhost:5000 ``` ### 选项 B: 手动设置 **数据库** ``` createdb memshield_auth # 或者使用 docker：docker run -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16 ``` **后端** ``` cd auth-project python -m venv venv && source venv/bin/activate # Windows: venv\Scripts\activate pip install -r backend/requirements.txt cp .env.example .env # Fill in your credentials python run.py # Flask 运行在 http://localhost:5000 ``` **前端** ``` cd frontend npm install npm run dev # Vite 运行在 http://localhost:3000 ``` ## ✦ OAuth 应用设置 ### Google 1. 前往 [Google Cloud Console → 凭据](https://console.cloud.google.com/apis/credentials) 2. 创建 **OAuth 2.0 Client ID** → 应用类型：**Web application** 3. 添加已授权的重定向 URI：`http://localhost:5000/api/auth/google/callback` 4. 复制 Client ID 和 Secret 到 `.env` 文件中 ### GitHub 1. 前往 [GitHub 开发者设置](https://github.com/settings/developers) → **OAuth Apps** → **New OAuth App** 2. 设置 Authorization callback URL：`http://localhost:5000/api/auth/github/callback` 3. 复制 Client ID 并生成 + 复制 Client Secret 到 `.env` 文件中 ## ✦ API 参考 | 方法 | Endpoint | 认证 | 描述 | |--------|----------|------|-------------| | `GET` | `/api/auth/google` | — | 重定向至 Google 授权页 | | `GET` | `/api/auth/google/callback` | — | 处理 Google 重定向 | | `GET` | `/api/auth/github` | — | 重定向至 GitHub 授权页 | | `GET` | `/api/auth/github/callback` | — | 处理 GitHub 重定向 | | `POST` | `/api/auth/register` | — | 邮箱/密码注册 | | `POST` | `/api/auth/login` | — | 邮箱/密码登录 | | `POST` | `/api/auth/refresh` | Refresh JWT | 颁发新的访问 Token | | `POST` | `/api/auth/logout` | Access JWT | 登出 (客户端清除 Token) | | `GET` | `/api/auth/me` | Access JWT | 当前用户资料 | ## ✦ 数据库结构 ``` CREATE TABLE users ( id VARCHAR(36) PRIMARY KEY, -- UUID email VARCHAR(254) NOT NULL UNIQUE, name VARCHAR(255) NOT NULL, profile_picture TEXT, -- OAuth avatar URL password_hash VARCHAR(255), -- NULL for OAuth-only oauth_provider VARCHAR(32), -- 'google'|'github'|'email' oauth_provider_id VARCHAR(255), -- Provider UID is_active BOOLEAN NOT NULL DEFAULT TRUE, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), last_login_at TIMESTAMPTZ, CONSTRAINT uq_oauth_provider_user UNIQUE (oauth_provider, oauth_provider_id) ); ``` ## ✦ 安全说明 | 关注点 | 实现方式 | |---------|---------------| | CSRF | `state` 参数：使用 `crypto.getRandomValues()` (前端) 和 `secrets.token_urlsafe()` (后端) 生成，存储在 `sessionStorage` 中并在回调时进行验证 | | 密码存储 | 使用成本因子为 12 的 `bcrypt` | | Token 有效期 | Access Token: 15 分钟 · Refresh Token: 7 天 | | 邮箱枚举 | 时间安全的登录路径 (针对未知邮箱执行虚假的 bcrypt 调用) | | XSS | React 会对所有渲染值进行转义；JWT 存储在内存中 (而非 `localStorage`) | | 账号关联 | 来自不同提供商的同邮箱账号会自动合并 | | 密钥 | 所有凭证均在 `.env` 中，绝不提交 | ### 生产环境强化清单 - [ ] 添加 **JWT 黑名单** (Redis) 用于在登出时撤销 Refresh Token - [ ] 在 login/register/refresh 等 endpoint 添加 **速率限制** (`flask-limiter`) - [ ] 在 OAuth 流程中使用 **PKCE** 代替普通的 `state` - [ ] 仅通过 **HTTPS** 提供服务；如果切换为基于 cookie 的 token，请设置 `Secure` 和 `HttpOnly` cookie 标志 - [ ] 添加 **CORS** 源白名单 (已配置，请为生产域名进行更新) - [ ] 将进程内的 OAuth 状态存储替换为 **Redis** (TTL: 5 分钟) - [ ] 为邮箱/密码注册添加 **邮箱验证** 流程 ## ✦ 技术栈 | 层级 | 技术 | |-------|-----------| | 前端框架 | React 18 + Vite 5 | | 样式 | Tailwind CSS 3 | | 图标 | Lucide React | | HTTP 客户端 | Axios (带有用于静默刷新的拦截器) | | 路由 | React Router v6 | | 后端框架 | Flask 3 | | ORM | Flask-SQLAlchemy | | 认证 | Flask-JWT-Extended | | 密码哈希 | bcrypt | | 数据库 | PostgreSQL 16 | | 容器化 | Docker + Docker Compose | *为 Group 13 · MemShield · University of Dodoma · 2025/2026 构建*

标签：CSRF防护, Docker, Docker Compose, Flask, Flask-JWT-Extended, GitHub登录, Google登录, JWT, Lucide React, OAuth 2.0, PostgreSQL, React, SecList, Session管理, SQLAlchemy, Syscalls, Tailwind CSS, Vite, 内存取证, 刷新令牌, 前端工程化, 后端开发, 安全防御评估, 密码强度检测, 数据库, 无障碍访问, 易失性内存分析, 毕业设计, 流量嗅探, 测试用例, 状态管理, 社交登录, 网络安全, 自适应机器学习, 请求拦截, 账号绑定, 路由守卫, 输入校验, 逆向工具, 防御绕过, 隐私保护