# 账号层(`base_user`)契约 > 🔴 本文件讲**账号层**:载体是什么、口令怎么算、管理员位怎么判、角色码怎么取。 > 上游对照物 = JNPF j7 的 `base_user` / `base_role` / `base_role_relation` 三张表 > + 上游 `PasswordTokenGranter` 的口令算法。 > 与 `docs/contract.md`(对外形状)/ `docs/known-limitations.md` L4(权限敞开)配套读。 --- ## 1. 载体 | 表 | 用途 | 本仓位置 | |---|---|---| | `base_user` | 账号(`f_account` / `f_password` / `f_secretkey` / `f_is_administrator` / `f_enabled_mark` / `f_delete_mark` …) | `schema/migrate.sql`(B2 起建表,B4 起**真正使用**) | | `base_role` | 角色(`f_en_code`) | 同上 | | `base_role_relation` | 用户 ↔ 角色(`f_object_type='user'` + `f_object_id` + `f_role_id`) | 同上 | 🔴 **数据面代码**:`src/tdc/service/account.rs`(读写 `base_*`)、 `src/tdc/controller/account.rs`(6 个端点 + 登录)。 🔴 **不建**上游其余 120 张 `base_*`(`base_module` / `base_authorize` / `base_organize` …)—— 上游 `ssw.jnpf-permission.enabled=false` ⇒ 菜单授权行是死的(见 `docs/known-limitations.md` L2)。 🔴 **`data/accounts.json` 保留但后端不再读取**(B4 之前它是载体)。 存量账号**不导入**(决策 D8)⇒ 旧 JSON 里的账号在 B4 之后**登不上**。 --- ## 2. 口令:官方双 md5 公式 ### 公式 ``` f_password = md5( lower( md5(明文) ) + lower(f_secretkey) ) ``` - 入参 `md5(明文)` 是**明文的 md5 hex**(32 个小写 hex),不是明文本身。 - `f_secretkey` 是**每账号随机**的秘钥(UUID v4 大写,36 字符带连字符)。 - 上游对照:`PasswordTokenGranter.java:186` = `Md5Util.getStringMd5(inputPwd + secretkey.toLowerCase())` (`inputPwd` 已经是 `md5_hex(明文)`)。 ### 完整链路 | 环节 | 做什么 | 代码位置 | |---|---|---| | 浏览器加密 | `md5(明文)` → AES-256-ECB-PKCS7 → hex | `src/platform/cipher.rs`(与上游 `frontend/web/src/utils/cipher.ts` 逐字对齐) | | 服务端解密 | 密文 hex → `md5(明文)` | `src/platform/cipher.rs`(`decrypt_login_password`) | | **入库 / 比对** | `md5(lower(md5(明文)) + lower(secretkey))` | `src/tdc/service/account.rs:124`(`official_password_hash`) | | 登录比对 | `constant_time_eq`(常量时间) | `src/tdc/controller/account.rs:78`(`login`)+ `src/platform/compare.rs` | ### 🔴 三条容易踩的 1. **改密不换 secretkey**(与官方一致)⇒ `reset_password` 只重算 `f_password` (`src/tdc/service/account.rs:576`)。 2. **一次性换算单向不可逆**:`f_password = md5(lower(旧裸 md5 hex) || lower(新 secretkey))` ⇒ 从旧的裸 md5 换到新公式,需要**旧 md5**(前端手里那份)+ 新 secretkey; 拿明文反推也可以,但**拿旧的 `f_password` 反推不出来**。 3. **别把裸 md5 当口令存**:裸 md5 一旦泄漏即可直接当口令用(上游公式正是为了这个)。 ### 自证(不是自证自洽) `src/tdc/service/account.rs` 的单测 `official_password_hash_matches_the_upstream_formula` 用**两个独立向量**(用系统 `md5` 算出来的,不是本仓代码算的): | secretkey | 期望 `f_password` | |---|---| | `A1B2C3D4` | `f5aed9cb34072037071de9e90f3ef650` | | `00-11-22` | `cf1150bde4e2f01f1f0a4558a800cbb0` | (`md5("123456")` = `e10adc3949ba59abbe56e057f20f883e`) 另有一道**跨端**防线:`tests/account_api.rs::login_accepts_the_upstream_literal_ciphertext` 拿**上游的字面密文**真打登录端点(改密钥它必红)。 --- ## 3. 引导(幂等) `src/tdc/service/account.rs:621`(`bootstrap_account_layer`): 1. **种三个角色**(照抄上游 `V1.0.1__connector_seed.sql`,含固定 id): `tdcProvider` / `tdcConsumer` / `user`(`WHERE NOT EXISTS` ⇒ 幂等)。 2. **`base_user` 有没有存活行**?有 ⇒ **不引导**(幂等,不覆盖既有账号); 无 ⇒ 建**一个**管理员: `f_account` = `TDC_BOOTSTRAP_ADMIN_ACCOUNT`(默认 `admin`)、 `f_is_administrator=1`、`f_enabled_mark=1`、口令按上面公式入库。 3. **管理员绑角色**:`base_role_relation` 写一行,绑 `user` 角色。 🔴 **全程持 `db_lock`** ⇒ 进程内串行(pglite 单 backend)。 ### 🔴 默认口令是**公开已知**的 `admin` / `admin` ⇒ **本地调试默认值**。 - `TDC_STRICT_SECRETS=1` ⇒ 启动时若管理员**仍在用默认口令** ⇒ **拒绝启动** (`src/main.rs` + `src/tdc/service/account.rs:753`)。 - 部署前**必须**改口令(走 `POST /api/permission/Users/{id}/Actions/ResetPassword`)。 --- ## 4. 管理员位(fail-closed) | 项 | 口径 | |---|---| | 判据 | `base_user.f_is_administrator = 1` **且** `(f_delete_mark IS NULL OR f_delete_mark = 0)` | | 代码 | `src/tdc/service/account.rs:289`(`is_administrator`) | | **异常处理** | **查询出错 ⇒ false**(fail-closed)⇒ 宁可拒绝,**不可**误放行 | | 用途 | 守 `/api/permission/Users*` **6 个**端点(`src/tdc/controller/account.rs:149`,`require_admin`) | `require_admin` 的放行口径: | 主体 | 结果 | |---|---| | 连接器身份会话(`Principal::Session`) | ✅ 放行(上游同款:身份本身就是管理员) | | 本地账号会话(`Principal::Account`) | 查 `f_is_administrator` ⇒ 1 才放行 | | 内部令牌(`Principal::Internal`) | ❌ **403**「仅管理员可管理连接器用户」(比上游严一档,**刻意**) | | 无凭证 | ❌ **401**「内部接口凭证无效」 | 🔴 **管理员账号不可删**:`remove()` 遇 `administrator == true` ⇒ 业务失败 「管理员账号不可删除」(`src/tdc/service/account.rs:513`)。 --- ## 5. 角色码 `src/tdc/service/account.rs:320`(`role_codes`)—— **逐字照抄**上游 SQL: ```sql SELECT b.f_en_code FROM base_role b JOIN base_role_relation r ON r.f_role_id = b.f_id WHERE r.f_object_type = 'user' AND r.f_object_id = ? AND (b.f_delete_mark IS NULL OR b.f_delete_mark = 0) AND b.f_en_code IN ('tdcProvider','tdcConsumer','tdsReadOnly') ``` - 暴露在 **`GET /api/ssw/tdc/Auth/Me` 的 `roles` 键**(上游 `AuthController#me:207` 同款) ⇒ `src/tdc/service/identity.rs:360`(`me_payload`)。 - **只对账号会话算**(上游只有门户登录这一路算角色)⇒ 身份会话返回**空数组**。 ### 🔴 悬空码(上游自身的不一致,照抄) | | `tdcProvider` | `tdcConsumer` | `tdsReadOnly` | `user` | |---|---|---|---|---| | **判据**(`IN` 列表) | ✅ | ✅ | ✅ | ❌ | | **种子**(`SEED_ROLES`) | ✅ | ✅ | ❌ | ✅ | ⇒ 引导管理员绑的是 `user` 角色 ⇒ **它的 `roles` 数组是空的**。 **这不是 bug**,是上游口径(决策 D9)。 --- ## 6. 出参形状(**不变**) `/api/permission/Users` 每一行(`src/tdc/controller/account.rs:127`,`account_view`): ```json { "id", "account", "realName", "gender", "mobilePhone", "enabledMark", "creatorTime", "description" } ``` - 🔴 **不得**回显 `f_password` / `f_secretkey`(出参**整条删键**,不是置 null)。 - `gender` 是**数字**(上游列是 `varchar(50)` ⇒ 存数字文本、读时解析成 `i64`,默认 0)。 - `mobilePhone` / `description` 空串落 **SQL NULL** ⇒ 出参是 `null` 不是 `""` (`src/tdc/service/account.rs:169`,`opt_p`)。 - `creatorTime` 是 `to_char(f_creator_time,'YYYY-MM-DD HH24:MI:SS')` 的**字符串** (服务器本地时区,见 `docs/contract.md` §时间口径)。 --- ## 7. 自检 ```bash # 账号层真的在库里 curl -s --noproxy '*' http://127.0.0.1:30000/api/health # ⇒ baseTables = 3 # 登录(口令公式端到端) bash scripts/smoke.sh # ⇒ PASS=80 FAIL=0 # 口令公式的两个独立向量 cargo test --lib official_password_hash ```