safe/AI.md

AI Coding Context: @go/safe

本索引供 AI 模型理解 @go/safe 的设计规范，以生成符合本项目“安全闭环、防御优先”哲学的代码。

🤖 AI 行为准则 (API 优先级)

1. 优先使用 (Tier 1)：处理敏感数据，首选 NewSafeBufAndErase 或 NewSafeBuf，配合 Open()/Close() 闭环操作。
2. 安全约束：
   • SafeBuf 内部已自动处理 LockMemory 和 ZeroMemory，严禁对已托管的 SafeBuf 或其内部数据再次手动调用 LockMemory。
   • 任何 Open() 获得的 SecretPlaintext，必须在同一作用域内 defer sp.Close()。
3. 系统与高级工具 (Tier 2)：系统级防御（如 DisableCoreDump）应在 init() 调用。ZeroMemory 等底层 API 仅限高性能 buffer 复用场景。

🛠 API Reference

安全存储 (SafeBuf)

• func NewSafeBuf(raw []byte) *SafeBuf：创建保护实例，需手动执行 ZeroMemory 擦除原始数据。
• func NewSafeBufAndErase(raw []byte) *SafeBuf：创建实例并自动擦除原始明文，首选 API。
• func NewSafeBufFromEncrypted(cipher, salt []byte) *SafeBuf：从加密源重建保护实例。
• func NewSafeString(raw []byte) (*SecretPlaintext, string)：创建临时的敏感字符串。
• func (sb *SafeBuf) Open() *SecretPlaintext：解密 SafeBuf。调用后必须 defer sp.Close()。
• func (sb *SafeBuf) Close()：销毁加密实例并擦除加密内容。

内存管理与防御

• func LockMemory(buf []byte) error：锁定内存页，防止 Swap。
• func UnlockMemory(buf []byte) error：解锁内存页。
• func DisableCoreDump() error：禁止进程核心转储。
• func ZeroMemory(buf []byte)：强力覆盖内存。用于 NewSafeBuf 后清理原数据或 buffer 复用。

辅助与底层工具

• func MakeSafeToken(size int) []byte：生成高熵随机令牌。
• func SetSafeBufObfuscator(encrypt func([]byte) ([]byte, []byte), decrypt func([]byte, []byte) []byte)：设置自定义混淆器。
• func EncryptChaCha20(raw []byte, key []byte, salt []byte) []byte：ChaCha20 加密。
• func DecryptChaCha20(cipher []byte, key []byte, salt []byte) []byte：ChaCha20 解密。

🧩 典型模式 (Best Practices)

• ✅ 场景：标准敏感数据处理:

  // 数据使用后立即销毁，无需二次操作
  sb := safe.NewSafeBufAndErase(secretData)
  defer sb.Close()
  
  sp := sb.Open()
  defer sp.Close() // 闭环清理明文副本
  process(sp.String())
  

• ✅ 系统级防御:

  func init() {
      safe.DisableCoreDump()
  }