AI: 更新文档索引至 v1.0.3

AI.md

@@ -1,43 +1,54 @@
 # AI Coding Context: @go/safe
 
-本索引供 AI 模型理解 `@go/safe` 的设计规范，以生成符合本项目“安全、闭环、防御优先”哲学的代码。
+本索引供 AI 模型理解 `@go/safe` 的设计规范，以生成符合本项目“安全闭环、防御优先”哲学的代码。
 
-## 🤖 AI 行为准则
+## 🤖 AI 行为准则 (API 优先级)
 
-1.  **敏感数据全托管**：所有涉及密钥、密码、私人数据的处理，必须经由 `SafeBuf` 或其派生结构处理。
+1.  **优先使用 (Tier 1)**：处理敏感数据，首选 `NewSafeBufAndErase` 或 `NewSafeBuf`，配合 `Open()/Close()` 闭环操作。
-2.  **强制清理机制**：`SafeBuf.Open()` 返回的 `SecretPlaintext` 必须在业务使用完毕后显式调用 `Close()`。虽然存在 Finalizer 兜底，但不得依赖它作为主要的清理手段。
+2.  **安全约束**：
-3.  **系统级安全防御**：对于运行高敏感任务的进程，在 `init()` 阶段应优先调用 `DisableCoreDump()` 和 `LockMemory()`。
+    - `SafeBuf` 内部已自动处理 `LockMemory` 和 `ZeroMemory`，**严禁**对已托管的 `SafeBuf` 或其内部数据再次手动调用 `LockMemory`。
+    - 任何 `Open()` 获得的 `SecretPlaintext`，**必须**在同一作用域内 `defer sp.Close()`。
+3.  **系统与高级工具 (Tier 2)**：系统级防御（如 `DisableCoreDump`）应在 `init()` 调用。`ZeroMemory` 等底层 API 仅限高性能 buffer 复用场景。
 
-## 🛠 关键 API 设计约定
+## 🛠 API Reference
 
-| 类型 | 功能 | 语义约定 |
+### 安全存储 (SafeBuf)
-| :--- | :--- | :--- |
+- `func NewSafeBuf(raw []byte) *SafeBuf`：创建保护实例，需手动执行 `ZeroMemory` 擦除原始数据。
-| **内存保护** | 锁定/解锁页面 | `LockMemory`/`UnlockMemory` |
+- `func NewSafeBufAndErase(raw []byte) *SafeBuf`：创建实例并自动擦除原始明文，**首选 API**。
-| **转储防御** | 系统级防御 | `DisableCoreDump` |
+- `func NewSafeBufFromEncrypted(cipher, salt []byte) *SafeBuf`：从加密源重建保护实例。
-| **数据安全** | 敏感存储 | `NewSafeBuf`/`NewSafeBufAndErase` -> `Open()` -> `Close()` |
+- `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)
 
-*   **✅ 强制推荐 (内存立即擦除)**:
+*   **✅ 场景：标准敏感数据处理**:
     ```go
-    // 创建即擦除原始明文，杜绝残留
+    // 数据使用后立即销毁，无需二次操作
     sb := safe.NewSafeBufAndErase(secretData)
     defer sb.Close()
-    
+
     sp := sb.Open()
-    defer sp.Close() // 显式释放明文副本
+    defer sp.Close() // 闭环清理明文副本
+    process(sp.String())
     ```
 
-*   **⚠️ 谨慎使用**:
+*   **✅ 系统级防御**:
     ```go
-    // 若原始数据后续还需要使用，使用 NewSafeBuf，但必须手动擦除原始数据
+    func init() {
-    sb := safe.NewSafeBuf(secretData)
+        safe.DisableCoreDump()
-    safe.ZeroMemory(secretData) // 必须手动执行
+    }
-    defer sb.Close()
     ```
 
-*   **🤖 AI 强制指令**:
-    1.  **禁止残留**：绝不允许明文数据在内存中无保护停留。
-    2.  **API 优先级**：在代码生成时，凡涉及敏感数据传入，默认首选 `NewSafeBufAndErase`。
-    3.  **闭环调用**：任何 `Open()` 后的 `SecretPlaintext` 对象，生成的代码必须同时生成对应的 `defer sp.Close()` 调用。
-

go.mod

@@ -3,7 +3,7 @@ module apigo.cc/go/safe
 go 1.25.0
 
 require (
-	apigo.cc/go/rand v1.0.2 // indirect
+	apigo.cc/go/rand v1.0.3 // indirect
 	golang.org/x/crypto v0.50.0 // indirect
 	golang.org/x/sys v0.43.0 // indirect
 )