@@ -0,0 +1,109 @@
+# 后端安全不变量（Security Invariants）
+
+本文档登记后端代码中**不可变更的安全保护点**。
+每一条不变量都对应 `SecurityInvariantsTests` 中的回归测试，CI 自动跑。
+
+## 维护规则
+
+修改本文件涉及的代码时，**必须同时更新对应测试**。
+删除任何一条不变量需在 PR 描述写明理由并 CC superadmin review。
+
+每条不变量包含四个字段：
+- **保护点**：被这条规则保护的代码位置（file path + 类/方法名）
+- **测试**：验证这条规则的测试方法名（直接 `./mvnw test -Dtest=SecurityInvariantsTests` 跑得到）
+- **为什么**：规则存在的理由——攻击场景 / 历史 / 业务约束
+- **历史**：规则诞生时间与背景（commit、CR 报告、incident）
+
+## 编号约定
+
+`INV-XXX` 三位流水号，永不复用。删除条目时保留编号 + 标 `(retired)`，
+新条目用下一个未占用号。这样 PR diff / 历史回溯永远稳定。
+
+---
+
+## INV-001 · superadmin 角色不能通过 API 授予
+
+- **保护点**：
+  - `usercenter/service/UserCenterService#updateAuthorization`
+  - `events/controller/AdminUserController#setAdminRole`
+- **测试**：
+  - `SecurityInvariantsTests#admin不能通过PUT_users_authorization给自己加superadmin角色`
+  - `SecurityInvariantsTests#admin不能通过PUT_users_authorization给他人加superadmin角色`
+  - `SecurityInvariantsTests#admin可以通过PUT_users_authorization设置非superadmin的合法角色`（反向 happy path）
+- **为什么**：superadmin 是 admin 的上位角色（能管理其他 admin 的角色绑定）。
+  如果 admin 能通过任何 API 拿到 superadmin，整套 RBAC 边界失效。
+  唯一合法的 superadmin 授予路径：DB 直接 `UPDATE user_accounts SET roles = ...`。
+- **历史**：2026-05-07 三方 CR 的 attack chain A 起点（详见内部报告）。
+
+---
+
+## INV-002 · 不允许往他人的 chat 历史写消息
+
+- **保护点**：`chat/controller/ChatHistoryController#save`
+- **测试**：
+  - `SecurityInvariantsTests#匿名调用不能往他人chatId写消息`
+  - `SecurityInvariantsTests#登录用户不能往他人chatId写消息`
+  - `SecurityInvariantsTests#chat的owner可以继续写自己的chat历史`（反向）
+  - `SecurityInvariantsTests#匿名chat允许匿名继续写`（反向，保留匿名 → 登录迁移语义）
+- **为什么**：chat 历史既是用户隐私也是 AI 训练 / 行为审计的输入。
+  如果攻击者拿到他人 chatId（前端 log / share URL leak），匿名 POST 即可往
+  victim 历史里塞污染消息。COALESCE 语义不会改 ownerId，但 INSERT INTO
+  "Message" 已经发生——这是数据完整性 + 内容污染。
+  匿名 chat 允许继续匿名写，保留"匿名 → 登录迁移"业务语义；
+  一旦 chat 已绑定 ownerId，则只允许 owner 本人写。
+- **历史**：2026-05-07 三方 CR 的 attack chain B 起点。
+
+---
+
+## INV-003 · 密码哈希必须用 bcrypt（legacy SHA-256 仅兼容路径）
+
+- **保护点**：
+  - `usercenter/service/PasswordService#hash`（始终输出 bcrypt）
+  - `usercenter/service/PasswordService#matches`（dual-mode：bcrypt + legacy SHA-256）
+  - `usercenter/service/AuthService#login`（lazy upgrade：登录成功后把 legacy hash 就地升级）
+  - `src/main/resources/schema.sql`（seed bcrypt 哈希）
+  - `docker/init-db/init.sql`（seed bcrypt 哈希）
+  - `src/test/resources/test-schema.sql`（seed bcrypt 哈希）
+- **测试**：
+  - `PasswordServiceTests#hashGeneratesBcryptOutput`
+  - `PasswordServiceTests#hashSamePasswordTwiceProducesDifferentOutput`（salt 随机性证据）
+  - `PasswordServiceTests#matchesAcceptsLegacySha256Hash`（向后兼容）
+  - `PasswordServiceTests#isLegacyHashIdentifiesPlainSha256`
+  - `SecurityInvariantsTests#seed账号能用明文密码登录验证bcrypt端到端`
+- **为什么**：原实现用单轮 SHA-256，无 salt 无 cost factor。
+  DB 一旦泄露（备份、容器逃逸、pgAdmin 误导出），所有口令账号瞬间失守——
+  GPU 一秒可跑数十亿哈希，rainbow table 已收录绝大部分常见明文。
+  迁移策略：新写入一律 bcrypt；老 SHA-256 hash 通过 dual-mode matches 让用户能登录，
+  登录成功时由 AuthService 就地升级。所有 seed 同步重写为 bcrypt 形式。
+- **历史**：2026-05-07 三方 CR 的 attack chain B 加固项。
+
+---
+
+## INV-004 · user_follows 表必须随 schema 一并建立
+
+- **保护点**：
+  - `src/main/resources/schema.sql`（user_follows DDL + idx_user_follows_followee 索引）
+  - `docker/init-db/init.sql`（同步 DDL）
+  - `src/test/resources/test-schema.sql`（测试同步）
+  - `usercenter/follows/FollowService`（SQL 调用方）
+- **测试**：`SecurityInvariantsTests#user_follows表存在且follow_unfollow能闭环`
+- **为什么**：FollowService 引用的 `user_follows(follower_id, followee_id, created_at)`
+  之前在 schema.sql 与 init.sql 中都未定义，全新部署或新 Neon 数据库一访问
+  `/api/user-center/follows/...` 就 `relation does not exist` 报 500。
+  这是 issue #25 之外的额外 schema drift。CI 测试存在表 + follow/unfollow 闭环
+  作为长期回归探测器。
+- **历史**：2026-05-07 三方 CR 发现的 schema drift（与 issue #25 类同）。
+
+---
+
+## INV-005 · docker-compose 不允许暴露公网 PG 端口或保留弱密码默认值
+
+- **保护点**：`docker-compose.yml`（postgres 服务 ports 段、所有密码字段）
+- **测试**：
+  - `SecurityInvariantsTests#docker_compose里postgres端口必须绑127_0_0_1`
+  - `SecurityInvariantsTests#docker_compose里不允许出现change_me弱密码默认值`
+- **为什么**：PostgreSQL 主端口暴露公网 = 攻击面 +1（弱密码扫库 / 0day / TLS 退化）。
+  pgAdmin 走 docker internal network 即可访问，不需要 host port mapping。
+  `change_me` fallback 让部署者忘配 env 时仍能起服务，但起来的就是弱密码后台
+  ——必须用 `${VAR:?...}` 形式强制部署期校验。
+- **历史**：2026-05-07 三方 CR 加固项（端口部分历史已修，本次加测试 + 收紧密码默认值）。
@@ -12,7 +12,7 @@ services:
       # 数据库连接（使用 PG* 变量，与 application.properties 保持一致）
       SPRING_DATASOURCE_URL: ${SPRING_DATASOURCE_URL:-jdbc:postgresql://postgres:5432/involution_hell}
       PGUSER: ${PGUSER:-involution}
-      PGPASSWORD: ${PGPASSWORD:-change_me}
+      PGPASSWORD: ${PGPASSWORD:?PGPASSWORD must be set in .env}
       SPRING_SQL_INIT_MODE: ${SPRING_SQL_INIT_MODE:-always}
       # GitHub OAuth2
       AUTH_GITHUB_ID: ${AUTH_GITHUB_ID:-}
@@ -67,11 +67,14 @@ services:
     environment:
       POSTGRES_DB: ${POSTGRES_DB:-involution_hell}
       POSTGRES_USER: ${POSTGRES_USER:-involution}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-change_me}
-    # 只 bind 到 loopback，不再暴露公网。
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env}
+    # 只 bind 到 loopback，不再暴露公网（INV-005）。
     # Spring Boot / pgAdmin / 自动备份容器都在同 docker network，走容器名 postgres:5432 即可。
     # 历史上是 "5432:5432" 让 Vercel build 脚本远程查 doc_contributors 生成排行榜，
     # 现已改走后端 /api/public/leaderboard，DB 不再需要对外开放。
+    #
+    # 注意：禁止把这一行改回 "5432:5432" 或 "0.0.0.0:5432:5432"。
+    # 攻击面分析见 SECURITY.md / INV-005。
     ports:
       - "127.0.0.1:5432:5432"
     volumes:
@@ -95,7 +98,7 @@ services:
     restart: unless-stopped
     environment:
       PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL:-admin@involutionhell.com}
-      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD:-change_me}
+      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD:?PGADMIN_PASSWORD must be set in .env}
       # pgAdmin 保持 SERVER_MODE=False（desktop / single-user，无登录页）——
       # 关键前提：**外层 Caddy 做 forward_auth**，只有带合法 admin satoken
       # cookie 的请求才被代理到这里。直接对公网暴露 8082 绝对不行。
@@ -138,7 +141,7 @@ services:
       POSTGRES_HOST: postgres
       POSTGRES_DB: ${POSTGRES_DB:-involution_hell}
       POSTGRES_USER: ${POSTGRES_USER:-involution}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-change_me}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env}
       # -Fc 产出 custom 格式（.dump），pgAdmin 右键 Restore 直接一键恢复；
       # 镜像包装脚本默认会 gzip，这里必须显式设 BACKUP_SUFFIX=.dump 且不加 gzip
       # 选项，让镜像按 custom 格式直接落盘。
 
@@ -15,12 +15,23 @@ CREATE TABLE IF NOT EXISTS user_accounts (
 -- admin / Admin@123456
 -- alice / Alice@123456
 -- auditor / Audit@123456
+-- 哈希格式：bcrypt(cost=10) —— INV-003 起点
 INSERT INTO user_accounts (username, password_hash, display_name, enabled, roles, permissions)
-VALUES ('admin',   'ad89b64d66caa8e30e5d5ce4a9763f4ecc205814c412175f3e2c50027471426d', 'Admin',   TRUE, 'admin',   'user:profile:read,user:center:read,user:center:manage'),
-       ('alice',   'b02bb998ecc1616148b9b4ba0405dbd4c224acd1bac059d59f0a07b3b1a68400', 'Alice',   TRUE, 'user',    'user:profile:read'),
-       ('auditor', 'ccabaaba054fb98905b5b9ee47174f57cb6088e04b1526f08b872dc06eaa6bb9', 'Auditor', TRUE, 'auditor', 'user:profile:read,user:center:read')
+VALUES ('admin',   '$2b$10$Bfnw8v.BsXeZVPbre94sJeokgEfKuCLsdH7ckJxzxn5nxirHJHmP.', 'Admin',   TRUE, 'admin',   'user:profile:read,user:center:read,user:center:manage'),
+       ('alice',   '$2b$10$BmtVOmPK8Os/xreOTImsdec1fAA8Y9iTm1D823swYucSI2NDFdk.q', 'Alice',   TRUE, 'user',    'user:profile:read'),
+       ('auditor', '$2b$10$/1OfzhrA6CITrjJsDbzk.uMLq6cHa/iOP./wL2BAPo9t7QRq7Ca5W', 'Auditor', TRUE, 'auditor', 'user:profile:read,user:center:read')
 ON CONFLICT (username) DO NOTHING;
 
+-- 关注关系（user_follows）—— 与 schema.sql 保持一致
+CREATE TABLE IF NOT EXISTS user_follows (
+    follower_id BIGINT      NOT NULL REFERENCES user_accounts(id) ON DELETE CASCADE,
+    followee_id BIGINT      NOT NULL REFERENCES user_accounts(id) ON DELETE CASCADE,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (follower_id, followee_id)
+);
+CREATE INDEX IF NOT EXISTS idx_user_follows_followee
+    ON user_follows(followee_id, created_at DESC);
+
 -- Prisma tables (frontend/prisma/schema.prisma)
 
 -- users table
 
@@ -109,6 +109,15 @@
 			<version>1.39.0</version>
 		</dependency>
 
+		<!-- spring-security-crypto: 单独 artifact，仅提供 BCryptPasswordEncoder 等
+		     PasswordEncoder 实现，不会引入完整 Spring Security 的 Filter chain。
+		     PasswordService 用它做 bcrypt 哈希（替代之前的裸 SHA-256），同时保留
+		     legacy SHA-256 dual-mode 兼容老用户登录（见 INV-003 / SECURITY.md）。 -->
+		<dependency>
+			<groupId>org.springframework.security</groupId>
+			<artifactId>spring-security-crypto</artifactId>
+		</dependency>
+
 		<!-- Google Analytics Data API (GA4) -->
 		<dependency>
 			<groupId>com.google.analytics</groupId>
 
@@ -3,7 +3,10 @@
 import cn.dev33.satoken.stp.StpUtil;
 import com.involutionhell.backend.chat.dto.ChatTurnSaveRequest;
 import com.involutionhell.backend.chat.repository.ChatHistoryRepository;
+import com.involutionhell.backend.chat.repository.ChatOwner;
 import com.involutionhell.backend.common.api.ApiResponse;
+import com.involutionhell.backend.common.error.AccessDeniedBusinessException;
+import java.util.Optional;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -12,13 +15,16 @@
 /**
  * /api/chat/sessions/save —— 保存一次 AI 对话回合（替代前端原 Prisma 直连）。
  *
- * 鉴权：匿名允许（SaTokenConfigure 里放行本路径）。原 Prisma 实现就是匿名也写，
- * chat.userId 允许 NULL；保持语义一致，避免前端切流量时未登录用户聊天历史丢失。
- * 如果登录了，用 sa-token 取 userId 关联；没登录就 NULL。
+ * 鉴权策略（INV-002）：匿名 + 登录都允许，但写入前必须做归属校验：
+ *   - chat 不存在：允许任意调用方创建（首次写入）
+ *   - chat 存在且 ownerId == null：允许匿名继续写、登录用户首次"接管"为 owner
+ *   - chat 存在且 ownerId != null：调用方必须登录且 userId 与 ownerId 完全匹配
  *
- * 为什么单独放一个 controller 而不是塞进 OpenAiController：OpenAiController 管
- * 流式代理，这里管持久化，职责不同；而且这条路径要对匿名开放，和 OpenAI 代理
- * 的登录要求不一致，拆开配 SaToken 拦截规则更清晰。
+ * 攻击场景：攻击者拿到他人 chatId（前端 log / share URL leak），匿名 POST
+ * 即可往 victim 历史里塞消息。COALESCE 语义不会改 ownerId，但 INSERT INTO
+ * "Message" 已经发生——这是数据完整性 + 内容污染问题。
+ *
+ * 见 SecurityInvariantsTests INV-002 三条断言。
  */
 @RestController
 @RequestMapping("/api/chat/sessions")
@@ -38,11 +44,22 @@ public ApiResponse<Void> save(@RequestBody ChatTurnSaveRequest req) {
 
         // StpUtil.isLogin() 对匿名请求返回 false 而不是抛异常——配合 SaToken
         // 拦截器在 SaTokenConfigure 里 notMatch 放行本路径，才能真正对匿名生效。
-        Long userId = StpUtil.isLogin() ? StpUtil.getLoginIdAsLong() : null;
+        Long callerUserId = StpUtil.isLogin() ? StpUtil.getLoginIdAsLong() : null;
+
+        // INV-002：归属校验。已绑定 owner 的 chat 必须由 owner 本人写。
+        // 这一步必须在 saveTurn 之前——saveTurn 内部用 ON CONFLICT upsert，
+        // 一旦执行就会插入 Message 行，事后回滚得靠 @Transactional，宁可前置拦截。
+        Optional<ChatOwner> existing = chatHistoryRepository.lookupOwner(req.chatId());
+        if (existing.isPresent() && !existing.get().isAnonymous()) {
+            Long ownerId = existing.get().ownerId();
+            if (callerUserId == null || !callerUserId.equals(ownerId)) {
+                throw new AccessDeniedBusinessException("不允许写入他人的 chat 历史");
+            }
+        }
 
         chatHistoryRepository.saveTurn(
                 req.chatId(),
-                userId,
+                callerUserId,
                 req.userMessage(),
                 req.assistantMessage());
 
 
@@ -1,5 +1,7 @@
 package com.involutionhell.backend.chat.repository;
 
+import java.util.Optional;
+
 /**
  * AI 对话历史持久化接口。
  *
@@ -10,6 +12,16 @@
  */
 public interface ChatHistoryRepository {
 
+    /**
+     * 查询 chatId 对应行的归属。
+     *   - empty：chat 不存在
+     *   - present 且 ownerId == null：匿名 chat（保留给"匿名 → 登录迁移"语义）
+     *   - present 且 ownerId != null：已绑定到具体 user
+     *
+     * 用于 Controller 在写入前做 INV-002 归属校验。
+     */
+    Optional<ChatOwner> lookupOwner(String chatId);
+
     /**
      * 原子地持久化一个聊天回合：
      *   1. chat 不存在则创建、存在则刷新 updatedAt 和 userId（匿名 → 登录迁移场景）
 
@@ -0,0 +1,17 @@
+package com.involutionhell.backend.chat.repository;
+
+/**
+ * Chat 行的归属信息——只承载本系统真正在乎的两件事：是否存在 + owner 是谁。
+ *
+ * 为什么不直接 Optional<Long> 表示 owner：会丢掉"chat 不存在"和"chat 存在但匿名"
+ * 这两种状态的差别。匿名 chat 允许继续匿名写；他人 chat 必须拒绝。两态合并会让
+ * controller 的归属校验逻辑写不清楚。
+ *
+ * @param ownerId user_accounts.id；匿名 chat 为 null
+ */
+public record ChatOwner(Long ownerId) {
+
+    public boolean isAnonymous() {
+        return ownerId == null;
+    }
+}
@@ -1,6 +1,8 @@
 package com.involutionhell.backend.chat.repository;
 
 import java.sql.Types;
+import java.util.List;
+import java.util.Optional;
 import java.util.UUID;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.stereotype.Repository;
@@ -22,6 +24,26 @@ public JdbcChatHistoryRepository(JdbcTemplate jdbc) {
         this.jdbc = jdbc;
     }
 
+    /**
+     * 查询 chatId 的归属信息。详细语义见接口文档。
+     *
+     * 实现要点：rs.getLong + rs.wasNull 才能区分"列值就是 0"和"列值是 NULL"，
+     * 直接 getObject 在 H2 / Postgres 之间行为不一致。
+     */
+    @Override
+    public Optional<ChatOwner> lookupOwner(String chatId) {
+        List<ChatOwner> result = jdbc.query(
+                """
+                SELECT "userId" FROM "Chat" WHERE id = ?
+                """,
+                (rs, rn) -> {
+                    long uid = rs.getLong("userId");
+                    return new ChatOwner(rs.wasNull() ? null : uid);
+                },
+                chatId);
+        return result.stream().findFirst();
+    }
+
     /**
      * 为什么用 ON CONFLICT 做 upsert 而不是先 select 再 insert：
      *   1. 单次 round-trip，少一次 SQL 调用
 
@@ -0,0 +1,19 @@
+package com.involutionhell.backend.common.error;
+
+/**
+ * 业务规则触发的"访问被拒"——不是 Sa-Token 缺权限/缺角色，而是业务对象归属
+ * 不匹配（例如试图写入他人的 chat 历史、修改他人的资源）。
+ *
+ * 用独立类型而不是复用 NotPermissionException：
+ *   1. NotPermissionException 的 message 模板由 GlobalExceptionHandler 强制成
+ *      "拒绝访问: 缺少权限 [...]"，业务语义会被吞
+ *   2. 单独类型让调用方一眼看出是"业务归属"问题而非"角色权限"问题
+ *
+ * GlobalExceptionHandler 把它转成 403 + 自定义 message。
+ */
+public class AccessDeniedBusinessException extends RuntimeException {
+
+    public AccessDeniedBusinessException(String message) {
+        super(message);
+    }
+}
@@ -80,6 +80,16 @@ public ResponseEntity<ApiResponse<Void>> handleNotRoleException(NotRoleException
                 .body(ApiResponse.fail("拒绝访问: 缺少角色 [" + e.getRole() + "]"));
     }
 
+    /**
+     * 业务归属访问被拒——例如写入他人的 chat 历史、修改他人的资源。
+     * 与 Sa-Token 缺权限/缺角色不同，message 由抛出方决定，403 状态码。
+     */
+    @ExceptionHandler(AccessDeniedBusinessException.class)
+    public ResponseEntity<ApiResponse<Void>> handleAccessDeniedBusiness(AccessDeniedBusinessException e) {
+        return ResponseEntity.status(HttpStatus.FORBIDDEN)
+                .body(ApiResponse.fail(e.getMessage()));
+    }
+
     // ==========================================
     // 业务与通用异常拦截
     // ==========================================