首次握手与凭据轮换
一次性引导、双向数据库凭据、可恢复交付与在线轮换的协议。
本页是插件双向握手凭据的交付、轮换与撤销规范。公共 SDK 的 enrollment 模块提供类型。
会话协议由注册声明 protocols.credentials 选择，会话业务请求与响应不带 contractVersion；版本与选择边界见
权威规范。
管理员接入 create/status/revoke 保持独立管理合同 2.0.0，管理 DTO 的 contractVersion 保留；不包含 environmentId 或 endpointName。
Contract crate 只提供类型和校验；HTTP 调用、数据库存储、加密和轮换调度由插件自己的服务实现。
本页适用于直接承载协议的插件服务，也适用于
独立 Adapter Hosted Service。
采用 Adapter 时，将插件身份、一次性引导授权和加密密钥交付到 Adapter Environment；凭据由 Adapter
独立数据库保存与轮换，业务后端不复制握手状态或平台长期 Token。
插件身份独立于部署载体。平台只登记插件标识、工作区归属、授权回调地址和凭证状态，不保存 Hosted Service 或 Application Runtime 绑定。
CLI 接入步骤见插件注册与管理。
首次操作顺序与分层验收统一见首次接入流程与验收。本页描述程序实现协议，不能代替部署交付步骤。 服务启动后建立并持久化双向凭据；生命周期接口校验当前有效凭据后执行请求。
两个方向，各自独立
平台调用插件的 caller token 由插件生成；平台加密保存，插件长期保存验证哈希。 插件调用平台的 platform token 由平台生成；平台长期保存验证哈希，插件加密保存。 CLI 只签发一次性授权并将 Token 写入指定私密文件，凭据交付由部署所有者完成。 采用 Hosted Service 时，通过其独立配置管理命令写入 Secret 并显式绑定进程变量；仅保存 Secret 值不会自动注入进程。 握手完成后，由部署所有者清理本地 Token 文件、引导键及变量绑定，保留身份与加密密钥绑定。 数据库加密密钥通过部署 Secret 提供，不能和密文一起放在业务数据库，也不能复用用户登录凭据、业务服务 token 或引导 token。
每次发起请求读取当前有效凭据，不能将启动时的 token 一直保存在鉴权器或 HTTP 客户端中。 双向数据库中的代次由交付协议关联，两个数据库之间不存在原子事务。
交付顺序
- 插件先持久保存唯一
exchangeId、基准代次及本次生成的 caller token 密文，再发起交换。 - 用引导 token 或当前有效 platform token 请求
POST /bundle-plugin-manager/api/plugin-session/exchange， 提交pluginId、exchangeId、expectedGeneration、executeUrl和callerToken。 - 平台锁定插件身份并创建候选代次，返回
platformToken、generation、expiresAt、renewAfter、pendingUntil。 相同交换重试返回同一组凭据；相同授权不能被不同交换或不同 caller token 认领。 - 插件先将候选 platform token 加密落库，再用它调用
POST /bundle-plugin-manager/api/plugin-session/confirm， 提交pluginId和exchangeId。 - 平台在一个本地事务内确认代次并切换出站凭据，返回
previousValidUntil。插件随后推进本地当前代次， 删除临时 caller token 密文。平台删除为重复交付而暂存的 platform token 密文。
尚未确认的候选 token 只能用于确认交付，不能提前用于平台业务接口。确认操作可重试，确认响应丢失时 使用已经落库的新 token 再确认即可。多个副本必须通过数据库事务和唯一约束复用同一候选交换， 不能按响应到达顺序覆盖代次。
轮换、撤销与恢复
插件按平台返回的 renewAfter 调度下一次交换。初始部署策略为：引导和待确认交付各最长 30 分钟，
长期凭据 30 天，提前 7 天轮换，上一代最多重叠 5 分钟。期限来自平台版本化配置，插件不能自行扩大。
旧代在期限结束后立即拒绝；后台秘密清理不替代每次鉴权时的期限校验。
过期且未确认的轮换交付可用当前有效 platform token 调用
POST /bundle-plugin-manager/api/plugin-session/abandon，提交原 exchangeId。
只有平台确认它未生效并已超时后，插件才删除本地候选并建立下一次交换。
已经确认的交付不得丢弃，必须恢复确认结果。若当前凭据也已失效，则由管理员重新授权。
为即时观察平台撤销，插件先校验本地 caller token，再通过当前有效 platform token 调用
POST /bundle-plugin-manager/api/plugin-session/authorize-caller，提交 pluginId和 callerToken。
只有返回成功且 data 为 true 才接受本次受保护调用；不得缓存结果，平台不可达时失败关闭。
切换期间平台可能先于插件本地事务完成，此时使用已经持久接收的候选 platform token 验证对应 caller token。
撤销会终止待确认交付，旧 token 不能通过轮换重新激活身份。已经发出的请求无法追回。
数据库不可用、加密密钥错误、关联身份不符或凭据失效时，应明确拒绝受保护操作。 进程健康检查验证数据库连接和 listener；后台握手建立受管会话，接入状态单独记录并验证。
迁移与发布顺序
插件管理不调用 Hosted Service 核验接口。已有插件的握手、确认、轮换和 caller 授权继续使用会话协议 1.0.0。
管理接口升级为 2.0.0 后使用 CLI 0.98.0 或后继兼容版本；旧部署定位字段不再接受。
删除历史部署绑定不会清除已有凭证、代次或授权历史，不需要为了此变更重新授权。
接入时先准备插件数据库与 Secret，再交付一次性授权，完成握手并回读确认结果。
已经启用受管凭据后，不能只回滚到不理解该状态的旧镜像。恢复必须使用支持本协议的版本或执行明确的管理员重新授权。 文档不构成线上验收：必须完成真实握手、无引导变量重启、响应丢失恢复、在线轮换和撤销测试后才宣告上线。