Files
knowledge-governance/internal/libraryrelease/restore_dispatch_activation.go
T
姚章浩 1c58f1ef7e fix(library): DS01 激活消费真实维护 journal 证据
为什么:v1 激活门只重算调用方自填 JSON 的 sha256,stopped/queue_drained 仍是声明,
不是排空事实。v2 证据只声明身份,事实改由 Store 读取维护窗口 journal(入口
drained+active_at_close=0、quiesce 全零且停写后复核、writer stop_requested+退出码)
与治理库实例维护行(同作业/实例/指纹/level、未释放、writer 集合一致)核出;缺受信
journal 根或构建身份未注入即失败关闭。

同时把 r38 激活移到维护窗口 held 的当下(barrier 点,真实只读观察),更新 PG/adapter
夹具与 F3 反例(伪造/替换摘要、错 writer 集合、未退出、未排空、过期、库/指纹/构建
不符、窗口已释放、journal 已 recovered、未配置受信根),并更名 beforeCommit 用例。
2026-11-02 18:48:10 +08:00

172 lines
7.7 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package libraryrelease
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"os"
"strings"
"time"
)
// 恢复派发激活证据(DS01-F3,协议版本 2)。
//
// 配置开关、"三个非空字符串"或调用方自填的 `stopped=true` 都不是独占证明。v2 证据
// 只允许**指向**一份由维护窗口写下的 journal:调用方声明目标身份、维护作业、journal
// 文件名/摘要与受控 writer 的不可变实例身份;真正的事实(入口关闭与排空、后台静默、
// 每个 writer 的退出观察)由 Store 直接读 journal 字节并解析取得,再用治理库的
// library_instance_maintenance 行把作业/实例/指纹/writer 集合钉死。
//
// 因此"把调用方 JSON 再 hash 一次"不再算核实:摘要只证明"读到的是这一份 journal",
// 事实来自 journal 本体与治理库行,而不是调用方的布尔字段。
//
// 边界:代码能核验 journal 完整性、目标/实例/治理库/构建身份、writer 集合一致性与
// 新鲜度;它不独立观测"外部 writer 此刻没在运行",但 journal 的入口 drain(
// active_at_close=0)、quiesce 零点与退出码是维护链自己的受控观察,且窗口必须仍处于
// held(已恢复/释放的窗口不构成"旧 writer 已停"的证据)。
const RestoreDispatchActivationMaxAge = 2 * time.Hour
const RestoreDispatchActivationProtocolVersion = 2
// RestoreDispatchWriterDrain 是调用方对"旧 writer 集合"的声明:只给身份,不给结论。
// InstanceID 必须等于 journal 里登记的不可变 writer 身份(容器/进程 ID)。
type RestoreDispatchWriterDrain struct {
Name string `json:"name"`
Kind string `json:"kind"`
InstanceID string `json:"instance_id"`
}
type RestoreDispatchActivationEvidence struct {
ProtocolVersion int `json:"protocol_version"`
TargetIdentity string `json:"target_identity"`
TargetFingerprint string `json:"target_fingerprint"`
TargetInstance string `json:"target_instance"`
GovernanceDatabase string `json:"governance_database"`
ProtocolBuild string `json:"protocol_build"`
AttestedBy string `json:"attested_by"`
AttestedAt time.Time `json:"attested_at"`
MaintenanceJob string `json:"maintenance_job"`
MaintenanceJournal string `json:"maintenance_journal"`
MaintenanceJournalSHA256 string `json:"maintenance_journal_sha256"`
Writers []RestoreDispatchWriterDrain `json:"writers"`
}
func (e RestoreDispatchActivationEvidence) Validate(now time.Time, maxAge time.Duration) error {
if e.ProtocolVersion != RestoreDispatchActivationProtocolVersion {
return fmt.Errorf("restore dispatch activation protocol version %d is not supported", e.ProtocolVersion)
}
for name, value := range map[string]string{
"target identity": e.TargetIdentity, "target fingerprint": e.TargetFingerprint,
"target instance": e.TargetInstance, "governance database": e.GovernanceDatabase,
"protocol build": e.ProtocolBuild, "attested by": e.AttestedBy,
"maintenance job": e.MaintenanceJob, "maintenance journal": e.MaintenanceJournal,
"maintenance journal digest": e.MaintenanceJournalSHA256,
} {
if strings.TrimSpace(value) == "" {
return fmt.Errorf("restore dispatch activation evidence lacks %s", name)
}
}
if !isHex64(e.TargetFingerprint) {
return errors.New("restore dispatch activation target fingerprint is not a sha256 hex string")
}
if !isHex64(e.MaintenanceJournalSHA256) {
return errors.New("restore dispatch activation maintenance journal digest is not a sha256 hex string")
}
if !validActivationID(e.MaintenanceJob) {
return errors.New("restore dispatch activation maintenance job id is invalid")
}
// journal 只能按作业名定位在同一受信根目录里;带路径分隔符/相对引用会绕开
// Store 配置的证据根,让"来源"变成调用方随手给的任意文件。
if e.MaintenanceJournal != e.MaintenanceJob+".json" {
return errors.New("restore dispatch activation maintenance journal is not the job journal")
}
if len(e.Writers) == 0 || len(e.Writers) > 256 {
return errors.New("restore dispatch activation lists no controlled writers")
}
names := map[string]bool{}
instances := map[string]bool{}
for _, writer := range e.Writers {
if strings.TrimSpace(writer.Name) == "" || strings.TrimSpace(writer.Kind) == "" ||
strings.TrimSpace(writer.InstanceID) == "" {
return errors.New("restore dispatch activation writer lacks name, kind or instance id")
}
if !validActivationID(writer.InstanceID) {
return errors.New("restore dispatch activation writer instance id is invalid")
}
if names[writer.Name] {
return fmt.Errorf("restore dispatch activation writer %s is listed twice", writer.Name)
}
names[writer.Name] = true
if instances[writer.InstanceID] {
return fmt.Errorf("restore dispatch activation writer instance %s is listed twice", writer.InstanceID)
}
instances[writer.InstanceID] = true
}
if e.AttestedAt.IsZero() || e.AttestedAt.After(now.Add(5*time.Minute)) {
return errors.New("restore dispatch activation attestation time is not credible")
}
if maxAge <= 0 {
maxAge = RestoreDispatchActivationMaxAge
}
if now.Sub(e.AttestedAt) > maxAge {
return fmt.Errorf("restore dispatch activation evidence is older than %s", maxAge)
}
return nil
}
// LoadRestoreDispatchActivationEvidence 读取并核验证据文件字节摘要。expectedDigest 必须
// 与文件实际 sha256 相同;不接受"文件里写的摘要"。
func LoadRestoreDispatchActivationEvidence(path, expectedDigest string, now time.Time, maxAge time.Duration) (RestoreDispatchActivationEvidence, error) {
var evidence RestoreDispatchActivationEvidence
if strings.TrimSpace(path) == "" || strings.TrimSpace(expectedDigest) == "" {
return evidence, errors.New("restore dispatch activation requires an evidence file and its digest")
}
raw, err := os.ReadFile(path)
if err != nil {
return evidence, fmt.Errorf("read restore dispatch activation evidence: %w", err)
}
sum := sha256.Sum256(raw)
if got := hex.EncodeToString(sum[:]); got != strings.ToLower(strings.TrimSpace(expectedDigest)) {
return evidence, errors.New("restore dispatch activation evidence digest does not match the file")
}
decoder := json.NewDecoder(strings.NewReader(string(raw)))
decoder.DisallowUnknownFields()
if err := decoder.Decode(&evidence); err != nil {
return RestoreDispatchActivationEvidence{}, fmt.Errorf("parse restore dispatch activation evidence: %w", err)
}
if err := evidence.Validate(now, maxAge); err != nil {
return RestoreDispatchActivationEvidence{}, err
}
return evidence, nil
}
// CanonicalBytes 是写入台账的规范字节(同一份证据只有一种序列化)。
func (e RestoreDispatchActivationEvidence) CanonicalBytes() ([]byte, error) {
return json.Marshal(e)
}
func isHex64(value string) bool {
if len(value) != 64 || strings.ToLower(value) != value {
return false
}
_, err := hex.DecodeString(value)
return err == nil
}
// validActivationID 与维护 journal 的作业/服务 ID 同一字符集:证据里出现的身份
// 必须能原样出现在 journal 中,不能靠空格/路径字符制造"看起来不同"的别名。
func validActivationID(value string) bool {
if len(value) == 0 || len(value) > 128 {
return false
}
for _, r := range value {
if !(r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' || r == '-' || r == '_') {
return false
}
}
return true
}