From 982ef655305dc63518444f522e24c0d50d368168 Mon Sep 17 00:00:00 2001
From: bot_dev1 <bot_dev1@xayunmei.com>
Date: Wed, 5 Aug 2026 02:08:37 +0000
Subject: [PATCH] =?UTF-8?q?docs(#150):=20web/auth=20README=EF=BC=88?=
 =?UTF-8?q?=E7=99=BB=E5=BD=95=E9=A1=B5=E4=B8=8E=E6=9C=AC=E5=9C=B0=E8=B4=A6?=
 =?UTF-8?q?=E5=8F=B7=E4=BC=9A=E8=AF=9D=E7=AE=A1=E7=90=86=E8=AF=B4=E6=98=8E?=
 =?UTF-8?q?=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 web/auth/README.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 web/auth/README.md

diff --git a/web/auth/README.md b/web/auth/README.md
new file mode 100644
index 0000000..199c875
--- /dev/null
+++ b/web/auth/README.md
@@ -0,0 +1,63 @@
+# web/auth — iAOP 登录页与本地账号会话管理（issue #150 / PRD 8.2）
+
+登录认证是配置台/驾驶舱写操作的入口闸门。未登录用户不可访问写操作（PRD 8.2）。
+
+## 组成
+
+**前端（纯静态）**
+- `login.html` / `auth.css` / `auth.js` — 深色主题登录页，对接 `/auth/login`、`/auth/me`；
+  `auth.js` 导出 `IAOP_AUTH.requireLoginElseRedirect()` 供其它页面做路由守卫。
+
+**后端（core/auth，纯标准库）**
+- `users.py` — `User` 模型 + `PBKDF2-HMAC-SHA256` 密码哈希（盐 16B / 迭代 200000，
+  OWASP 2023 量级）+ `UserStore`（内存，可换 PG 后端）。恒定时间校验防时序侧信道。
+- `session.py` — HMAC 签名会话 token（`<uid>.<expire>.<sig>`），HttpOnly cookie `iaop_session`。
+- `postgres_users_schema.py` — PostgreSQL `users` 表 DDL（`BIGSERIAL id` / `username UNIQUE` /
+  `password_hash` / `role CHECK(readonly|engineer|admin)` / `active` / 时间戳），对齐 #30。
+- `auth_api.py` — 认证 HTTP 端点（`POST /auth/login` `POST /auth/logout` `GET /auth/me`）+
+  `require_auth` / `can_write` 守卫（未登录 401、readonly 写 403，PRD 8.2）。
+- `tests/test_auth.py` — 单元测试。
+
+## 跑测试
+
+```bash
+# 仓库根目录
+python -m pytest core/auth/tests/test_auth.py -v
+# 或无 pytest：
+python core/auth/tests/test_auth.py
+```
+
+## 冒烟（认证服务）
+
+```bash
+python -m core.auth.auth_api
+# → iAOP AuthAPI on http://127.0.0.1:8088（初始管理员 admin / change-me-now，生产必须改密）
+```
+
+```bash
+curl -s -X POST http://127.0.0.1:8088/auth/login -H 'Content-Type: application/json' \
+  -d '{"username":"admin","password":"change-me-now"}' -c /tmp/c.txt
+curl -s http://127.0.0.1:8088/auth/me -b /tmp/c.txt
+```
+
+## 前端冒烟
+
+```bash
+cd web/auth && python -m http.server 8090
+# 浏览器开 http://localhost:8090/login.html（AUTH_BASE 指向 :8088 见 auth.js）
+```
+
+## 角色（对齐 core/template-console/rbac.py）
+
+| 角色 | 读 | 配置写 | 发布/回滚 |
+|------|----|--------|----------|
+| readonly | ✓ | ✗ | ✗ |
+| engineer | ✓ | ✓ | ✗ |
+| admin    | ✓ | ✓ | ✓ |
+
+## 安全
+
+- 永不存明文密码；存储 `pbkdf2_sha256$<iter>$<salt-b64>$<hash-b64>`。
+- `authenticate` 失败不区分"用户不存在/密码错"，防用户名枚举。
+- token HMAC 恒定时间校验；cookie `HttpOnly; SameSite=Lax`。
+- 生产必须设置 `IAOP_AUTH_SECRET` 环境变量（多副本共享）并改初始管理员密码。