diff --git a/AI.md b/AI.md deleted file mode 100644 index e917036..0000000 --- a/AI.md +++ /dev/null @@ -1,54 +0,0 @@ -# AI Coding Context: @go/safe (v1.0.4) - -本索引供 AI 模型理解 `@go/safe` 的设计规范,以生成符合本项目“安全闭环、防御优先”哲学的代码。 - -## 🤖 AI 行为准则 (API 优先级) - -1. **优先使用 (Tier 1)**:处理敏感数据,首选 `NewSafeBufAndErase` 或 `NewSafeBuf`,配合 `Open()/Close()` 闭环操作。 -2. **安全约束**: - - `SafeBuf` 内部已自动处理 `LockMemory` 和 `ZeroMemory`,**严禁**对已托管的 `SafeBuf` 或其内部数据再次手动调用 `LockMemory`。 - - 任何 `Open()` 获得的 `SecretPlaintext`,**必须**在同一作用域内 `defer secret.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 (safeBuf *SafeBuf) Open() *SecretPlaintext`:解密 SafeBuf。**调用后必须 `defer secret.Close()`**。 -- `func (safeBuf *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) - -* **✅ 场景:标准敏感数据处理**: - ```go - // 数据使用后立即销毁,无需二次操作 - safeBuf := safe.NewSafeBufAndErase(secretData) - defer safeBuf.Close() - - secret := safeBuf.Open() - defer secret.Close() // 闭环清理明文副本 - process(secret.String()) - ``` - -* **✅ 系统级防御**: - ```go - func init() { - _ = safe.DisableCoreDump() - } - ``` -