mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-06 01:07:35 +00:00
refactor(security): Store 复用 Codec 加密能力 + 删 globalCodec 单例
## 用户裁定
> store也应该调用security的加密能力！
## 改动前的事实（实测）
两套**完全重复**的 AES-256-GCM：
Store.seal/open store.go:372,388 裸 base64
Codec.Seal/Open codec.go:113,139 enc:v1: 前缀 + 域隔离 + 幂等
算法、nonce 布局（前置 + io.ReadFull(rand)）、密钥环轮换逻辑全都一样，
只有 Codec 多了前缀与域隔离。
危害不是"代码重复"这么轻：
· 两套实现各自演化，任何一侧的改动不会被另一侧的判据发现
· Store 缺域隔离 ⇒ 变量库与配置共用密钥（安全倒退）
· Store 缺前缀 ⇒ 无法区分"旧密文"与"明文"（惰性迁移的障碍）
## 本次做的
### Store 委托 Codec
codecOf() 按当前 keys 环惰性构建（轮换后自动跟上）
sealWithRing() 新格式（enc:v1: 前缀）
openWithStoreRing() 兼容新旧两种格式，返回 needsMigrate
删除 Store 自带的 seal/open/openWithRing —— 现在**只有一处** AES-GCM。
### 域隔离（安全判据）
storeCodecDomain = "security/variables"
configCodecDomain = "config-at-rest"
两者必须不同：同域时一处明文泄漏可推导另一处密文。
### 存量密文惰性迁移
旧格式是裸 base64 无前缀，而 Codec.Open 对无前缀输入**原样返回明文**
（那是给 config 的存量明文兼容）。直接交给 Open 会把密文当明文返回，
症状是"凭据回填出一个 base64 串"。
所以 Store 走 openWithStoreRing：
enc:v1:... → Codec.Open
裸 base64 → Codec.OpenLegacy（解开后立刻回写新格式）
不做启动时全量迁移（21G 数据目录的教训：迁移窗口越长越危险），
也不让两种格式永久共存（判据永不能要求"落盘都是新格式"）。
### 删 globalCodec 单例 → 归 Runtime
security 模块 → rt.SetCodec(c) → ks.Security
config 模块 → cfgReg.SetCodec(ks.Security.Codec())
ConfigRegistry 加 codec 字段（注入而非读全局），6 处 ConfigCodec() 改为
r.codecOf()；PluginSettings 经 p.registry 转调。
sdk.SecretsAPI 也加 codec 参数（插件加密能力来自它的内核实例）。
### 顺带
· InitConfigCodec* / ClearConfigCodec 删除，改 NewConfigCodec 返回实例
· homed-key-rotate 改为 构造 + reg.SetCodec（不再装全局）
· bootstrap_order_test 的锚点从 InitConfigCodecWithOldKeys 改为
NewConfigCodec（守的不变量不变，只是生效点写法变了）
## 判据（均经变异验证）
TestNoPackageLevelSingletons 禁表补入 globalCodec
TestStoreWritesPrefixedCiphertext 新密文必须带 enc:v1:（旧实现裸 base64 ⇒ 红）
TestStoreAndConfigUseDifferentDomains 域隔离；改成同域 ⇒ 红（实测确认）
TestLegacyCiphertextStillReadableAndMigrates 旧格式可读 + 落盘已升级
TestRotationKeepsOldCiphertextReadable 轮换后旧条目仍可回填
## 验证
go build ./... PASS
go vet ./... PASS
gofmt -l 干净
go test ./... -count=1 63 包全过，0 FAIL
干净检出（git worktree） build + security/config 测试全绿
## 数据风险
加密实现切换有丢数据风险，因此：
· 先写往返判据，再改实现
· 惰性迁移（读到才升级），不做启动全量重写
· 旧格式与旧密钥环**都保留**读取路径
This commit is contained in:
JianFeeeee
@ -31,7 +31,6 @@ import (
|
||||
"fmt"
|
||||
"io"
|
||||
"strings"
|
||||
"sync"
|
||||
)
|
||||
|
||||
// EncPrefixV1 是密文的自描述前缀。
|
||||
@ -180,6 +179,75 @@ func (c *Codec) Open(stored string) (string, error) {
|
||||
return "", fmt.Errorf("%w (域 %s)", ErrBadCiphertext, c.Domain())
|
||||
}
|
||||
|
||||
// NewLegacyRingCodec 构造一个用**现成密钥环**（不做域派生）的编解码器。
|
||||
//
|
||||
// ★ 专供 Store 使用（2026-11-04 T3.2）。与 NewCodec 的区别只有一点：
|
||||
//
|
||||
// NewCodec ：用一个主密钥 HMAC 派生出**该域**的子密钥
|
||||
// NewLegacyRingCodec：直接吃一组密钥（Store 的 keys 环，含历史代）
|
||||
//
|
||||
// 为什么 Store 不能走 NewCodec 的域派生：它的密文是**用主密钥本身**加密的
|
||||
// （历史数据），换成派生密钥会让所有存量条目解不开 —— 那是数据丢失，
|
||||
// 不是迁移。
|
||||
//
|
||||
// keys[0] 是当前加密钥，其余只用于 Open（轮换过渡期）。
|
||||
func NewLegacyRingCodec(domain string, keys [][]byte) *Codec {
|
||||
c := &Codec{domain: domain}
|
||||
if len(keys) > 0 && len(keys[0]) == 32 {
|
||||
c.key = keys[0]
|
||||
for _, k := range keys[1:] {
|
||||
if len(k) == 32 {
|
||||
c.oldKeys = append(c.oldKeys, k)
|
||||
}
|
||||
}
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
// OpenLegacy 解开**无前缀**的旧格式密文（裸 base64 + nonce 前置）。
|
||||
//
|
||||
// ★ 为什么必须单独一个方法而不是让 Open 兼容：
|
||||
//
|
||||
// `Open` 对无前缀输入**原样返回**（那是"存量明文兼容"的正确行为——
|
||||
// 老配置里存的就是明文）。但 Store 的旧密文恰好也是无前缀的裸 base64，
|
||||
// 两者在字面上无法区分。
|
||||
//
|
||||
// 所以：
|
||||
//
|
||||
// 配置（config）→ 用 Open：无前缀 = 明文，原样返回
|
||||
// 变量库（Store）→ 读到无前缀时先试 OpenLegacy：能解开 = 旧密文
|
||||
// ⇒ 立刻用 Seal 回写为新格式（惰性迁移）
|
||||
//
|
||||
// 把歧义留在**调用方**（它知道自己存的是什么），而不是让 Open 猜。
|
||||
func (c *Codec) OpenLegacy(stored string) (string, error) {
|
||||
if !c.Enabled() {
|
||||
return "", fmt.Errorf("%w: 有密文但编解码器未启用（域 %s）", ErrNoMasterKey, c.Domain())
|
||||
}
|
||||
raw, err := decodeB64(stored)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("%w: 旧格式 base64 解码失败", ErrBadCiphertext)
|
||||
}
|
||||
keys := append([][]byte{c.key}, c.oldKeys...)
|
||||
for _, k := range keys {
|
||||
block, err := aes.NewCipher(k)
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
gcm, err := cipher.NewGCM(block)
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
if len(raw) < gcm.NonceSize() {
|
||||
continue
|
||||
}
|
||||
plain, err := gcm.Open(nil, raw[:gcm.NonceSize()], raw[gcm.NonceSize():], nil)
|
||||
if err == nil {
|
||||
return string(plain), nil
|
||||
}
|
||||
}
|
||||
return "", fmt.Errorf("%w: 旧格式密文解不开（域 %s）", ErrBadCiphertext, c.Domain())
|
||||
}
|
||||
|
||||
// IsEncrypted 报告一个已存储的值是否是本模块的密文。
|
||||
//
|
||||
// ★ 单调为真：密文解密后可能恰好以 `enc:v1:` 开头（极小概率），
|
||||
@ -188,38 +256,32 @@ func IsEncrypted(stored string) bool {
|
||||
return strings.HasPrefix(stored, EncPrefixV1)
|
||||
}
|
||||
|
||||
// ---------------- 全局配置编解码器 ----------------
|
||||
// ---------------- 配置落盘编解码器 ----------------
|
||||
|
||||
var (
|
||||
globalCodecMu sync.RWMutex
|
||||
globalCodec *Codec
|
||||
)
|
||||
// ★ 2026-11-04（T3.2）：包级单例 `globalCodec` 与访问器 `ConfigCodec()`
|
||||
// 已删除（用户裁定「所有共享数据统一挂载一个 kernel 提供的挂载点上暴露」）。
|
||||
//
|
||||
// 配置加密器现在归 `security.Runtime`：
|
||||
//
|
||||
// security 模块装配 → rt.SetCodec(c) → ks.Security
|
||||
// config 模块装配 → cfgReg.SetCodec(ks.Security.Codec())
|
||||
//
|
||||
// 与变量库（ks.Security.Store()）同源同生命周期，没有任何第二条通道。
|
||||
|
||||
// InitConfigCodec 装配配置落盘用的编解码器（内核启动时调用一次）。
|
||||
func InitConfigCodec(masterKey []byte) (*Codec, error) {
|
||||
return InitConfigCodecWithOldKeys(masterKey, nil)
|
||||
// NewConfigCodec 构造配置落盘用的编解码器（**不**注册任何全局状态）。
|
||||
//
|
||||
// 当前钥负责 Seal；旧钥仅参与 Open（E-1 平滑轮换）。
|
||||
// 调用方拿到实例后负责注入（见 Runtime.SetCodec）。
|
||||
func NewConfigCodec(masterKey []byte, oldKeys [][]byte) (*Codec, error) {
|
||||
return NewCodecWithOldKeys(masterKey, configCodecDomain, oldKeys)
|
||||
}
|
||||
|
||||
// InitConfigCodecWithOldKeys 装配支持 E-1 平滑轮换的配置 codec。
|
||||
// 当前钥负责 Seal；旧钥仅参与 Open。
|
||||
|
||||
func InitConfigCodecWithOldKeys(masterKey []byte, oldKeys [][]byte) (*Codec, error) {
|
||||
c, err := NewCodecWithOldKeys(masterKey, "config-at-rest", oldKeys)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
globalCodecMu.Lock()
|
||||
globalCodec = c
|
||||
globalCodecMu.Unlock()
|
||||
return c, nil
|
||||
}
|
||||
|
||||
// ConfigCodec 取配置编解码器；未装配时返回 nil（调用方原样读写）。
|
||||
func ConfigCodec() *Codec {
|
||||
globalCodecMu.RLock()
|
||||
defer globalCodecMu.RUnlock()
|
||||
return globalCodec
|
||||
}
|
||||
// configCodecDomain 是配置落盘加密的域。
|
||||
//
|
||||
// ★ 必须与变量库的域（storeCodecDomain）不同 —— 见那边的说明。
|
||||
// 域在这里集中定义，避免"两处各写一个字符串"（拼错了不会报错，
|
||||
// 只会让两个域意外重合，而那是安全倒退）。
|
||||
const configCodecDomain = "config-at-rest"
|
||||
|
||||
// NeedsRekey 报告该密文是否**不是**当前主密钥加的（即轮换后尚未重加密）。
|
||||
//
|
||||
@ -273,13 +335,11 @@ func (c *Codec) openWithSingleKey(key []byte, stored string) (string, error) {
|
||||
return string(plain), nil
|
||||
}
|
||||
|
||||
// ClearConfigCodec 卸下配置编解码器（测试与"显式关闭加密"用）。
|
||||
// ★ 2026-11-04：`ClearConfigCodec` 已删除。
|
||||
//
|
||||
// 单独一个函数而不是让 InitConfigCodec(nil) 承担：
|
||||
// 后者语义模糊（nil 是"没密钥"还是"要清空"？），且会掩盖调用方的错误
|
||||
// —— 曾因此让一个判据假绿（以为清空了，其实上一把密钥还在）。
|
||||
func ClearConfigCodec() {
|
||||
globalCodecMu.Lock()
|
||||
globalCodec = nil
|
||||
globalCodecMu.Unlock()
|
||||
}
|
||||
// 它清的是包级单例。现在"关闭加密"通过不注入（或注入 nil）表达：
|
||||
//
|
||||
// rt.SetCodec(nil) → config.codecOf() == nil
|
||||
// cfgReg.SetCodec(nil)
|
||||
//
|
||||
// 比"清空一个全局变量"更明确：状态属于对象，不属于进程。
|
||||
|
||||
Reference in New Issue
Block a user