security

type AuditEntry struct {
	// 操作上下文
	SessionID  string    `json:"session_id"`  // 会话唯一 ID(可为空)
	TurnNumber int       `json:"turn_number"` // 对话轮次(0 表示未知)
	Timestamp  time.Time `json:"timestamp"`   // 操作发生时间(UTC)

	// 操作信息
	ToolName  string `json:"tool_name"` // 工具名称,如 "Write","Edit","Bash"
	Operation string `json:"operation"` // 操作类型:"write"/"edit"/"read"/"execute"
	Resource  string `json:"resource"`  // 资源标识(文件路径,URL,数据库表名等)

	// 操作者(多用户/SaaS 场景使用,单用户可为空)
	ActorID string `json:"actor_id,omitempty"`

	// 审计结果
	Outcome string `json:"outcome"`          // "allowed"/"blocked"/"error"
	Reason  string `json:"reason,omitempty"` // 拦截/错误原因,如 "secret_detected:github-pat"

	// 可扩展字段(跨行业专用).
	// 仓储场景示例:{"sku": "SKU-001", "qty_before": "100", "qty_after": "80"}
	// 医疗场景示例:{"patient_id_hash": "abc123", "phi_type": "diagnosis"}
	// 金融场景示例:{"account_hash": "xyz", "amount": "50000", "currency": "CNY"}
	Extra map[string]string `json:"extra,omitempty"`
}

type AuditSink interface {
	// Write 写入一条审计记录.
	// 实现必须是线程安全的(多个 goroutine 可能并发写入).
	// 返回 error 表示写入失败,调用方可以决定是否重试或降级.
	Write(entry AuditEntry) error

	// Close 刷新缓冲区并释放资源.
	// 对于同步写入实现,Close 可以是空操作.
	Close() error
}

type CompositeAuditSink struct {
	// contains filtered or unexported fields
}

type DefaultSecretGuard struct {

	// ExemptPaths 是豁免路径列表(路径前缀,如 "testdata/","/tmp/fixtures/").
	// 路径匹配任意一个前缀时跳过扫描,直接返回 nil, nil.
	// 精妙之处(CLEVER): 用前缀匹配而非 glob,避免引入 glob 解析复杂度.
	// 绝大多数豁免场景都是目录前缀(testdata/,fixtures/ 等),前缀足够.
	ExemptPaths []string

	// MaxBytes 覆盖默认的 MaxScanBytes.0 表示使用默认值.
	MaxBytes int

	// OnBlocked 是检测到秘密时的回调(可选).
	// 由引擎层注入--在 engine.New() 中设置为触发 "secret_scan_blocked" Observer 事件.
	// 工具层(FileWrite/FileEdit)不需要直接依赖 Observer,避免循环导入.
	//
	// 精妙之处(CLEVER): 回调而非直接依赖 EventObserver 接口--
	// security 包不导入 engine 包,engine 包在构造时将 observer.Event 注入为回调.
	// 这样 security 包保持零引擎依赖,可以被 pkg/memory 等其他包直接使用.
	// 替代方案:<security 包导入 engine.EventObserver 接口>
	// - 否决原因:形成循环导入(engine 包已经导入 security 包).
	OnBlocked func(path string, matches []SecretMatch)
	// contains filtered or unexported fields
}

type NoopAuditSink struct{}

type NoopSecretGuard struct{}

type SecretGuard interface {
	// Scan 扫描 content 中的敏感信息.
	// path 用于豁免规则判断(ExemptPaths 前缀匹配).
	// 返回命中的规则列表;返回 ErrContentTooLarge 表示内容超限;
	// 内容安全时返回 nil, nil.
	Scan(path, content string) ([]SecretMatch, error)

	// Redact 将 content 中匹配到的秘密替换为 [REDACTED],返回脱敏后的字符串.
	// 用于日志输出,错误消息展示时的保护性处理.
	// 不返回 error--脱敏本身不应阻断流程;超限内容直接原样返回(不脱敏).
	Redact(content string) string
}

type SecretMatch struct {
	// RuleID 是触发的规则 ID,如 "github-pat".
	RuleID string

	// Label 是人类可读的标签,如 "GitHub PAT".
	// 用于错误消息和审计日志(永远不包含实际秘密值).
	Label string
}

type SecretRule struct {
	// ID 是规则的唯一标识,对应 gitleaks rule ID(kebab-case).
	// 例:"github-pat","aws-access-token"
	ID string

	// Source 是正则表达式源字符串(Go re2 语法).
	// 精妙之处(CLEVER): 存储 source 而非编译后的 *regexp.Regexp,
	// 支持按需惰性编译(只在首次扫描时编译),也方便序列化和热更新.
	Source string

	// Flags 是正则 flag,通常为空(大多数规则区分大小写).
	// 仅当规则需要大小写不敏感时设置为 "i".
	Flags string
}