feat: harden sessions and track downstream acknowledgements

2026-07-14 14:18:43 +08:00
parent 3d37adcc9f
commit 8c03663f24
43 changed files with 1733 additions and 150 deletions
@@ -278,6 +278,8 @@
 - 已实现多 Gateway 恢复抢占协调第一版：恢复锁从单纯实例名升级为 Redis token 租约，状态记录 `lockOwner/lockExpiresAt`；恢复完成时必须通过 Lua 原子校验锁 token，只有持锁实例才能写入最终恢复状态并释放锁，避免旧实例超时后误删新实例锁或覆盖新实例恢复结果；运营端详情/列表可查看锁持有实例。
 - 已实现长短信分片审计第一版：Gateway `SubmitResult` 回传真实 `segments[]`，包含 `segmentTotal/segmentIndex/sequenceId/gatewayMessageId/submitStatus/submittedAt`；NestJS 写入 Prisma/PostgreSQL `SmsMessageSegmentAudit`，回执按 `gatewayMessageId` 回填分片回执状态，补偿归因可记录 `compensationType`；运营端短信记录详情可查看真实分片提交、回执和补偿审计。
 - 下游投递重试已改为指数退避第一版：首次失败后按基础间隔重试，随后按 2 倍递增，并受最大退避上限约束，避免客户长时间离线时平台每分钟机械重试。
+- 下游状态必须以客户确认作为终态：Gateway `SendPkt` 成功后只能写 `awaiting_ack`，仅收到匹配连接、`Sequence_Id`、`Msg_Id` 且 `CMPP_DELIVER_RESP.Result=0` 后才能写 `delivered`；超时、非零 Result 和历史未留存 ACK 的记录分别按未确认、拒绝或历史未确认展示，不能再把 TCP 写出冒充客户已收到。
+- 企业应用必须分别提供“回执自动重试投递”和“上行短信自动重试投递”开关，默认开启。开关按投递创建时快照保存；关闭只阻止已经写出但未获 ACK/被拒绝后的自动重发，不阻止离线队列在客户首次上线时完成首次投递。手工重投不受开关限制，但必须提示重复业务处理风险并二次确认。
 - 已实现客户侧最终 Deliver 推送的第一版能力：Gateway 在下游 Submit 被接受后记录 messageId 到客户连接的内存映射；NestJS 收到最终 receipt/uplink 并入库后调用 Gateway `/downstream/receipt`、`/downstream/uplink`，Gateway 向仍在线的客户 CMPP 连接下发 Deliver Receipt 或普通 Deliver。
 - 已实现客户侧 Deliver 持久化第一版能力：NestJS 收到最终 receipt/uplink 后写入 `CmppDownstreamDelivery` 待投递记录；在线推送成功标记 delivered，客户断线或 Gateway 不可达时保留 pending 并记录 retry 信息；客户重新 bind 后 Gateway 按账号拉取 pending 记录补发。
 - 已实现普通上行匹配与人工认领第一版：优先按 messageId 精确匹配；无 messageId 时按接入号匹配应用路由；仍无唯一应用时按手机号和最近下发时间窗口匹配；多候选标记 ambiguous 并写入 `SmsUplinkMatchCandidate` 候选，运营端可人工认领候选应用/下发记录；认领后更新上行记录、保留候选审计，并创建真实客户侧上行 Deliver 投递记录。
@@ -1370,6 +1372,13 @@
 - 两端登录均输入用户名、邮箱或手机号，外加密码和图形验证码。
 - 登录接口必须调用真实 NestJS API，不允许前端静态用户、localStorage mock 或纯前端验证码作为验收依据。
 - 运营端登录仅允许平台管理员；客户端登录仅允许已关联企业的企业管理员。
+- 浏览器认证凭据必须改为服务端随机生成的不可预测会话标识，通过 `HttpOnly`、`SameSite=Lax` Cookie 传输；前端 `localStorage` 只可保留非敏感展示信息，不得保存访问令牌。生产 Cookie 必须启用 `Secure`，因此正式部署本功能前必须先为页面和 API 配置 HTTPS。
+- 会话真实状态保存在 Redis，至少包含用户、入口、`sessionVersion`、创建时间、最后有效操作时间、最近密码认证时间、锁定时间和绝对到期时间。Redis 不可用或记录不存在时必须失败关闭，不得退回纯前端会话。
+- 运营端连续 60 分钟、客户端连续 120 分钟无用户操作后进入安全锁定，提前 5 分钟提醒。锁定后只需验证当前密码即可生成新会话标识并继续使用，不重复输入账号和图形验证码；锁定超过 4 小时必须完整登录。
+- 自动轮询、Dashboard 定时刷新、健康检查和后台标签页请求不得延长无操作期限。前端计时器只负责提醒和锁屏，NestJS/Redis 必须在每次受保护请求前独立执行空闲、锁定和绝对期限判断。
+- 单次登录绝对时长为 12 小时，无论是否持续操作均不得自动续期；到期必须使用账号、密码和图形验证码完整登录。修改密码、禁用/删除用户、角色变化和管理员强制下线必须通过 `sessionVersion` 和 Redis 会话立即撤销现有会话。
+- 用户、权限、企业状态、应用密钥、通道配置、路由、报备状态和资金调整等敏感操作要求最近 30 分钟内验证过当前密码。超时后由后端返回 `RECENT_AUTHENTICATION_REQUIRED`，前端验证当前密码后自动重试原操作；不能只依赖前端弹窗判断。
+- 主动退出、空闲锁定、密码解锁、敏感操作再认证和会话创建均需写真实系统日志；多标签页使用浏览器消息同步锁定、解锁和退出。普通网络错误、400、403 业务拒绝或 5xx 不得被误判为自动退出。

 ### 2. 用户类型和企业关联

@@ -29,6 +29,13 @@ REPO_URL=http://175.27.255.91:3000/hectorzhao/lislgosms.git
 BRANCH=main
 PUBLIC_HTTP_PORT=12026
 API_PORT=3000
+ADMIN_SESSION_IDLE_TIMEOUT_MS=3600000
+CLIENT_SESSION_IDLE_TIMEOUT_MS=7200000
+SESSION_LOCK_RECOVERY_MS=14400000
+SESSION_ABSOLUTE_TIMEOUT_MS=43200000
+SESSION_RECENT_AUTH_MS=1800000
+SESSION_COOKIE_SECURE=true
+CMPP_DOWNSTREAM_ACK_TIMEOUT_SECONDS=30
 GATEWAY_CMPP_ADDR=0.0.0.0:17890
 OBJECT_STORAGE_DRIVER=minio
 OBJECT_STORAGE_LOCAL_ROOT=/var/lib/cmpp-platform/object-storage
@@ -37,6 +44,8 @@ PROD_ADMIN_USERNAME=prod_admin
 PROD_ADMIN_PASSWORD='change-me'
 ```

+安全会话使用 HttpOnly Cookie，正式生产必须先为页面和 `/api` 配置 HTTPS，并保持 `SESSION_COOKIE_SECURE=true`。仅在用户明确授权的 HTTP 生产验证环境中，允许临时显式设置 `SESSION_COOKIE_SECURE=false` 维持验证可用性；该例外必须记录在发布验收中，不能替代正式环境 TLS。
+
 脚本会安装 Node.js、Go、PostgreSQL、Redis、MinIO、Nginx，创建 systemd 服务，执行 Prisma migrate，构建前端/API/Gateway，并创建平台管理员。Node.js、Go 和 MinIO 下载会按服务器架构自动选择 x64/amd64 或 arm64。

 如生产验证服务器临时无法稳定下载 MinIO，可显式传入 `OBJECT_STORAGE_DRIVER=local`，文件会通过真实 API 保存到服务器本地目录 `OBJECT_STORAGE_LOCAL_ROOT`，`cmpp-minio` 服务会跳过安装和启动。该模式只建议用于验证环境；正式生产建议恢复 `OBJECT_STORAGE_DRIVER=minio`。
@@ -3251,6 +3251,12 @@ npm run verify:phase8
 | TC-AUTH-004 | 使用平台管理员或未关联企业的用户登录 `/client/login`。 | 登录失败；不进入客户端。 |
 | TC-AUTH-005 | 同一用户连续输错密码 5 次。 | 第 5 次后用户锁定 24 小时；锁定期内正确密码也被拒绝；系统记录失败次数和锁定时间。 |
 | TC-AUTH-006 | 输入错误或过期图形验证码登录。 | 返回 400 可读错误；必须刷新验证码后重试。 |
+| TC-AUTH-007 | 使用运营管理员登录，确认响应、浏览器存储和 Redis；不携带 Cookie 访问运营 API。 | 登录响应和 localStorage 不含访问令牌；浏览器仅持有 HttpOnly 会话 Cookie；Redis 存在哈希会话记录；无 Cookie 请求返回 `401/SESSION_INVALID`。 |
+| TC-AUTH-008 | 将运营端无操作参数缩短后等待超时，同时保持 Dashboard 自动轮询；再输入当前密码解锁。 | 自动轮询不续期；服务端返回 `401/SESSION_LOCKED`；页面锁屏但无需账号和验证码；当前密码正确时轮换 Session ID，旧标识失效，多标签同步解锁。 |
+| TC-AUTH-009 | 将客户端无操作参数缩短并验证其阈值独立于运营端；锁定后超过锁定恢复期限。 | 客户端使用独立 120 分钟默认阈值；超过 4 小时恢复期限后密码快速解锁被拒绝，必须完整登录。 |
+| TC-AUTH-010 | 持续操作至绝对期限，将默认 12 小时在测试环境缩短验证。 | 用户活动只能刷新空闲时间，不能延长绝对期限；到期返回 `401/SESSION_ABSOLUTE_TIMEOUT`，必须重新输入账号、密码和验证码。 |
+| TC-AUTH-011 | 登录超过最近认证窗口后执行用户禁用、手工充值、通道修改、路由修改或报备状态修改。 | 后端先返回 `403/RECENT_AUTHENTICATION_REQUIRED`，输入当前密码后 30 分钟内自动重试；错误密码不执行原操作，数据库无副作用。 |
+| TC-AUTH-012 | 分别执行主动退出、修改密码、禁用、删除和角色变更，并在另一标签页继续请求。 | Redis 会话删除或 `sessionVersion` 失效；所有标签页同步退出；旧 Cookie 均返回 401；系统日志可查询创建、锁定、解锁、再认证和退出事件。 |
 | TC-USER-ADMIN-001 | 运营端新增平台管理员，填写用户名/登录账号、邮箱或手机号、初始密码。 | 创建成功；用户无 `tenantId`；可登录运营端；写 `user.created` 日志。 |
 | TC-USER-ADMIN-002 | 运营端新增企业管理员但不选择企业。 | 返回 400；不创建用户。 |
 | TC-USER-ADMIN-003 | 运营端新增企业管理员并选择企业。 | 创建成功；用户关联企业；可登录客户端；客户端数据按该企业隔离。 |
@@ -3276,3 +3282,12 @@ npm run verify:phase8
 | TC-MOCK-CLEAN-006 | 运营端短信记录按手机号、状态、日期和内容查询，打开详情。 | 数据来自 `sms_message_records`；详情展示真实 messageId、状态、失败原因；无数据时为空态。 |
 | TC-MOCK-CLEAN-007 | 访问明确标注待开发的彩信菜单。 | 可以显示待开发/空态；不得作为第一版短信真实功能通过依据。 |
 | TC-PHONE-SEGMENT-001 | 生产库存在 50 万级手机号段时打开手机号段库，连续点击下一页、上一页，并按号段、省份、城市或运营商搜索。 | API 使用 `prefix` 游标分页并返回 `hasMore/nextCursor`；页面数据来自真实数据库，可稳定前后翻页和搜索；接口不执行全表总数统计，页面不展示号段总条数。 |
+
+### 17.11 下游投递 ACK 与应用级重试策略
+
+| 用例编号 | 操作 | 预期结果 |
+| --- | --- | --- |
+| TC-GW-ACK-001 | 客户在线时分别触发一条状态回执和一条上行短信，Gateway `SendPkt` 成功后延迟返回 `CMPP_DELIVER_RESP`。 | 写出后 `CmppDownstreamDelivery.status=awaiting_ack`；只有匹配连接、Sequence_Id、Msg_Id 且 Result=0 后才变为 `delivered`，并保存写出时间、确认时间、ACK 字段和连接 ID。 |
+| TC-GW-ACK-002 | 分别返回非零 Result、不返回响应直到超时、重启 Gateway 后让旧 `awaiting_ack` 超时。 | 非零 Result 和超时不会误记为 delivered；Gateway 重启后 NestJS 能恢复过期 ACK，按策略进入退避重试或最终 `rejected/unconfirmed`。 |
+| TC-GW-ACK-003 | 在企业应用中分别关闭“回执自动重试”和“上行短信自动重试”，各制造一次 ACK 超时，再重新开启并创建新投递。 | 关闭只影响对应类型的新投递策略快照；离线后的首次投递仍会在重连时执行；已写出未确认的记录不自动重发；重新开启后新记录按退避策略重试。 |
+| TC-GW-ACK-004 | 对 `unconfirmed/rejected/failed` 记录执行单条和批量手工重投。 | 页面提示重复处理风险并二次确认；真实调用 Gateway；`awaiting_ack/delivered` 不允许重投；重发复用同一业务 Msg_Id。 |
@@ -1708,3 +1708,19 @@ git diff --check
 - 新增真实故障形态回归用例：完整括号签名、审核通过、全局 reporting 时可进入模板不匹配人工审核聚合，并验证查询不再携带全局报备条件、不产生签名失败回执。定向 API 测试 1 suite、41 项通过；API 全量 13 suites、142 项通过，API build、前端 build、Gateway 全量 Go 测试和 `git diff --check` 通过，前端仅有既有 Vite chunk size warning。
 - 功能提交 `f08a73e1` 已 push 并部署生产。部署前 PostgreSQL 备份为 `/opt/cmpp-platform/backups/cmpp-20260714-112012.sql`（约 64MB），运行源码备份为 `/opt/cmpp-platform/backups/source-20260714-112012.tar.gz`（约 15MB）；发布包本地与服务器 SHA-256 均为 `38b3fa6282a06648dabc048fbebca7a6579a6a7ef1f8eee514ecf14fb9d69790`。
 - 生产 36 条 migration 无待执行项，`.deployed-commit=f08a73e19129f5249a5a9e0035c7ab63b80422d4`；`cmpp-api`、`cmpp-gateway`、Nginx、MinIO 均 active，`12026/17890/8090/3000` 监听，API/Gateway health 和外部首页、运营端登录页 HTTP 200。线上源码确认按完整括号 `match[0]` 查询且不带全局 `reportStatus` 条件，部署后 API/Gateway 近期日志无 error。未擅自向客户号码重发短信；新提交将按应用现有模板不匹配人工审核策略进入真实审核与后续通道路由。
+
+## 2026-07-14 服务端安全会话与自动锁定（未提交、未部署）
+
+- 将可预测的 `dev-token:userId:sessionVersion` 和 localStorage 访问令牌替换为 256 位随机会话标识；浏览器只通过 HttpOnly、SameSite Cookie 携带，Redis 使用会话标识 SHA-256 键保存真实状态。生产模式 Cookie 默认 `Secure`，当前生产仍为 HTTP，因此本功能在完成 HTTPS 配置前不得部署。
+- 运营端/客户端无操作阈值分别为 60/120 分钟，提前 5 分钟提醒；超时进入密码锁屏，4 小时内可用当前密码解锁并轮换会话标识，超过后完整登录。绝对会话时长 12 小时不可滑动续期；敏感操作最近密码认证窗口为 30 分钟。
+- NestJS 中间件对运营端和客户端受保护 API 强制要求 Redis 会话，逐次校验用户状态和 `sessionVersion`；Gateway 回调和 health 保持原内部链路，不被浏览器会话门禁拦截。自动轮询只有检测到近期真实浏览器操作时才携带活动标识，不能长期保活无人值守会话。
+- 用户/权限、企业状态、应用密钥、通道和路由、报备状态、手工充值/退款/调整已接后端最近认证 Guard。前端收到 `RECENT_AUTHENTICATION_REQUIRED` 后要求当前密码，成功后自动重试；普通 JSON、Blob 和文件上传统一处理会话 401。会话创建、锁定、解锁、再认证和退出写 `OperationLog`，多标签页同步状态。
+- API 自动化测试当前 15 suites、151 项通过；新增 Redis 会话空闲锁定、客户端独立阈值、4 小时恢复期限、解锁轮换旧标识失效、`sessionVersion`/角色权限变更撤销和敏感操作 Guard 用例。真实本地 PostgreSQL + Redis + NestJS 短阈值验收通过：登录响应无访问令牌且收到 Cookie、无 Cookie 访问返回 `401/SESSION_INVALID`、空闲后返回 `401/SESSION_LOCKED`、密码解锁后恢复查询、认证窗口过期后敏感操作返回 `403/RECENT_AUTHENTICATION_REQUIRED`、重新认证和登出成功；临时用户与会话已清理。本轮按要求不提交、不推送、不部署。
+
+## 2026-07-14 下游 CMPP_DELIVER_RESP 精确确认与双重试开关
+
+- 生产只读排查 11:40 两条余额失败短信确认：NestJS 已生成 `REJECTD` 回执，Gateway 对同一 CMPP2.0 会话写出后分别收到 Sequence_Id 37/38 的 `CMPP_DELIVER_RESP`。原 `CmppDownstreamDelivery.status=delivered` 仅代表 `SendPkt` 成功，无法证明客户确认，属于观测口径缺陷。
+- Gateway 新增按连接和 Sequence_Id 跟踪投递，记录实际下发 Msg_Id；写出后回调 `downstream/sent`，收到 CMPP2.0/2.1/3.0 `DELIVER_RESP` 后校验 Sequence_Id、Msg_Id 和 Result，再回调 `downstream/acknowledged`。ACK 超时回调真实失败类型；重启后 NestJS 在客户恢复拉取 pending 时补偿处理过期 `awaiting_ack`。
+- Prisma `SmsApplication` 新增回执、上行两个自动重试开关，默认开启；`CmppDownstreamDelivery` 保存策略快照、写出/确认/截止时间、ACK Result/Sequence_Id/Msg_Id 和连接 ID。关闭开关后首次投递仍保留，已写出未确认或被拒绝的对应类型不自动重发；手工重投保留并增加重复处理二次确认。
+- 运营端企业应用编辑页增加两个独立开关；下游投递页区分待首次投递、等待客户端确认、客户端已确认、未确认、拒绝和最终失败，Dashboard 和告警改为真实 ACK 口径。历史 7 条仅确认写出的记录迁移为 `unconfirmed`，不伪造 ACK。
+- 新增 API ACK 状态与关闭重试策略单测、Gateway 真实 CMPP 会话 ACK 回调/超时单测；同步更新需求和 TC-GW-ACK-001～004。API 全量 15 suites、153 项通过，Gateway 全量 Go 测试、Prisma validate 与本地真实 PostgreSQL migration、API build、前端 build 和 `git diff --check` 通过；前端仅有既有 chunk size warning。应用内浏览器确认本地构建标题、登录 DOM、无框架覆盖及 console 无 error/warn；因真实图形验证码未获授权代解，受保护页面内的两个开关点击验收未执行。待提交并部署后补充最终提交、备份、migration 和生产验收结果。