功能说明
已登录且当前没有密码的用户,通过本人当前绑定手机号的短信验证码首次设置密码。已有密码返回明确错误,不执行改密。本文描述当前源码,尚未部署。
无需先查询 密码状态。发送和提交均实时查询数据库,不信任页面状态或用户资料缓存。
请求说明
POST /jim/users/setpass- Headers:
appkey、Authorization(登录返回的原文,不加 Bearer)、Content-Type: application/json。 - 必须是有效 ds1 或兼容期 legacy 用户身份,遵守 设备登录策略。API Key、service、空 requester 均拒绝。
- 仅操作当前 app 的当前 requester。没有
user_id、phone参数,额外传入不会改变目标。
先调用 发送验证码:
POST /jim/sms/send HTTP/1.1
appkey: YOUR_APP_KEY
Authorization: USER_AUTHORIZATION_TOKEN
Content-Type: application/json
{"purpose":"set_password"}
收到验证码后提交:
POST /jim/users/setpass HTTP/1.1
appkey: YOUR_APP_KEY
Authorization: USER_AUTHORIZATION_TOKEN
Content-Type: application/json
{"code":"123456","new_password":"my password"}
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string | 是 | 本次 set_password 用途下发的六位数字验证码 |
| new_password | string | 是 | 6–64 个 Unicode 字符,禁止全空白,不裁剪首尾空白 |
当前密码必须为 SQL NULL 或空字符串,非空(包括空白)均算已设密码。绑定号码须为大陆 1[3-9][0-9]{9} 或带 + 的国际号码(首位非零、7–15 位数字),不裁剪号码空白。手机号格式资格与 password/status 一致,不保证供应商覆盖所有国际号码。
此密码规则仅新增设密接口采用,不改变注册或旧 updpass 的既有规则。存储继续使用 SHA1,兼容现有账密登录;更强哈希的迁移另期处理。
验证码与频控
- crypto/rand 强随机六位码,固定测试万能验证码不适用。
- 按 purpose、app、user、当前绑定手机号隔离,不能使用 login 验证码;不在响应中返回手机号、验证码或 hash。
- 从发送预留起 300 秒有效,到期瞬间即失效;重发产生新码并使旧码失效,不延长或复用旧码。
- 每 app 下账号和手机号分别执行:60 秒重发间隔,每小时 5 次、每日 10 次。小时/日为从各自首次发送起算的固定 3600/86400 秒窗口,不是自然日或滑动窗口。
- 配置预检失败不预留配额、不替换已有挑战。发送预留持久化后即计小时/日额度并作废旧码;供应商明确非 OK 业务响应只释放当前 attempt 的短期冷却,不退小时/日额度。超时、网络错误、缺失业务状态等结果未知,保留短期冷却。旧响应不能释放新 attempt 的配额或激活其挑战。
/sms/send的 set_password 响应新增data.retry_after_seconds:成功通常 60,失败按账号及手机号各项有效限制剩余秒数取最大值;明确拒绝且无其他限制为 0,17021 包含实际等待时间。客户端请求中禁用重发,成功/失败均按此值倒计时,其他失败不盲启 60 秒。此字段不改变/users/setpass或登录用途响应。- 每个挑战最多 5 次验证错误,第 5 次和随后验证返回 17022;重发受发送限额限制并重新计验证次数。
- 当前绑定号码与发码号码不一致时不可使用旧码,需向新绑定号码重新发码。
- MySQL 行锁和事务原子消费及条件设密;多个进程并发只允许一次成功,不能覆盖已设密码。数据库错误回滚提交,不会消费后丢失重试机会或误报成功。
响应说明
{"code":0,"msg":"success","data":null}
成功后重新查询密码状态为 has_password:true、can_set_password_by_sms:false。无需更新用户资料中的 has_password 缓存。
错误说明
通常 HTTP 200,必须检查业务 code;成功或失败都不返回手机号、密码或验证码。
| code | 说明 |
|---|---|
| 17001 / 17002 | 缺少 appkey / 应用不存在 |
| 17003 | JSON 或密码不符合规则;发送接口未知 purpose |
| 17005 | 未登录、API Key/service、空 requester、legacy 无效或被策略拒绝 |
| 17605 | ds1 无效、过期或会话撤销 |
| 17012 | 当前 app 下的本人用户不存在 |
| 17019 | password already set:已有密码,请走既有改密流程 |
| 17020 | valid bound phone required:无格式有效绑定手机号 |
| 17021 | SMS rate limited:发送间隔或账号/手机号额度限制 |
| 17022 | SMS verification attempts exceeded:错误尝试达到 5 次,需重新发码 |
| 17023 | invalid or expired password SMS code:验证码错误、到期、无记录、发送未确认成功、号码已改变或跨用途/app/user |
| 17008 | 供应商配置预检失败不计额、不替换旧码;已预留后的发送失败使旧码失效并计小时/日额度,明确拒绝仅释放本次短冷却,未知结果保留冷却;等待时间见发送响应 data.retry_after_seconds |
| 17000 | 数据库/随机数内部错误,不能视为成功;提交事务失败允许原码有效期内重试 |
| 17024 | password SMS pepper not configured:服务器专用 pepper 未配置或少于 32 字节,新用途禁用 |
部署与配置
后续兼容迁移 20261110.sql 为已存在的配额表补齐 attempt_nonce 字段,允许重复执行。必须先完成迁移再运行使用新字段的服务版本;新建数据库的初始迁移也包含该字段。
服务端迁移 20261109.sql 新增 InnoDB 表 password_sms_challenges、password_sms_quotas,以及 users.password_sms_phone_version 字段和手机号变更触发器;号码修改后即使改回原号码,旧验证码仍失效,不需修改旧绑定接口。兼容 MySQL 8.0,迁移账号需要 TRIGGER 权限。启动 Upgrade 按版本执行,字段变更 PREPARE 固定在同一连接。MySQL 不支持 PREPARE CREATE TRIGGER,触发器由 Go 专门步骤查询 information_schema.TRIGGERS 后执行普通 CREATE TRIGGER,支持重复运行和失败重试,错误时不推进版本。必须通过启动 Upgrade 执行完整迁移,不能仅手工运行 SQL 文件。须先完成迁移、服务器 pepper 与应用短信目的配置再开放入口。
服务器 YAML 必配 password_sms_pepper:至少 32 字节的高熵服务器专用秘密。默认空或不足 32 字节时,设密发送及提交返回 17024,且不会占用额度或调用供应商;原登录 SMS 不受该配置影响。示意只使用占位符:
password_sms_pepper: "<至少32字节的服务器专用随机秘密>"
所有服务进程使用相同且重启后稳定的值,不可每次启动随机生成;不把真实值写入仓库、数据库或日志。更换 pepper 会令已有验证码失效,需重新发送。
验证码摘要使用 HMAC-SHA256,绑定 purpose、app、user、phone、nonce、code、phone version,常量时间比对。pepper 不与挑战记录同库存放,也不复用 apps 表的 AppSecureKey;目标是防止仅挑战表泄露后的离线穷举,不承诺服务器秘密和数据库同时泄露后的防护。
应用扩展项 set_password_sms_engine_conf 选填,使用与 sms_engine_conf 相同 JSON 结构。仅当此记录确实不存在时回退到原登录短信配置 sms_engine_conf;显式空值、非法 JSON、不完整配置、数据库查询失败及不支持渠道均失败关闭,不回退。无论使用独立配置还是回退配置,都必须逐应用核实模板适用于首次设密或通用身份验证,不能复用只写登录/注册的误导文案。目前新用途仅支持 aliyun,并检查供应商业务返回 OK;旧 Baidu adapter 输出供应商响应,SMSBao adapter 未校验业务状态,因此新用途拒绝使用这两个 adapter,原登录流程不变。
{
"channel":"aliyun",
"aliyun":{
"access_key":"YOUR_ACCESS_KEY",
"access_secret":"YOUR_ACCESS_SECRET",
"sign_name":"YOUR_SIGN",
"template_code":"YOUR_SET_PASSWORD_TEMPLATE",
"template_code_key":"code"
}
}
模板必须明确为首次设置密码或通用身份验证用途,不能误用只写“登录”的模板。上述内容仅占位示例,勿将真实配置写入文档/日志。
发送预留成功后调用供应商,仅确认成功并完成数据库激活才返回成功。供应商可能已接受但激活 DB 失败时返回 17000,收到的验证码不会被接受;等待间隔后重新发码。can_set_password_by_sms 不检查供应商配置或是否已部署。