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
2026-11-04 12:22:08 +08:00
parent 47afd67ca1
commit 5bdd0b5107
18 changed files with 665 additions and 158 deletions

View File

@ -15,17 +15,17 @@ import (
func TestAuditSecretsDetectsForeignKeyBackup(t *testing.T) {
// 本包的 codec 是**进程级全局**,测试必须还原现场,
// 否则会把密钥泄漏给同包其它判据(实测:导致 GetInt 读到密文)。
t.Cleanup(security.ClearConfigCodec)
dir := t.TempDir()
keyA := []byte("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
keyB := []byte("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb")
// 机器 A:写入一条加密配置
security.ClearConfigCodec()
if _, err := security.InitConfigCodec(keyA); err != nil {
t.Fatal(err)
cA, cerr := security.NewConfigCodec(keyA, nil)
if cerr != nil {
t.Fatal(cerr)
}
regA := NewConfigRegistry(filepath.Join(dir, "config.db"))
regA.SetCodec(cA)
regA.RegisterDef(cfgDef("core.llm.api_key"))
if err := regA.Set("core.llm.api_key", "sk-machine-a"); err != nil {
t.Fatal(err)
@ -37,11 +37,12 @@ func TestAuditSecretsDetectsForeignKeyBackup(t *testing.T) {
regA.Close()
// 机器 B:同一份 db,但密钥不同
security.ClearConfigCodec()
if _, err := security.InitConfigCodec(keyB); err != nil {
t.Fatal(err)
cB, cerr := security.NewConfigCodec(keyB, nil)
if cerr != nil {
t.Fatal(cerr)
}
regB := NewConfigRegistry(filepath.Join(dir, "config.db"))
regB.SetCodec(cB)
defer regB.Close()
ok2, bad2, err := regB.AuditSecrets()
if err != nil {
@ -61,25 +62,27 @@ func TestAuditSecretsDetectsForeignKeyBackup(t *testing.T) {
// ★ 同一密钥下重启(正常恢复)必须全部可解 —— 不能把正常备份误报成坏。
func TestAuditSecretsCleanOnSameKey(t *testing.T) {
t.Cleanup(security.ClearConfigCodec)
dir := t.TempDir()
key := []byte("cccccccccccccccccccccccccccccccc")
security.ClearConfigCodec()
if _, err := security.InitConfigCodec(key); err != nil {
t.Fatal(err)
c, cerr := security.NewConfigCodec(key, nil)
if cerr != nil {
t.Fatal(cerr)
}
db := filepath.Join(dir, "config.db")
reg := NewConfigRegistry(db)
reg.SetCodec(c)
reg.RegisterDef(cfgDef("core.llm.api_key"))
if err := reg.Set("core.llm.api_key", "sk-1"); err != nil {
t.Fatal(err)
}
reg.Close()
if _, err := security.InitConfigCodec(key); err != nil {
t.Fatal(err)
cy, cerr := security.NewConfigCodec(key, nil)
if cerr != nil {
t.Fatal(cerr)
}
reg2 := NewConfigRegistry(db)
reg2.SetCodec(cy)
defer reg2.Close()
ok, bad, err := reg2.AuditSecrets()
if err != nil || bad != 0 || ok != 1 {

View File

@ -4,6 +4,7 @@ import (
"database/sql"
"encoding/json"
"fmt"
"github.com/JianFeeeee/HologramAgent/internal/security"
"log"
"os"
"path/filepath"
@ -64,6 +65,41 @@ type ConfigRegistry struct {
// 为何缓存成集合而不是每次查 def:写入是热路径,而 def 查询要拿锁;
// 且 secret 判定必须对**无 def 的键**也能生效(见 secretByKeyPattern)。
secrets map[string]bool
// codec 是配置落盘加密执行者(由 security 模块注入)。
//
// ★ 2026-11-04(T3.2):此前读 `security.ConfigCodec()` 包级单例。
// 那个单例绕开了内核统一挂载点 —— 本 Registry 属于哪个内核实例就用
// 哪个 codec,不该由"最后谁调了 InitConfigCodec"决定。
//
// ★ 为什么是字段注入而不是让 config import kstate:
// kstate 依赖 config(State.CfgReg 的类型),config 再 import kstate
// 就是 import cycle。所以方向是 config 只持有它需要的**能力**
// (一个 *security.Codec),由上层装配时塞进来。
codecMu sync.RWMutex
codec *security.Codec
}
// SetCodec 注入配置落盘加密执行者(security 模块装配时调用)。
//
// nil 合法:未启用加密时所有敏感项以明文落盘(并可由 IsEncrypted 看出)。
func (r *ConfigRegistry) SetCodec(c *security.Codec) {
if r == nil {
return
}
r.codecMu.Lock()
r.codec = c
r.codecMu.Unlock()
}
// codecOf 返回注入的 codec(未注入为 nil)。
func (r *ConfigRegistry) codecOf() *security.Codec {
if r == nil {
return nil
}
r.codecMu.RLock()
defer r.codecMu.RUnlock()
return r.codec
}
func NewConfigRegistry(dbPath string) *ConfigRegistry {
@ -211,7 +247,7 @@ func (r *ConfigRegistry) Register(key string, value interface{}) {
defer r.mu.Unlock()
stored := fmt.Sprint(value)
if r.isSecretKey(key) {
stored, _ = sealForStorage(key, stored)
stored, _ = r.sealForStorage(key, stored)
}
r.db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, key, stored)
}
@ -235,7 +271,7 @@ func (r *ConfigRegistry) registerDefLocked(def ConfigDef) {
// 默认值也要加密落盘(否则声明了 secret 的项一启动就是明文)。
stored := def.Default
if r.isSecretKey(def.Key) {
stored, _ = sealForStorage(def.Key, stored)
stored, _ = r.sealForStorage(def.Key, stored)
}
r.db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, def.Key, stored)
// 记录「本次运行确实为这个键铺了初始行」—— GetXxx 只对这类键回退到
@ -383,7 +419,7 @@ func (r *ConfigRegistry) Get(key string) (interface{}, error) {
return nil, err
}
// 敏感项在库里是密文 ⇒ 对调用方透明解密(读接口语义不变)。
if plain, oerr := openFromStorage(key, val); oerr == nil {
if plain, oerr := r.openFromStorage(key, val); oerr == nil {
return plain, nil
} else {
return nil, oerr
@ -399,7 +435,7 @@ func (r *ConfigRegistry) Set(key string, value interface{}) error {
stored := fmt.Sprint(value)
// ★ 敏感项在**写库前**加密:库文件里只有密文。
if r.isSecretKey(key) {
stored, _ = sealForStorage(key, stored)
stored, _ = r.sealForStorage(key, stored)
}
_, err := r.db.Exec(`INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)`, key, stored)
if err == nil && strings.HasPrefix(key, "core.llm.sources.") {
@ -554,7 +590,7 @@ func (r *ConfigRegistry) listPrefixLocked(prefix string) map[string]string {
for rows.Next() {
var k, v string
if err := rows.Scan(&k, &v); err == nil {
if plain, oerr := openFromStorage(k, v); oerr == nil {
if plain, oerr := r.openFromStorage(k, v); oerr == nil {
out[k] = plain
} else {
// 解不开就不给值:宁可缺失(可诊断)也不把密文当明文交出去。
@ -580,7 +616,7 @@ func (r *ConfigRegistry) Dump() map[string]interface{} {
// ★ 返回**明文**:Dump 的调用方都是内核内部可信路径
//(ToConfig 重建 LLMSource、WebUI 设置页、插件读自身/他人配置)。
// 本需求防的是「静态文件泄漏」,不是「内部读取」。
if plain, oerr := openFromStorage(k, v); oerr == nil {
if plain, oerr := r.openFromStorage(k, v); oerr == nil {
result[k] = plain
} else {
log.Printf("[config] Dump decrypt %s failed: %v", k, oerr)
@ -1076,7 +1112,7 @@ func (r *ConfigRegistry) GetString(key, defaultVal string) string {
if err != nil {
return defaultVal
}
if plain, oerr := openFromStorage(key, v); oerr == nil {
if plain, oerr := r.openFromStorage(key, v); oerr == nil {
return plain
}
return defaultVal
@ -1365,7 +1401,7 @@ func (r *ConfigRegistry) SetPluginConfig(name, key string, value interface{}) er
table := r.pluginTableName(name)
stored := fmt.Sprint(value)
if r.isSecretKey("plugin." + name + "." + key) {
stored, _ = sealForStorage("plugin."+name+"."+key, stored)
stored, _ = r.sealForStorage("plugin."+name+"."+key, stored)
}
_, err := r.db.Exec(fmt.Sprintf(`INSERT OR REPLACE INTO %s (key, value) VALUES (?, ?)`, table), key, stored)
return err
@ -1397,7 +1433,7 @@ func (p *PluginSettings) Get(key string) (interface{}, error) {
return nil, err
}
// 敏感项透明解密
if plain, oerr := openFromStorage("plugin."+p.name+"."+key, val); oerr == nil {
if plain, oerr := p.registry.openFromStorage("plugin."+p.name+"."+key, val); oerr == nil {
return plain, nil
} else {
return nil, oerr
@ -1410,7 +1446,7 @@ func (p *PluginSettings) Set(key string, value interface{}) error {
stored := fmt.Sprint(value)
// ★ 插件敏感项同样加密落盘(插件无感知:它 Set 明文,Get 也得到明文)。
if p.isSecretKeyLocal(key) {
stored, _ = sealForStorage("plugin."+p.name+"."+key, stored)
stored, _ = p.registry.sealForStorage("plugin."+p.name+"."+key, stored)
}
_, err := p.registry.db.Exec(fmt.Sprintf(`INSERT OR REPLACE INTO %s (key, value) VALUES (?, ?)`, p.table), key, stored)
return err
@ -1428,7 +1464,7 @@ func (p *PluginSettings) SetSecret(key string, value interface{}) error {
sealed := stored
if stored != "" {
var ok bool
sealed, ok = sealForStorage("plugin."+p.name+"."+key, stored)
sealed, ok = p.registry.sealForStorage("plugin."+p.name+"."+key, stored)
if !ok {
return fmt.Errorf("config: 密钥未装配,拒绝以明文存储敏感项 %q", key)
}
@ -1453,7 +1489,7 @@ func (p *PluginSettings) GetSecret(key string) (string, error) {
if err != nil {
return "", err
}
return openFromStorage("plugin."+p.name+"."+key, val)
return p.registry.openFromStorage("plugin."+p.name+"."+key, val)
}
func (p *PluginSettings) Remove(key string) error {
p.registry.mu.Lock()
@ -1496,7 +1532,7 @@ func (p *PluginSettings) RegisterDef(def ConfigDef) {
stored := def.Default
if p.registry.isSecretKey(qualified) {
stored, _ = sealForStorage(qualified, stored)
stored, _ = p.registry.sealForStorage(qualified, stored)
}
p.registry.db.Exec(fmt.Sprintf(`INSERT OR IGNORE INTO %s (key, value) VALUES (?, ?)`, p.table), localKey, stored)
}

View File

@ -113,9 +113,9 @@ func (p *PluginSettings) isSecretKeyLocal(key string) bool {
//
// 返回值语义:加密发生则 mem=false(调用方据此决定是否需回读校验);
// 非敏感键或未装配 codec 时原样返回。
func sealForStorage(key, value string) (string, bool) {
func (r *ConfigRegistry) sealForStorage(key, value string) (string, bool) {
if !security.IsEncrypted(value) {
c := security.ConfigCodec()
c := r.codecOf()
if c == nil || !c.Enabled() {
return value, false
}
@ -133,11 +133,11 @@ func sealForStorage(key, value string) (string, bool) {
// 非密文原样返回(**存量明文兼容**):老数据不需要一次性迁移。
// 密文但解不开 ⇒ **响亮失败**(返回错误而非密文),因为把密文
// 当明文交出去会让下游拿到垃圾(比如把 `enc:v1:...` 当 API key 发出去)。
func openFromStorage(key, stored string) (string, error) {
func (r *ConfigRegistry) openFromStorage(key, stored string) (string, error) {
if !security.IsEncrypted(stored) {
return stored, nil
}
c := security.ConfigCodec()
c := r.codecOf()
if c == nil || !c.Enabled() {
return "", security.ErrNoMasterKey
}
@ -164,7 +164,7 @@ func openFromStorage(key, stored string) (string, error) {
//
// 返回 (加密条数, 错误)。幂等:已加密的项不会被二次加密。
func (r *ConfigRegistry) EncryptExistingSecrets() (int, error) {
c := security.ConfigCodec()
c := r.codecOf()
if c == nil || !c.Enabled() {
return 0, security.ErrNoMasterKey
}
@ -243,7 +243,7 @@ func (r *ConfigRegistry) EncryptExistingSecrets() (int, error) {
//
// 幂等:已是当前钥的项不动。解不开的项**响亮计数**并跳过(不静默删)。
func (r *ConfigRegistry) RekeySecrets() (int, int, error) {
c := security.ConfigCodec()
c := r.codecOf()
if c == nil || !c.Enabled() {
return 0, 0, security.ErrNoMasterKey
}
@ -304,7 +304,7 @@ func (r *ConfigRegistry) RekeySecrets() (int, int, error) {
//
// 返回 (可解, 不可解)。不可解 > 0 就是密钥不匹配/缺代的硬信号。
func (r *ConfigRegistry) AuditSecrets() (int, int, error) {
c := security.ConfigCodec()
c := r.codecOf()
if c == nil || !c.Enabled() {
return 0, 0, security.ErrNoMasterKey
}
@ -393,16 +393,23 @@ func (r *ConfigRegistry) SecretKeys() []string {
// 「磁盘上确实是密文」。生产代码不得使用。
func (r *ConfigRegistry) DB() *sql.DB { return r.db }
// ResetTestCodec 为判据装配一把固定主密钥。
// NewTestCodec 造一把固定主密钥的配置 codec(供判据注入 Registry)。
//
// ★ 2026-11-04:从 ResetTestCodec 改名并改语义。
//
// 原实现调 security.InitConfigCodec 装**包级单例**(已删除)。现在返回
// 实例,由调用方 `reg.SetCodec(c)` 注入 —— 与生产注入路径一致。
//
// 单独放在非 _test 文件里,是因为 proc 包(另一个包)的端到端判据
// 也需要它 —— 跨包无法直接调 *_test.go 里的辅助函数。
func ResetTestCodec(t interface {
func NewTestCodec(t interface {
Helper()
Fatalf(string, ...interface{})
}) {
if _, err := security.InitConfigCodec(
[]byte("0123456789abcdef0123456789abcdef")); err != nil {
}) *security.Codec {
t.Helper()
c, err := security.NewConfigCodec([]byte("0123456789abcdef0123456789abcdef"), nil)
if err != nil {
t.Fatalf("装配测试 codec 失败: %v", err)
}
return c
}

View File

@ -12,18 +12,23 @@ import (
"github.com/JianFeeeee/HologramAgent/internal/security"
)
func testCodec(t *testing.T) {
// testCodec 造一把固定主密钥的 codec(不再装包级单例)。
func testCodec(t *testing.T) *security.Codec {
t.Helper()
if _, err := security.InitConfigCodec([]byte("0123456789abcdef0123456789abcdef")); err != nil {
c, err := security.NewConfigCodec([]byte("0123456789abcdef0123456789abcdef"), nil)
if err != nil {
t.Fatal(err)
}
return c
}
func newSecReg(t *testing.T) *ConfigRegistry {
t.Helper()
dir := t.TempDir()
testCodec(t)
return NewConfigRegistry(filepath.Join(dir, "config.db"))
r := NewConfigRegistry(filepath.Join(dir, "config.db"))
// 按生产路径注入(config 模块从 ks.Security.Codec() 取)。
r.SetCodec(testCodec(t))
return r
}
// 直接在 sqlite 层面读原始值(绕过 ConfigRegistry 的解密)。
@ -198,10 +203,12 @@ func TestWrongKeyFailsLoudly(t *testing.T) {
if err := r.Set("core.llm.api_key", "secret-value-1234567890"); err != nil {
t.Fatal(err)
}
// 换一把主密钥
if _, err := security.InitConfigCodec([]byte("ffffffffffffffffffffffffffffffff")); err != nil {
// 换一把主密钥(同一 Registry 上重新注入,模拟轮换后配置错配)
other, err := security.NewConfigCodec([]byte("ffffffffffffffffffffffffffffffff"), nil)
if err != nil {
t.Fatal(err)
}
r.SetCodec(other)
if _, err := r.Get("core.llm.api_key"); err == nil {
t.Fatal("换密钥后必须报错,不能把密文当明文返回")
}
@ -216,8 +223,7 @@ func TestWrongKeyFailsLoudly(t *testing.T) {
// ★ 判据:未装配 codec 时退化为明文读写(本地开发/测试不阻塞)。
func TestNoCodecDegradesToPlain(t *testing.T) {
dir := t.TempDir()
// 清空全局 codec
security.ClearConfigCodec()
// 不注入 codec = 未装配(原先是 ClearConfigCodec 清单例)
r := NewConfigRegistry(filepath.Join(dir, "c.db"))
if err := r.Set("core.llm.api_key", "plain-dev"); err != nil {
t.Fatal(err)
@ -375,9 +381,8 @@ func TestExplicitSetSecretIgnoresKeyName(t *testing.T) {
// 这是最危险的静默降级:插件以为存了密文,实际磁盘上是明文。
func TestSetSecretRefusesWithoutKey(t *testing.T) {
dir := t.TempDir()
security.ClearConfigCodec()
defer testCodec(t) // 复原,避免影响其它判据
// 不注入 codec = 未装配(原先是 ClearConfigCodec 清单例)。
// 每个 Registry 自带 codec,不再需要"复原全局状态"。
r := NewConfigRegistry(filepath.Join(dir, "c.db"))
ps := r.PluginConfig("demo4")
ps.RegisterDef(ConfigDef{Key: "enabled", Default: "1"})