feat: 客户端加密 encrypted 字段，数据库只存密文 (v0.5.0)

- 新增 src/crypto.rs：AES-256-GCM 加解密 + Argon2id 密钥派生 + OS Keychain 读写
- 新增 `secrets init` 命令：输入 Master Password，派生 Master Key 存入 Keychain
- 新增 `secrets migrate-encrypt` 命令：将旧明文 JSONB 数据批量加密
- 修改 db.rs：encrypted 列 JSONB → BYTEA，新增 kv_config 表（存 Argon2id salt）
- 修改 models.rs：encrypted 字段类型 Value → Vec<u8>
- 修改 add/update：写入前 encrypt_json，update 读取后 decrypt → 合并 → 重新加密
- 修改 search：按需解密，未解密时显示 _encrypted:true/_key_count:N
- 通过 6 个 crypto 单元测试（加解密、JSON roundtrip、Argon2id 确定性）

Made-with: Cursor

src/commands/add.rs

@@ -3,6 +3,7 @@ use serde_json::{Map, Value, json};
 use sqlx::PgPool;
 use std::fs;
 
+use crate::crypto;
 use crate::output::OutputMode;
 
 /// Parse "key=value" entries. Value starting with '@' reads from file.
@@ -24,7 +25,7 @@ pub(crate) fn parse_kv(entry: &str) -> Result<(String, String)> {
     Ok((key.to_string(), value))
 }
 
-fn build_json(entries: &[String]) -> Result<Value> {
+pub(crate) fn build_json(entries: &[String]) -> Result<Value> {
     let mut map = Map::new();
     for entry in entries {
         let (key, value) = parse_kv(entry)?;
@@ -43,9 +44,12 @@ pub struct AddArgs<'a> {
     pub output: OutputMode,
 }
 
-pub async fn run(pool: &PgPool, args: AddArgs<'_>) -> Result<()> {
+pub async fn run(pool: &PgPool, args: AddArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
     let metadata = build_json(args.meta_entries)?;
-    let encrypted = build_json(args.secret_entries)?;
+    let secret_json = build_json(args.secret_entries)?;
+
+    // Encrypt the secret JSON before storing
+    let encrypted_bytes = crypto::encrypt_json(master_key, &secret_json)?;
 
     tracing::debug!(args.namespace, args.kind, args.name, "upserting record");
 
@@ -66,7 +70,7 @@ pub async fn run(pool: &PgPool, args: AddArgs<'_>) -> Result<()> {
     .bind(args.name)
     .bind(args.tags)
     .bind(&metadata)
-    .bind(&encrypted)
+    .bind(&encrypted_bytes)
     .execute(pool)
     .await?;
 

src/commands/init.rs

@@ -0,0 +1,62 @@
+use anyhow::{Context, Result};
+use rand::RngExt;
+use sqlx::PgPool;
+
+use crate::{crypto, db};
+
+pub async fn run(pool: &PgPool) -> Result<()> {
+    println!("Initializing secrets master key...");
+    println!();
+
+    // Read password (no echo)
+    let password =
+        rpassword::prompt_password("Enter master password: ").context("failed to read password")?;
+    if password.is_empty() {
+        anyhow::bail!("Master password must not be empty.");
+    }
+    let confirm = rpassword::prompt_password("Confirm master password: ")
+        .context("failed to read password confirmation")?;
+    if password != confirm {
+        anyhow::bail!("Passwords do not match.");
+    }
+
+    // Get or create Argon2id salt
+    let salt = match db::load_argon2_salt(pool).await? {
+        Some(existing) => {
+            println!("Found existing salt in database (not the first device).");
+            existing
+        }
+        None => {
+            println!("Generating new Argon2id salt and storing in database...");
+            let mut salt = vec![0u8; 16];
+            rand::rng().fill(&mut salt[..]);
+            db::store_argon2_salt(pool, &salt).await?;
+            salt
+        }
+    };
+
+    // Derive master key
+    print!("Deriving master key (Argon2id, this takes a moment)... ");
+    let master_key = crypto::derive_master_key(&password, &salt)?;
+    println!("done.");
+
+    // Store in OS Keychain
+    crypto::store_master_key(&master_key)?;
+
+    // Self-test: encrypt and decrypt a canary value
+    let canary = b"secrets-cli-canary";
+    let enc = crypto::encrypt(&master_key, canary)?;
+    let dec = crypto::decrypt(&master_key, &enc)?;
+    if dec != canary {
+        anyhow::bail!("Self-test failed: encryption roundtrip mismatch");
+    }
+
+    println!();
+    println!("Master key stored in OS Keychain.");
+    println!("You can now use `secrets add` / `secrets search` commands.");
+    println!();
+    println!("IMPORTANT: Remember your master password — it is not stored anywhere.");
+    println!("           On a new device, run `secrets init` with the same password.");
+
+    Ok(())
+}

src/commands/migrate_encrypt.rs

@@ -0,0 +1,85 @@
+use anyhow::Result;
+use sqlx::PgPool;
+use uuid::Uuid;
+
+use crate::crypto;
+
+/// Row fetched for migration
+#[derive(sqlx::FromRow)]
+struct MigrateRow {
+    id: Uuid,
+    namespace: String,
+    kind: String,
+    name: String,
+    encrypted: Vec<u8>,
+}
+
+/// Encrypt any records whose `encrypted` column contains raw (unencrypted) bytes.
+///
+/// After the schema migration, old JSONB rows were stored as raw UTF-8 bytes.
+/// A valid AES-256-GCM blob is always at least 28 bytes (12 nonce + 16 tag).
+/// We attempt to decrypt each row; if decryption fails, we assume it's plaintext
+/// JSON and re-encrypt it.
+pub async fn run(pool: &PgPool, master_key: &[u8; 32]) -> Result<()> {
+    println!("Scanning for unencrypted secret rows...");
+
+    let rows: Vec<MigrateRow> =
+        sqlx::query_as("SELECT id, namespace, kind, name, encrypted FROM secrets")
+            .fetch_all(pool)
+            .await?;
+
+    let total = rows.len();
+    let mut migrated = 0usize;
+    let mut already_encrypted = 0usize;
+    let mut skipped_empty = 0usize;
+
+    for row in rows {
+        if row.encrypted.is_empty() {
+            skipped_empty += 1;
+            continue;
+        }
+
+        // Try to decrypt; success → already encrypted, skip
+        if crypto::decrypt_json(master_key, &row.encrypted).is_ok() {
+            already_encrypted += 1;
+            continue;
+        }
+
+        // Treat as plaintext JSON bytes (from schema migration copy)
+        let json_str = String::from_utf8(row.encrypted.clone()).map_err(|_| {
+            anyhow::anyhow!(
+                "Row [{}/{}/{}]: encrypted column contains non-UTF-8 bytes that are also not valid ciphertext. Manual inspection required.",
+                row.namespace, row.kind, row.name
+            )
+        })?;
+
+        let value: serde_json::Value = serde_json::from_str(&json_str).map_err(|e| {
+            anyhow::anyhow!(
+                "Row [{}/{}/{}]: failed to parse as JSON: {}",
+                row.namespace,
+                row.kind,
+                row.name,
+                e
+            )
+        })?;
+
+        let encrypted_bytes = crypto::encrypt_json(master_key, &value)?;
+
+        sqlx::query("UPDATE secrets SET encrypted = $1, updated_at = NOW() WHERE id = $2")
+            .bind(&encrypted_bytes)
+            .bind(row.id)
+            .execute(pool)
+            .await?;
+
+        println!("  Encrypted: [{}/{}] {}", row.namespace, row.kind, row.name);
+        migrated += 1;
+    }
+
+    println!();
+    println!(
+        "Done. Total: {total}, encrypted this run: {migrated}, \
+         already encrypted: {already_encrypted}, empty (skipped): {skipped_empty}"
+    );
+
+    Ok(())
+}

src/commands/mod.rs

@@ -1,5 +1,7 @@
 pub mod add;
 pub mod config;
 pub mod delete;
+pub mod init;
+pub mod migrate_encrypt;
 pub mod search;
 pub mod update;

src/commands/search.rs

@@ -2,6 +2,7 @@ use anyhow::Result;
 use serde_json::{Value, json};
 use sqlx::PgPool;
 
+use crate::crypto;
 use crate::models::Secret;
 use crate::output::OutputMode;
 
@@ -20,7 +21,7 @@ pub struct SearchArgs<'a> {
     pub output: OutputMode,
 }
 
-pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
+pub async fn run(pool: &PgPool, args: SearchArgs<'_>, master_key: Option<&[u8; 32]>) -> Result<()> {
     let mut conditions: Vec<String> = Vec::new();
     let mut idx: i32 = 1;
 
@@ -92,14 +93,14 @@ pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
 
     // -f/--field: extract specific field values directly
     if !args.fields.is_empty() {
-        return print_fields(&rows, args.fields);
+        return print_fields(&rows, args.fields, master_key);
     }
 
     match args.output {
         OutputMode::Json | OutputMode::JsonCompact => {
             let arr: Vec<Value> = rows
                 .iter()
-                .map(|r| to_json(r, args.show_secrets, args.summary))
+                .map(|r| to_json(r, args.show_secrets, args.summary, master_key))
                 .collect();
             let out = if args.output == OutputMode::Json {
                 serde_json::to_string_pretty(&arr)?
@@ -116,7 +117,7 @@ pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
                 );
             }
             if let Some(row) = rows.first() {
-                print_env(row, args.show_secrets)?;
+                print_env(row, args.show_secrets, master_key)?;
             } else {
                 eprintln!("No records found.");
             }
@@ -127,7 +128,7 @@ pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
                 return Ok(());
             }
             for row in &rows {
-                print_text(row, args.show_secrets, args.summary)?;
+                print_text(row, args.show_secrets, args.summary, master_key)?;
             }
             println!("{} record(s) found.", rows.len());
             if rows.len() == args.limit as usize {
@@ -143,7 +144,24 @@ pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
     Ok(())
 }
 
-fn to_json(row: &Secret, show_secrets: bool, summary: bool) -> Value {
+/// Decrypt the encrypted blob for a row. Returns an empty object on empty blobs.
+/// Returns an error value on decrypt failure (so callers can decide how to handle).
+fn try_decrypt(row: &Secret, master_key: Option<&[u8; 32]>) -> Result<Value> {
+    if row.encrypted.is_empty() {
+        return Ok(Value::Object(Default::default()));
+    }
+    let key = master_key.ok_or_else(|| {
+        anyhow::anyhow!("master key required to decrypt secrets (run `secrets init`)")
+    })?;
+    crypto::decrypt_json(key, &row.encrypted)
+}
+
+fn to_json(
+    row: &Secret,
+    show_secrets: bool,
+    summary: bool,
+    master_key: Option<&[u8; 32]>,
+) -> Value {
     if summary {
         let desc = row
             .metadata
@@ -163,14 +181,12 @@ fn to_json(row: &Secret, show_secrets: bool, summary: bool) -> Value {
     }
 
     let secrets_val = if show_secrets {
-        row.encrypted.clone()
+        match try_decrypt(row, master_key) {
+            Ok(v) => v,
+            Err(e) => json!({"_error": e.to_string()}),
+        }
     } else {
-        let keys: Vec<&str> = row
-            .encrypted
-            .as_object()
-            .map(|m| m.keys().map(|k| k.as_str()).collect())
-            .unwrap_or_default();
-        json!({"_hidden_keys": keys})
+        json!({"_encrypted": true, "_key_count": encrypted_key_count(row, master_key)})
     };
 
     json!({
@@ -186,7 +202,24 @@ fn to_json(row: &Secret, show_secrets: bool, summary: bool) -> Value {
     })
 }
 
-fn print_text(row: &Secret, show_secrets: bool, summary: bool) -> Result<()> {
+/// Return the number of keys in the encrypted JSON (decrypts to count; 0 on failure).
+fn encrypted_key_count(row: &Secret, master_key: Option<&[u8; 32]>) -> usize {
+    if row.encrypted.is_empty() {
+        return 0;
+    }
+    let Some(key) = master_key else { return 0 };
+    match crypto::decrypt_json(key, &row.encrypted) {
+        Ok(Value::Object(m)) => m.len(),
+        _ => 0,
+    }
+}
+
+fn print_text(
+    row: &Secret,
+    show_secrets: bool,
+    summary: bool,
+    master_key: Option<&[u8; 32]>,
+) -> Result<()> {
     println!("[{}/{}] {}", row.namespace, row.kind, row.name);
     if summary {
         let desc = row
@@ -214,22 +247,14 @@ fn print_text(row: &Secret, show_secrets: bool, summary: bool) -> Result<()> {
                 serde_json::to_string_pretty(&row.metadata)?
             );
         }
-        if show_secrets {
-            println!(
-                "  secrets:  {}",
-                serde_json::to_string_pretty(&row.encrypted)?
-            );
-        } else {
-            let keys: Vec<String> = row
-                .encrypted
-                .as_object()
-                .map(|m| m.keys().cloned().collect())
-                .unwrap_or_default();
-            if !keys.is_empty() {
-                println!(
-                    "  secrets:  [{}]  (--show-secrets to reveal)",
-                    keys.join(", ")
-                );
+        if !row.encrypted.is_empty() {
+            if show_secrets {
+                match try_decrypt(row, master_key) {
+                    Ok(v) => println!("  secrets:  {}", serde_json::to_string_pretty(&v)?),
+                    Err(e) => println!("  secrets:  [decrypt error: {}]", e),
+                }
+            } else {
+                println!("  secrets:  [encrypted]  (--show-secrets to reveal)");
             }
         }
         println!(
@@ -241,7 +266,7 @@ fn print_text(row: &Secret, show_secrets: bool, summary: bool) -> Result<()> {
     Ok(())
 }
 
-fn print_env(row: &Secret, show_secrets: bool) -> Result<()> {
+fn print_env(row: &Secret, show_secrets: bool, master_key: Option<&[u8; 32]>) -> Result<()> {
     let prefix = row.name.to_uppercase().replace(['-', '.'], "_");
     if let Some(meta) = row.metadata.as_object() {
         for (k, v) in meta {
@@ -249,27 +274,40 @@ fn print_env(row: &Secret, show_secrets: bool) -> Result<()> {
             println!("{}={}", key, v.as_str().unwrap_or(&v.to_string()));
         }
     }
-    if show_secrets && let Some(enc) = row.encrypted.as_object() {
-        for (k, v) in enc {
-            let key = format!("{}_{}", prefix, k.to_uppercase().replace('-', "_"));
-            println!("{}={}", key, v.as_str().unwrap_or(&v.to_string()));
+    if show_secrets {
+        let decrypted = try_decrypt(row, master_key)?;
+        if let Some(enc) = decrypted.as_object() {
+            for (k, v) in enc {
+                let key = format!("{}_{}", prefix, k.to_uppercase().replace('-', "_"));
+                println!("{}={}", key, v.as_str().unwrap_or(&v.to_string()));
+            }
         }
     }
     Ok(())
 }
 
 /// Extract one or more field paths like `metadata.url` or `secret.token`.
-fn print_fields(rows: &[Secret], fields: &[String]) -> Result<()> {
+fn print_fields(rows: &[Secret], fields: &[String], master_key: Option<&[u8; 32]>) -> Result<()> {
     for row in rows {
+        // Decrypt once per row if any field requires it
+        let decrypted: Option<Value> = if fields
+            .iter()
+            .any(|f| f.starts_with("secret") || f.starts_with("encrypted"))
+        {
+            Some(try_decrypt(row, master_key)?)
+        } else {
+            None
+        };
+
         for field in fields {
-            let val = extract_field(row, field)?;
+            let val = extract_field(row, field, decrypted.as_ref())?;
             println!("{}", val);
         }
     }
     Ok(())
 }
 
-fn extract_field(row: &Secret, field: &str) -> Result<String> {
+fn extract_field(row: &Secret, field: &str, decrypted: Option<&Value>) -> Result<String> {
     let (section, key) = field.split_once('.').ok_or_else(|| {
         anyhow::anyhow!(
             "Invalid field path '{}'. Use metadata.<key> or secret.<key>",
@@ -279,7 +317,9 @@ fn extract_field(row: &Secret, field: &str) -> Result<String> {
 
     let obj = match section {
         "metadata" | "meta" => &row.metadata,
-        "secret" | "secrets" | "encrypted" => &row.encrypted,
+        "secret" | "secrets" | "encrypted" => {
+            decrypted.ok_or_else(|| anyhow::anyhow!("secret field requires master key"))?
+        }
         other => anyhow::bail!(
             "Unknown field section '{}'. Use 'metadata' or 'secret'",
             other

src/commands/update.rs

@@ -4,13 +4,14 @@ use sqlx::{FromRow, PgPool};
 use uuid::Uuid;
 
 use super::add::parse_kv;
+use crate::crypto;
 
 #[derive(FromRow)]
 struct UpdateRow {
     id: Uuid,
     tags: Vec<String>,
     metadata: Value,
-    encrypted: Value,
+    encrypted: Vec<u8>,
 }
 
 pub struct UpdateArgs<'a> {
@@ -25,7 +26,7 @@ pub struct UpdateArgs<'a> {
     pub remove_secrets: &'a [String],
 }
 
-pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
+pub async fn run(pool: &PgPool, args: UpdateArgs<'_>, master_key: &[u8; 32]) -> Result<()> {
     let row: Option<UpdateRow> = sqlx::query_as(
         r#"
         SELECT id, tags, metadata, encrypted
@@ -71,8 +72,13 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
     }
     let metadata = Value::Object(meta_map);
 
-    // Merge encrypted
-    let mut enc_map: Map<String, Value> = match row.encrypted {
+    // Decrypt existing encrypted blob, merge changes, re-encrypt
+    let existing_json = if row.encrypted.is_empty() {
+        Value::Object(Map::new())
+    } else {
+        crypto::decrypt_json(master_key, &row.encrypted)?
+    };
+    let mut enc_map: Map<String, Value> = match existing_json {
         Value::Object(m) => m,
         _ => Map::new(),
     };
@@ -83,7 +89,8 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
     for key in args.remove_secrets {
         enc_map.remove(key);
     }
-    let encrypted = Value::Object(enc_map);
+    let secret_json = Value::Object(enc_map);
+    let encrypted_bytes = crypto::encrypt_json(master_key, &secret_json)?;
 
     tracing::debug!(
         namespace = args.namespace,
@@ -101,7 +108,7 @@ pub async fn run(pool: &PgPool, args: UpdateArgs<'_>) -> Result<()> {
     )
     .bind(&tags)
     .bind(metadata)
-    .bind(encrypted)
+    .bind(encrypted_bytes)
     .bind(row.id)
     .execute(pool)
     .await?;

src/crypto.rs

@@ -0,0 +1,192 @@
+use aes_gcm::{
+    Aes256Gcm, Key, Nonce,
+    aead::{Aead, AeadCore, KeyInit, OsRng},
+};
+use anyhow::{Context, Result, bail};
+use argon2::{Argon2, Params, Version};
+use serde_json::Value;
+
+const KEYRING_SERVICE: &str = "secrets-cli";
+const KEYRING_USER: &str = "master-key";
+const NONCE_LEN: usize = 12;
+
+// ─── Argon2id key derivation ─────────────────────────────────────────────────
+
+/// Derive a 32-byte Master Key from a password and salt using Argon2id.
+/// Parameters: m=65536 KiB (64 MB), t=3, p=4 — OWASP recommended.
+pub fn derive_master_key(password: &str, salt: &[u8]) -> Result<[u8; 32]> {
+    let params = Params::new(65536, 3, 4, Some(32)).context("invalid Argon2id params")?;
+    let argon2 = Argon2::new(argon2::Algorithm::Argon2id, Version::V0x13, params);
+    let mut key = [0u8; 32];
+    argon2
+        .hash_password_into(password.as_bytes(), salt, &mut key)
+        .map_err(|e| anyhow::anyhow!("Argon2id derivation failed: {}", e))?;
+    Ok(key)
+}
+
+// ─── AES-256-GCM encrypt / decrypt ───────────────────────────────────────────
+
+/// Encrypt plaintext bytes with AES-256-GCM.
+/// Returns `nonce (12 B) || ciphertext+tag`.
+pub fn encrypt(master_key: &[u8; 32], plaintext: &[u8]) -> Result<Vec<u8>> {
+    let key = Key::<Aes256Gcm>::from_slice(master_key);
+    let cipher = Aes256Gcm::new(key);
+    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
+    let ciphertext = cipher
+        .encrypt(&nonce, plaintext)
+        .map_err(|e| anyhow::anyhow!("AES-256-GCM encryption failed: {}", e))?;
+    let mut out = Vec::with_capacity(NONCE_LEN + ciphertext.len());
+    out.extend_from_slice(&nonce);
+    out.extend_from_slice(&ciphertext);
+    Ok(out)
+}
+
+/// Decrypt `nonce (12 B) || ciphertext+tag` with AES-256-GCM.
+pub fn decrypt(master_key: &[u8; 32], data: &[u8]) -> Result<Vec<u8>> {
+    if data.len() < NONCE_LEN {
+        bail!(
+            "encrypted data too short ({}B); possibly corrupted",
+            data.len()
+        );
+    }
+    let (nonce_bytes, ciphertext) = data.split_at(NONCE_LEN);
+    let key = Key::<Aes256Gcm>::from_slice(master_key);
+    let cipher = Aes256Gcm::new(key);
+    let nonce = Nonce::from_slice(nonce_bytes);
+    cipher
+        .decrypt(nonce, ciphertext)
+        .map_err(|_| anyhow::anyhow!("decryption failed — wrong master key or corrupted data"))
+}
+
+// ─── JSON helpers ─────────────────────────────────────────────────────────────
+
+/// Serialize a JSON Value and encrypt it. Returns the encrypted blob.
+pub fn encrypt_json(master_key: &[u8; 32], value: &Value) -> Result<Vec<u8>> {
+    let bytes = serde_json::to_vec(value).context("serialize JSON for encryption")?;
+    encrypt(master_key, &bytes)
+}
+
+/// Decrypt an encrypted blob and deserialize it as a JSON Value.
+pub fn decrypt_json(master_key: &[u8; 32], data: &[u8]) -> Result<Value> {
+    let bytes = decrypt(master_key, data)?;
+    serde_json::from_slice(&bytes).context("deserialize decrypted JSON")
+}
+
+// ─── OS Keychain ──────────────────────────────────────────────────────────────
+
+/// Load the Master Key from the OS Keychain.
+/// Returns an error with a helpful message if it hasn't been initialized.
+pub fn load_master_key() -> Result<[u8; 32]> {
+    let entry =
+        keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER).context("create keychain entry")?;
+    let hex = entry.get_password().map_err(|_| {
+        anyhow::anyhow!("Master key not found in keychain. Run `secrets init` first.")
+    })?;
+    let bytes = hex::decode_hex(&hex)?;
+    if bytes.len() != 32 {
+        bail!(
+            "stored master key has unexpected length {}; re-run `secrets init`",
+            bytes.len()
+        );
+    }
+    let mut key = [0u8; 32];
+    key.copy_from_slice(&bytes);
+    Ok(key)
+}
+
+/// Store the Master Key in the OS Keychain (overwrites any existing value).
+pub fn store_master_key(key: &[u8; 32]) -> Result<()> {
+    let entry =
+        keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER).context("create keychain entry")?;
+    let hex = hex::encode_hex(key);
+    entry
+        .set_password(&hex)
+        .map_err(|e| anyhow::anyhow!("keychain write failed: {}", e))?;
+    Ok(())
+}
+
+/// Delete the Master Key from the OS Keychain (used by tests / reset).
+#[cfg(test)]
+pub fn delete_master_key() -> Result<()> {
+    let entry =
+        keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER).context("create keychain entry")?;
+    let _ = entry.delete_credential();
+    Ok(())
+}
+
+// ─── Minimal hex helpers (avoid extra dep) ────────────────────────────────────
+
+mod hex {
+    use anyhow::{Result, bail};
+
+    pub fn encode_hex(bytes: &[u8]) -> String {
+        bytes.iter().map(|b| format!("{:02x}", b)).collect()
+    }
+
+    pub fn decode_hex(s: &str) -> Result<Vec<u8>> {
+        if !s.len().is_multiple_of(2) {
+            bail!("hex string has odd length");
+        }
+        (0..s.len())
+            .step_by(2)
+            .map(|i| u8::from_str_radix(&s[i..i + 2], 16).map_err(|e| anyhow::anyhow!("{}", e)))
+            .collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn roundtrip_encrypt_decrypt() {
+        let key = [0x42u8; 32];
+        let plaintext = b"hello world";
+        let enc = encrypt(&key, plaintext).unwrap();
+        let dec = decrypt(&key, &enc).unwrap();
+        assert_eq!(dec, plaintext);
+    }
+
+    #[test]
+    fn encrypt_produces_different_ciphertexts() {
+        let key = [0x42u8; 32];
+        let plaintext = b"hello world";
+        let enc1 = encrypt(&key, plaintext).unwrap();
+        let enc2 = encrypt(&key, plaintext).unwrap();
+        // Different nonces → different ciphertexts
+        assert_ne!(enc1, enc2);
+    }
+
+    #[test]
+    fn wrong_key_fails_decryption() {
+        let key1 = [0x42u8; 32];
+        let key2 = [0x43u8; 32];
+        let enc = encrypt(&key1, b"secret").unwrap();
+        assert!(decrypt(&key2, &enc).is_err());
+    }
+
+    #[test]
+    fn json_roundtrip() {
+        let key = [0x42u8; 32];
+        let value = serde_json::json!({"token": "abc123", "password": "hunter2"});
+        let enc = encrypt_json(&key, &value).unwrap();
+        let dec = decrypt_json(&key, &enc).unwrap();
+        assert_eq!(dec, value);
+    }
+
+    #[test]
+    fn derive_master_key_deterministic() {
+        let salt = b"fixed_test_salt_";
+        let k1 = derive_master_key("password", salt).unwrap();
+        let k2 = derive_master_key("password", salt).unwrap();
+        assert_eq!(k1, k2);
+    }
+
+    #[test]
+    fn derive_master_key_different_passwords() {
+        let salt = b"fixed_test_salt_";
+        let k1 = derive_master_key("password1", salt).unwrap();
+        let k2 = derive_master_key("password2", salt).unwrap();
+        assert_ne!(k1, k2);
+    }
+}

src/db.rs

@@ -23,7 +23,7 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
             name        VARCHAR(256) NOT NULL,
             tags        TEXT[]       NOT NULL DEFAULT '{}',
             metadata    JSONB        NOT NULL DEFAULT '{}',
-            encrypted   JSONB        NOT NULL DEFAULT '{}',
+            encrypted   BYTEA        NOT NULL DEFAULT '\x',
             created_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
             updated_at  TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
             UNIQUE(namespace, kind, name)
@@ -35,11 +35,37 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
         EXCEPTION WHEN OTHERS THEN NULL;
         END $$;
 
+        -- Migrate encrypted column from JSONB to BYTEA if still JSONB type.
+        -- After migration, old plaintext rows will have their JSONB data
+        -- stored as raw bytes (not yet re-encrypted); run `secrets migrate-encrypt`
+        -- to encrypt them with the master key.
+        DO $$ BEGIN
+            IF EXISTS (
+                SELECT 1 FROM information_schema.columns
+                WHERE table_name = 'secrets'
+                  AND column_name = 'encrypted'
+                  AND data_type = 'jsonb'
+            ) THEN
+                ALTER TABLE secrets RENAME COLUMN encrypted TO encrypted_jsonb_old;
+                ALTER TABLE secrets ADD COLUMN encrypted BYTEA NOT NULL DEFAULT '\x';
+                -- Copy existing JSONB data as raw UTF-8 bytes so nothing is lost
+                UPDATE secrets SET encrypted = convert_to(encrypted_jsonb_old::text, 'UTF8');
+                ALTER TABLE secrets DROP COLUMN encrypted_jsonb_old;
+            END IF;
+        EXCEPTION WHEN OTHERS THEN NULL;
+        END $$;
+
         CREATE INDEX IF NOT EXISTS idx_secrets_namespace ON secrets(namespace);
         CREATE INDEX IF NOT EXISTS idx_secrets_kind ON secrets(kind);
         CREATE INDEX IF NOT EXISTS idx_secrets_tags ON secrets USING GIN(tags);
         CREATE INDEX IF NOT EXISTS idx_secrets_metadata ON secrets USING GIN(metadata jsonb_path_ops);
 
+        -- Key-value config table: stores Argon2id salt (shared across devices)
+        CREATE TABLE IF NOT EXISTS kv_config (
+            key   TEXT PRIMARY KEY,
+            value BYTEA NOT NULL
+        );
+
         CREATE TABLE IF NOT EXISTS audit_log (
             id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
             action      VARCHAR(32)  NOT NULL,
@@ -60,3 +86,25 @@ pub async fn migrate(pool: &PgPool) -> Result<()> {
     tracing::debug!("migrations complete");
     Ok(())
 }
+
+/// Load the Argon2id salt from the database.
+/// Returns None if not yet initialized.
+pub async fn load_argon2_salt(pool: &PgPool) -> Result<Option<Vec<u8>>> {
+    let row: Option<(Vec<u8>,)> =
+        sqlx::query_as("SELECT value FROM kv_config WHERE key = 'argon2_salt'")
+            .fetch_optional(pool)
+            .await?;
+    Ok(row.map(|(v,)| v))
+}
+
+/// Store the Argon2id salt in the database (only called once on first device init).
+pub async fn store_argon2_salt(pool: &PgPool, salt: &[u8]) -> Result<()> {
+    sqlx::query(
+        "INSERT INTO kv_config (key, value) VALUES ('argon2_salt', $1) \
+         ON CONFLICT (key) DO NOTHING",
+    )
+    .bind(salt)
+    .execute(pool)
+    .await?;
+    Ok(())
+}

src/main.rs

@@ -1,6 +1,7 @@
 mod audit;
 mod commands;
 mod config;
+mod crypto;
 mod db;
 mod models;
 mod output;
@@ -16,7 +17,10 @@ use output::resolve_output_mode;
     name = "secrets",
     version,
     about = "Secrets & config manager backed by PostgreSQL — optimised for AI agents",
-    after_help = "QUICK START (AI agents):
+    after_help = "QUICK START:
+  # First time setup (run once per device)
+  secrets init
+
   # Discover what namespaces / kinds exist
   secrets search --summary --limit 20
 
@@ -44,6 +48,24 @@ struct Cli {
 
 #[derive(Subcommand)]
 enum Commands {
+    /// Initialize master key on this device (run once per device).
+    ///
+    /// Prompts for a master password, derives a key with Argon2id, and stores
+    /// it in the OS Keychain. Use the same password on every device.
+    #[command(after_help = "EXAMPLES:
+  # First device: generates a new Argon2id salt and stores master key
+  secrets init
+
+  # Subsequent devices: reuses existing salt from the database
+  secrets init")]
+    Init,
+
+    /// Encrypt any pre-existing plaintext records in the database.
+    ///
+    /// Run this once after upgrading from a version that stored secrets as
+    /// plaintext JSONB. Requires `secrets init` to have been run first.
+    MigrateEncrypt,
+
     /// Add or update a record (upsert). Use -m for plaintext metadata, -s for secrets.
     #[command(after_help = "EXAMPLES:
   # Add a server
@@ -281,7 +303,7 @@ async fn main() -> Result<()> {
         .with_target(false)
         .init();
 
-    // config 子命令不需要数据库连接，提前处理
+    // config subcommand needs no database or master key
     if let Commands::Config { action } = &cli.command {
         let cmd_action = match action {
             ConfigAction::SetDb { url } => {
@@ -297,7 +319,21 @@ async fn main() -> Result<()> {
     let pool = db::create_pool(&db_url).await?;
     db::migrate(&pool).await?;
 
+    // init needs a pool but sets up the master key — handle before loading it
+    if let Commands::Init = &cli.command {
+        return commands::init::run(&pool).await;
+    }
+
+    // All remaining commands require the master key from the OS Keychain
+    let master_key = crypto::load_master_key()?;
+
     match &cli.command {
+        Commands::Init | Commands::Config { .. } => unreachable!(),
+
+        Commands::MigrateEncrypt => {
+            commands::migrate_encrypt::run(&pool, &master_key).await?;
+        }
+
         Commands::Add {
             namespace,
             kind,
@@ -321,9 +357,11 @@ async fn main() -> Result<()> {
                     secret_entries: secrets,
                     output: out,
                 },
+                &master_key,
             )
             .await?;
         }
+
         Commands::Search {
             namespace,
             kind,
@@ -339,7 +377,6 @@ async fn main() -> Result<()> {
             output,
         } => {
             let _span = tracing::info_span!("cmd", command = "search").entered();
-            // -f implies --show-secrets when any field path starts with "secret"
             let show = *show_secrets || fields.iter().any(|f| f.starts_with("secret"));
             let out = resolve_output_mode(output.as_deref())?;
             commands::search::run(
@@ -358,9 +395,11 @@ async fn main() -> Result<()> {
                     sort,
                     output: out,
                 },
+                Some(&master_key),
             )
             .await?;
         }
+
         Commands::Delete {
             namespace,
             kind,
@@ -370,6 +409,7 @@ async fn main() -> Result<()> {
                 tracing::info_span!("cmd", command = "delete", %namespace, %kind, %name).entered();
             commands::delete::run(&pool, namespace, kind, name).await?;
         }
+
         Commands::Update {
             namespace,
             kind,
@@ -396,10 +436,10 @@ async fn main() -> Result<()> {
                     secret_entries: secrets,
                     remove_secrets,
                 },
+                &master_key,
             )
             .await?;
         }
-        Commands::Config { .. } => unreachable!(),
     }
 
     Ok(())

src/models.rs

@@ -11,7 +11,9 @@ pub struct Secret {
     pub name: String,
     pub tags: Vec<String>,
     pub metadata: Value,
-    pub encrypted: Value,
+    /// AES-256-GCM ciphertext: nonce(12B) || ciphertext+tag
+    /// Decrypt with crypto::decrypt_json() before use.
+    pub encrypted: Vec<u8>,
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
 }