ORVIBO Smart Control 同时连接家庭局域网、ORVIBO 云端和 Home Assistant 服务总线。 账号认证、门锁授权和事件媒体都应视为高敏感数据。本文件说明项目的报告渠道、信任边界和 提交材料要求。

请不要在公开 Issue 中披露可利用的漏洞、真实凭据或未修复的攻击步骤。优先通过仓库的 GitHub Security Advisory 私密报告功能联系维护者 maycode0-0；如果该功能不可用，请先 通过维护者的 GitHub 主页请求一个私密联络渠道，只发送影响摘要，不发送秘密本身。

报告应包含：

• 受影响的集成版本和 Home Assistant 版本；
• 攻击前提、影响范围和最小复现步骤；
• 相关模块、堆栈和脱敏后的协议形态；
• 已尝试的缓解措施；
• 是否存在公开利用或已知受影响用户。

维护者确认前不要公开完整细节。普通兼容性问题、设备支持请求和无安全影响的错误应使用 公开 Issue。

安全修复以最新发布版为目标。旧版本用户可能会被要求先升级，以排除已修复问题。开发分支 和未经发布的本地修改不提供兼容承诺，但其中可复现的安全缺陷仍欢迎私密报告。

• HomeMate/智家 365 账号、手机号和明文密码；
• 云账号和独立 MixPad LAN 密码的大写 MD5 摘要；它们可直接用于协议认证，安全等级等同密码；
• access token、session ID、session key、dynamic key、cookie 和 OAuth 参数；
• COS 临时密钥、security token、签名媒体 URL 和私人对象键；
• 临时门锁密码、授权 ID 与真实用户映射；
• Home Assistant 长期令牌、备份、.storage 内容和完整诊断包。

家庭 ID、用户 ID、设备 ID、UID、status ID、extAddr、MAC、IP、家庭/房间名称和可识别的 设备名称不一定能直接登录账号，但会暴露家庭拓扑或关联不同数据集。公开材料中应用稳定的 明显占位符替换，例如 REDACTED_DEVICE_A，不要换成另一个看似真实的十六进制值。

组件内的共享客户端证书和私钥用于兼容厂商 TLS 服务。它们来自公开可获取的厂商 App 协议 材料，不是每个用户独有的身份凭据，服务端也不能仅凭它们区分 Home Assistant 实例。对这组 文件做可逆加密无法建立新的信任边界，因为无人值守连接需要把解密能力一同分发。

这不降低账号令牌和会话密钥的敏感性。共享证书不能替代对运行时秘密的保护。

LAN 通道会发现 MixPad，并在 TCP 8088 上建立经过协议登录的会话。实现会校验预期网关 UID、会话身份、响应关联和推送数值，并在日志中掩码 IP、UID 与设备标识。

部署侧仍需承担以下责任：

• 不把网关端口转发到公网；
• 在可信家庭网络中运行 Home Assistant；
• 跨 VLAN 放行时只允许 HA 与指定网关之间的最小流量；
• 防止不受信任客户端加入可访问网关的网络；
• 保持 Home Assistant、集成和宿主系统更新。

默认结合模式下 LAN 失败后的云端回退提升可用性，不是安全认证的替代品。纯 LAN 模式明确 禁止该回退，纯云端模式不连接网关。来自错误网关或畸形推送的数据应被拒绝，而不是因为 云端存在就接受。独立 LAN 凭据只应在 MixPad 确实使用不同账号时启用，配置项保存摘要而非 明文；关闭后会删除独立用户名和摘要并恢复使用云账号摘要。

门锁是云专属只读设备，但临时密码服务会执行真实授权动作。自动化在调用前应限制触发来源、 门锁 device_id、授权时长和可用次数。不要让匿名仪表盘或低信任用户获得服务调用权限。

grant_temp_password 只在当前服务响应返回一次密码；事件总线和列表服务不会再次返回。 Home Assistant 自动化跟踪、通知历史和第三方日志仍可能记录响应变量，使用者需要自行控制 这些下游系统。

事件媒体保存在 Home Assistant 的 media/orvibo_smart_control/ 下，并可能短暂出现在带签名 的 URL 中。媒体可能包含人脸、门牌、室内环境和访问时间，应纳入备份加密、访问控制与保留 策略。默认历史保留 7 天并每周清理一次，可通过 cleanup_history 调整。

通用配置中的本地清理只删除上述集成媒体目录，并可重置通用选项。它不会删除账号、家庭、 设备选择、门锁用户映射、实体注册或 Home Assistant .storage，也不会操作其他集成目录。

集成更新检查默认关闭。启用后，Home Assistant 会按 6 到 168 小时的配置间隔访问 api.github.com/repos/maycode0-0/orvibo-smart-control/releases/latest，只读取最新稳定 版本标签，并在发现新版本时创建固定 ID 的持久通知；请求不包含 ORVIBO 账号、家庭或设备 数据。设备上下线通知同样默认关闭，可发送到用户指定的 domain.service，因此通知服务及 其下游存储会看到设备显示名称和上线/离线状态。

提交前至少检查以下内容：

git diff --check
git grep -n -I -E "accessToken|sessionKey|sessionId|password|phone|familyId|deviceId|security-token"

合法协议字段也会命中，必须人工确认字段值已经替换。JSON 字符串内可能嵌套另一层 JSON； 图片和视频也可能显示实体 ID、家庭名称或临时密码。

项目诊断只应保留解决问题所需的最小状态，不应宣称包含 MQTT 记录：当前实时云通道是厂商 二进制 TLS/SSL 长连接，项目没有独立 MQTT 客户端。抓包工具只应用于自己控制的账号与设备。

完整的贡献样本规则见 贡献指南。

运行时依赖以 manifest.json 为准。提交不得引入未固定来源的可执行文件、提交真实云端响应、 绕过 HACS/hassfest 校验，或把测试凭据写入 workflow。发布包应只包含组件运行所需文件，项目 项目名称、仓库地址和集成域由 manifest、HACS 元数据、CI 校验与代码审查共同维护。