feat(totp): support origin-bound 2FA for bridge

Author: cuihairu

cli/src/commands/bridge.rs

@@ -125,6 +125,7 @@ struct SuggestionItem {
     title: String,
     username_hint: Option<String>,
     match_strength: u8,
+    credential_type: String,
 }
 
 #[derive(Debug, Serialize)]
@@ -157,6 +158,9 @@ struct FillResponse {
 struct TotpPayload {
     origin: String,
     item_id: String,
+    /// Indicates this request was triggered by an explicit user action (click, keyboard).
+    #[serde(default)]
+    user_gesture: bool,
 }
 
 #[derive(Debug, Serialize)]
@@ -313,7 +317,7 @@ async fn handle_request(
             let parsed: SuggestionsPayload = serde_json::from_value(req.payload)
                 .context("invalid payload for get_suggestions")?;
             let host = origin_to_host(&parsed.origin)?;
-            let items = get_password_suggestions(db_path, &host).await?;
+            let items = get_credential_suggestions(db_path, &host).await?;
             let payload = serde_json::to_value(SuggestionsResponse {
                 items,
                 suggesting_for: host,
@@ -425,6 +429,18 @@ async fn handle_request(
                 serde_json::from_value(req.payload).context("invalid payload for get_totp")?;
             let host = origin_to_host(&parsed.origin)?;
 
+            let require_gesture = std::env::var("PERSONA_BRIDGE_REQUIRE_GESTURE")
+                .map(|v| v != "0" && v.to_lowercase() != "false")
+                .unwrap_or(true);
+            if require_gesture && !parsed.user_gesture {
+                warn!(
+                    origin = %parsed.origin,
+                    item_id = %parsed.item_id,
+                    "totp request rejected: user_gesture required but not provided"
+                );
+                return Err(anyhow!("user_gesture_required: totp must be triggered by explicit user action"));
+            }
+
             let master_password = std::env::var("PERSONA_MASTER_PASSWORD")
                 .ok()
                 .filter(|s| !s.trim().is_empty())
@@ -450,6 +466,10 @@ async fn handle_request(
                 return Err(anyhow!("unsupported_credential_type"));
             }
 
+            if cred.url.is_none() {
+                return Err(anyhow!("origin_binding_required: totp entries must have a URL set"));
+            }
+
             if !validate_origin_binding(&host, cred.url.as_deref()) {
                 warn!(
                     origin = %parsed.origin,
@@ -1048,7 +1068,7 @@ async fn compute_status(db_path: &PathBuf) -> Result<(bool, Option<String>)> {
     Ok((locked, active_identity))
 }
 
-async fn get_password_suggestions(db_path: &PathBuf, host: &str) -> Result<Vec<SuggestionItem>> {
+async fn get_credential_suggestions(db_path: &PathBuf, host: &str) -> Result<Vec<SuggestionItem>> {
     let db = open_db(db_path).await?;
     let repo = CredentialRepository::new(db);
     let all = repo.find_all().await?;
@@ -1058,15 +1078,18 @@ async fn get_password_suggestions(db_path: &PathBuf, host: &str) -> Result<Vec<S
         if !cred.is_active {
             continue;
         }
-        if cred.credential_type != CredentialType::Password {
+        let kind = match cred.credential_type {
+            CredentialType::Password => "password",
+            CredentialType::TwoFactor => "totp",
+            _ => continue,
+        };
+
+        if cred.url.is_none() {
             continue;
         }
 
         // Calculate match strength based on URL similarity.
-        let match_strength = match cred.url.as_deref() {
-            Some(url) => compute_match_strength(host, url),
-            None => 0,
-        };
+        let match_strength = compute_match_strength(host, cred.url.as_deref().unwrap_or_default());
 
         if match_strength == 0 {
             continue;
@@ -1077,6 +1100,7 @@ async fn get_password_suggestions(db_path: &PathBuf, host: &str) -> Result<Vec<S
             title: cred.name,
             username_hint: cred.username,
             match_strength,
+            credential_type: kind.to_string(),
         });
     }
 

cli/src/commands/totp.rs

@@ -46,6 +46,11 @@ pub enum TotpCommand {
         /// Account name override
         #[arg(long)]
         account: Option<String>,
+        /// Associate this TOTP with a website origin (enables browser extension matching)
+        ///
+        /// Accepts full URL (https://github.com) or a bare host (github.com).
+        #[arg(long)]
+        url: Option<String>,
         /// Digits override
         #[arg(long)]
         digits: Option<u8>,
@@ -77,12 +82,13 @@ pub async fn execute(args: TotpArgs, config: &CliConfig) -> Result<()> {
             secret,
             issuer,
             account,
+            url,
             digits,
             period,
             algorithm,
         } => {
             setup_totp(
-                config, identity, name, qr, otpauth, secret, issuer, account, digits, period,
+                config, identity, name, qr, otpauth, secret, issuer, account, url, digits, period,
                 algorithm,
             )
             .await?
@@ -101,6 +107,7 @@ async fn setup_totp(
     secret: Option<String>,
     issuer_override: Option<String>,
     account_override: Option<String>,
+    url: Option<String>,
     digits_override: Option<u8>,
     period_override: Option<u32>,
     algorithm_override: Option<String>,
@@ -137,6 +144,7 @@ async fn setup_totp(
     }
 
     let final_template = template.finalize()?;
+    let origin_url = url.map(|s| normalize_origin_url(&s)).transpose()?;
 
     let credential_name = display_name
         .or_else(|| {
@@ -173,6 +181,9 @@ async fn setup_totp(
         .context("Failed to create TOTP credential")?;
 
     credential.username = Some(final_template.account.clone());
+    if let Some(url) = origin_url {
+        credential.url = Some(url);
+    }
     credential
         .metadata
         .insert("issuer".into(), final_template.issuer.clone());
@@ -205,6 +216,21 @@ async fn setup_totp(
     Ok(())
 }
 
+fn normalize_origin_url(raw: &str) -> Result<String> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        bail!("URL cannot be empty");
+    }
+
+    let url = url::Url::parse(trimmed).or_else(|_| url::Url::parse(&format!("https://{trimmed}")))?;
+    let scheme = url.scheme();
+    let host = url
+        .host_str()
+        .ok_or_else(|| anyhow!("Invalid URL: missing host"))?;
+
+    Ok(format!("{scheme}://{host}"))
+}
+
 async fn generate_codes(config: &CliConfig, id: Uuid, watch: bool) -> Result<()> {
     let mut service = init_service(config).await?;
     let credential = service

docs/BRIDGE_PROTOCOL.md

@@ -110,7 +110,7 @@ Persona Native Messaging Bridge Protocol 用于浏览器扩展与本地 CLI/Desk
   "ok": true,
   "payload": {
     "server_version": "0.1.0",
-    "capabilities": ["status", "pairing_request", "pairing_finalize", "get_suggestions", "request_fill"],
+    "capabilities": ["status", "pairing_request", "pairing_finalize", "get_suggestions", "request_fill", "get_totp", "copy"],
     "pairing_required": true,
     "paired": false,
     "session_id": null,
@@ -231,7 +231,8 @@ Persona Native Messaging Bridge Protocol 用于浏览器扩展与本地 CLI/Desk
         "item_id": "uuid-v4",
         "title": "GitHub (Work)",
         "username_hint": "user@example.com",
-        "match_strength": 100
+        "match_strength": 100,
+        "credential_type": "password"
       }
     ]
   }
@@ -241,9 +242,9 @@ Persona Native Messaging Bridge Protocol 用于浏览器扩展与本地 CLI/Desk
 | match_strength | 含义 |
 |----------------|------|
 | 100 | 精确域名匹配 |
+| 90 | 子域名匹配 |
 | 80 | 域名包含匹配 |
 | 60 | 顶级域名匹配 |
-| 40 | 手动关联 |
 
 ### 6. request_fill - 请求填充
 
@@ -284,13 +285,16 @@ Persona Native Messaging Bridge Protocol 用于浏览器扩展与本地 CLI/Desk
 
 获取关联凭证的当前 TOTP 代码。
 
+> 注意：为了进行 Origin 绑定，TOTP 条目必须设置 URL（否则返回 `origin_binding_required`）。
+
 **请求：**
 ```json
 {
   "type": "get_totp",
   "payload": {
     "origin": "https://github.com",
-    "item_id": "uuid-v4"
+    "item_id": "uuid-v4",
+    "user_gesture": true
   }
 }
 ```
@@ -349,7 +353,7 @@ Persona Native Messaging Bridge Protocol 用于浏览器扩展与本地 CLI/Desk
 
 ### User Gesture 要求
 
-`request_fill` 和 `copy` 操作要求：
+`request_fill` / `get_totp` / `copy` 操作要求：
 
 1. 必须由用户明确操作触发（点击、键盘快捷键）
 2. 请求中应包含 `user_gesture: true` 表示这是用户主动操作
@@ -420,6 +424,7 @@ Persona Native Messaging Bridge Protocol 用于浏览器扩展与本地 CLI/Desk
 | `locked` | 保险库已锁定，需要解锁 |
 | `not_found` | 请求的资源不存在 |
 | `origin_mismatch` | Origin 不匹配 |
+| `origin_binding_required` | 条目未设置 URL，无法进行 Origin 绑定 |
 | `authentication_failed` | 认证失败 |
 | `user_confirmation_required` | 需要用户确认 |
 | `session_expired` | 会话已过期 |
@@ -435,7 +440,7 @@ Persona Native Messaging Bridge Protocol 用于浏览器扩展与本地 CLI/Desk
 | `PERSONA_DB_PATH` | 数据库路径 | `~/.persona/identities.db` |
 | `PERSONA_BRIDGE_STATE_DIR` | Bridge 状态目录（pairing/session） | `~/.persona/bridge` |
 | `PERSONA_BRIDGE_REQUIRE_PAIRING` | 是否强制 pairing + HMAC | `true` |
-| `PERSONA_BRIDGE_REQUIRE_GESTURE` | 是否强制 user_gesture（fill/copy） | `true` |
+| `PERSONA_BRIDGE_REQUIRE_GESTURE` | 是否强制 user_gesture（fill/totp/copy） | `true` |
 | `PERSONA_BRIDGE_AUTH_MAX_SKEW_MS` | HMAC 时间戳最大偏移（防重放） | `300000` |
 
 ### CLI 参数