Skip to main content

gitflow_github/
auth.rs

1//! GitHub 认证提供者实现。
2//!
3//! 通过 `gh auth` CLI 命令实现 [`AuthProvider`] trait,支持登录、
4//! 登出、状态查询及 Token 管理。
5//! 命令执行通过 [`CommandRunner`] 抽象,生产环境默认使用
6//! [`RealCommandRunner`],测试可注入自定义 runner 以模拟成功或失败场景。
7//! 环境变量读取通过 [`EnvSource`] 参数抽象,生产环境默认使用 [`RealEnv`],
8//! 测试可通过 `with_runner_and_env` 注入自定义实现。
9
10use async_trait::async_trait;
11use gitflow_cli_adapter_utils::{EnvSource, RealEnv};
12use gitflow_core::{
13    CoreError, Result,
14    auth::{AuthProvider, AuthStatus},
15};
16use tracing::debug;
17
18use crate::{
19    error::parse_gh_error,
20    runner::{CommandRunner, RealCommandRunner},
21};
22
23/// GitHub 认证提供者,通过 `gh` CLI 操作认证。
24///
25/// 命令执行通过 [`CommandRunner`] 抽象,生产环境默认使用
26/// [`RealCommandRunner`],测试可注入自定义 runner 以模拟成功或失败场景。
27/// 环境变量读取通过 [`EnvSource`] 参数抽象,生产环境默认使用 [`RealEnv`],
28/// 测试可通过 `with_runner_and_env` 注入自定义实现。
29///
30/// # Examples
31///
32/// ```no_run
33/// use gitflow_github::GitHubAuthProvider;
34///
35/// let provider = GitHubAuthProvider::new();
36/// ```
37#[derive(Debug, Clone)]
38pub struct GitHubAuthProvider<R: CommandRunner = RealCommandRunner, E: EnvSource = RealEnv> {
39    /// 用于执行 `gh` CLI 命令的 runner。
40    runner: R,
41    /// 环境变量来源,生产环境为进程环境,测试可注入。
42    env: E,
43}
44
45impl GitHubAuthProvider<RealCommandRunner, RealEnv> {
46    /// 创建新的 GitHub 认证提供者,使用真实的进程执行器。
47    #[must_use]
48    pub fn new() -> Self {
49        Self {
50            runner: RealCommandRunner,
51            env: RealEnv,
52        }
53    }
54
55    /// Create a new provider from a shared [`Session`].
56    ///
57    /// This enables state reuse across multiple operations in workflow chains.
58    /// Note: `AuthProvider` doesn't use repo, so session.repo is ignored.
59    #[must_use]
60    pub fn with_session(_session: &gitflow_core::Session) -> Self {
61        Self {
62            runner: RealCommandRunner,
63            env: RealEnv,
64        }
65    }
66}
67
68impl<R: CommandRunner> GitHubAuthProvider<R, RealEnv> {
69    /// 使用自定义 [`CommandRunner`] 创建提供者,环境变量仍取自进程环境。
70    ///
71    /// 主要用于测试,可注入模拟 runner 以控制 `gh` CLI 的输出。
72    #[must_use]
73    pub fn with_runner(runner: R) -> Self {
74        Self {
75            runner,
76            env: RealEnv,
77        }
78    }
79}
80
81impl<R: CommandRunner, E: EnvSource> GitHubAuthProvider<R, E> {
82    /// 同时注入自定义 [`CommandRunner`] 与 [`EnvSource`]。
83    ///
84    /// 测试应优先使用本构造函数:注入的环境变量来源使测试不依赖进程环境。
85    #[must_use]
86    pub fn with_runner_and_env(runner: R, env: E) -> Self {
87        Self { runner, env }
88    }
89}
90
91impl Default for GitHubAuthProvider<RealCommandRunner, RealEnv> {
92    fn default() -> Self {
93        Self::new()
94    }
95}
96
97#[async_trait]
98impl<R: CommandRunner + 'static, E: EnvSource + 'static> AuthProvider for GitHubAuthProvider<R, E> {
99    /// 执行交互式登录。
100    ///
101    /// 调用 `gh auth login`,将子进程的 stdout/stderr 透传给终端。
102    /// 如果提供了 token,则通过 `--with-token` 参数进行非交互式登录,
103    /// 并将 token 写入子进程的标准输入,避免其出现在进程参数中。
104    ///
105    /// # Errors
106    ///
107    /// 当认证失败或 `gh` 调用失败时返回错误。
108    async fn login(&self, token: Option<&str>) -> Result<()> {
109        debug!("spawning `gh auth login`");
110
111        if let Some(token) = token {
112            // 非交互模式:通过 stdin 传入 token,避免在进程参数中暴露敏感值
113            let output = self
114                .runner
115                .run_with_stdin("gh", &["auth", "login", "--with-token"], token.as_bytes())
116                .await
117                .map_err(|e| CoreError::Platform(format!("Failed to spawn gh auth login: {e}")))?;
118
119            if !output.status.success() {
120                return Err(CoreError::Platform("gh auth login failed".into()));
121            }
122        } else {
123            // Interactive mode
124            let output = self
125                .runner
126                .run("gh", &["auth", "login"])
127                .await
128                .map_err(|e| CoreError::Platform(format!("Failed to spawn gh auth login: {e}")))?;
129
130            if !output.status.success() {
131                return Err(CoreError::Platform("gh auth login failed".into()));
132            }
133        }
134
135        Ok(())
136    }
137
138    /// 执行登出,清除本地凭据。
139    ///
140    /// # Errors
141    ///
142    /// 当 `gh` 调用失败时返回错误。
143    async fn logout(&self) -> Result<()> {
144        debug!("spawning `gh auth logout`");
145
146        let output = self
147            .runner
148            .run("gh", &["auth", "logout"])
149            .await
150            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh auth logout: {e}")))?;
151
152        if !output.status.success() {
153            return Err(parse_gh_error(&output.stderr).into());
154        }
155
156        Ok(())
157    }
158
159    /// 查询当前认证状态。
160    ///
161    /// 调用 `gh auth status` 并解析输出来构造 [`AuthStatus`]。
162    /// 当 `gh` 命令执行失败或用户未登录时,返回 `AuthStatus { logged_in: false }`
163    /// 而非传播错误。
164    ///
165    /// # Errors
166    ///
167    /// 仅在 `gh` 返回非零退出码且无法识别为"未登录"模式时返回错误。
168    async fn status(&self) -> Result<AuthStatus> {
169        debug!("spawning `gh auth status`");
170
171        let Ok(output) = self.runner.run("gh", &["auth", "status"]).await else {
172            // CLI 执行失败(如 gh 未安装)→ 视为未登录
173            return Ok(AuthStatus {
174                logged_in: false,
175                user: None,
176                scopes: vec![],
177                hosts: vec![],
178            });
179        };
180
181        let stdout = String::from_utf8_lossy(&output.stdout);
182        let stderr = String::from_utf8_lossy(&output.stderr);
183
184        // gh auth status 在未登录时会返回非零退出码
185        if !output.status.success() {
186            // 检查是否为未登录状态(某些版本会返回特定错误)
187            let text = format!("{stdout}{stderr}");
188            if text.to_lowercase().contains("not logged in")
189                || text.to_lowercase().contains("no active account")
190                || text.to_lowercase().contains("not authenticated")
191            {
192                return Ok(AuthStatus {
193                    logged_in: false,
194                    user: None,
195                    scopes: vec![],
196                    hosts: vec![],
197                });
198            }
199
200            return Err(parse_gh_error(&output.stderr).into());
201        }
202
203        // 解析登录用户:查找 "Logged in to github.com as <username>" 行
204        let user = parse_user_from_status(&stdout);
205
206        // 解析 token scopes:查找 "Token scopes: 'scope1', 'scope2'" 行
207        let scopes = parse_scopes_from_status(&stdout);
208
209        Ok(AuthStatus {
210            logged_in: user.is_some(),
211            user,
212            scopes,
213            hosts: vec![],
214        })
215    }
216
217    /// 获取当前有效的访问 Token。
218    ///
219    /// # Errors
220    ///
221    /// 当 `gh` 命令执行失败、用户未登录或 Token 为空时返回错误。
222    async fn token(&self) -> Result<String> {
223        debug!("spawning `gh auth token`");
224
225        let output = self
226            .runner
227            .run("gh", &["auth", "token"])
228            .await
229            .map_err(|e| CoreError::Platform(format!("Failed to spawn gh auth token: {e}")))?;
230
231        if !output.status.success() {
232            return Err(parse_gh_error(&output.stderr).into());
233        }
234
235        let token = String::from_utf8_lossy(&output.stdout);
236        let trimmed = token.trim().to_string();
237        if trimmed.is_empty() {
238            return Err(CoreError::Platform(
239                "gh auth token returned empty output".into(),
240            ));
241        }
242        Ok(trimmed)
243    }
244}
245
246// AuthChecker 是同步 trait,必须使用 std::process::Command
247#[allow(clippy::disallowed_types, reason = "AuthChecker is synchronous")]
248impl<R: CommandRunner, E: EnvSource> gitflow_core::AuthChecker for GitHubAuthProvider<R, E> {
249    fn is_authenticated(&self) -> bool {
250        if self.env.var("GH_TOKEN").is_some() {
251            return true;
252        }
253
254        let output = std::process::Command::new("gh")
255            .args(["auth", "status"])
256            .output();
257
258        matches!(output, Ok(out) if out.status.success())
259    }
260
261    fn check_status(&self) -> gitflow_core::AuthCheckResult {
262        // 1. 检查环境变量
263        if self.env.var("GH_TOKEN").is_some() {
264            return gitflow_core::AuthCheckResult {
265                authenticated: true,
266                user: None,
267                reason: None,
268                hint: None,
269            };
270        }
271
272        // 2. 执行 gh auth status
273        let output = match std::process::Command::new("gh")
274            .args(["auth", "status"])
275            .output()
276        {
277            Ok(out) => out,
278            Err(e) => {
279                return gitflow_core::AuthCheckResult {
280                    authenticated: false,
281                    user: None,
282                    reason: Some(format!("Failed to execute gh: {e}")),
283                    hint: Some("Install GitHub CLI: https://cli.github.com".into()),
284                };
285            }
286        };
287
288        // 3. 解析结果
289        if output.status.success() {
290            let stdout = String::from_utf8_lossy(&output.stdout);
291            let user = parse_user_from_status(&stdout);
292
293            gitflow_core::AuthCheckResult {
294                authenticated: true,
295                user,
296                reason: None,
297                hint: None,
298            }
299        } else {
300            let stderr = String::from_utf8_lossy(&output.stderr);
301
302            gitflow_core::AuthCheckResult {
303                authenticated: false,
304                user: None,
305                reason: Some(stderr.to_string()),
306                hint: Some("Run `gh auth login` to authenticate".into()),
307            }
308        }
309    }
310}
311
312/// 从 `gh auth status` 的输出中解析 token scopes。
313///
314/// 支持格式:`"Token scopes: 'scope1', 'scope2', ..."`
315/// 可能带 `✓` 或 `-` 前缀。
316fn parse_scopes_from_status(output: &str) -> Vec<String> {
317    for line in output.lines() {
318        // 查找包含 "Token scopes:" 的行
319        let Some(pos) = line.find("Token scopes:") else {
320            continue;
321        };
322        let after = &line[pos + "Token scopes:".len()..];
323        let trimmed = after.trim();
324
325        // 处理 "none" 或空值
326        if trimmed.is_empty() || trimmed.eq_ignore_ascii_case("none") {
327            return vec![];
328        }
329
330        // 解析 'scope1', 'scope2' 格式
331        return trimmed
332            .split(',')
333            .map(|s| s.trim().trim_matches('\'').trim_matches('"').to_string())
334            .filter(|s| !s.is_empty())
335            .collect();
336    }
337    vec![]
338}
339
340/// 从 `gh auth status` 的输出中解析用户名。
341///
342/// 支持两种 `gh` CLI 输出格式:
343/// - 旧版:`"Logged in to github.com as <username>"`
344/// - 新版:`"Logged in to github.com account <username>"`
345fn parse_user_from_status(output: &str) -> Option<String> {
346    let separators = [" as ", " account "];
347    for line in output.lines() {
348        // Only parse lines that contain "Logged in to" to avoid false matches
349        if !line.contains("Logged in to") {
350            continue;
351        }
352        for sep in &separators {
353            if let Some(pos) = line.find(sep) {
354                let after = &line[pos + sep.len()..];
355                // 用户名后面可能跟 " (" 或空格或其他
356                if let Some(end) = after.find(' ') {
357                    let user = &after[..end];
358                    if !user.is_empty() {
359                        return Some(user.to_string());
360                    }
361                } else if !after.is_empty() {
362                    return Some(after.trim().to_string());
363                }
364            }
365        }
366    }
367    None
368}
369
370#[cfg(test)]
371mod tests {
372    use gitflow_cli_adapter_utils::MockEnv;
373
374    use super::*;
375    use crate::runner::MockCommandRunner;
376
377    #[test]
378    fn test_should_construct_github_auth_provider() {
379        let provider = GitHubAuthProvider::new();
380        let debug = format!("{provider:?}");
381        assert!(debug.contains("GitHubAuthProvider"));
382    }
383
384    #[test]
385    fn test_should_default_github_auth_provider() {
386        let provider = GitHubAuthProvider::default();
387        let _ = format!("{provider:?}");
388    }
389
390    #[test]
391    fn test_should_clone_github_auth_provider() {
392        let original = GitHubAuthProvider::new();
393        let cloned = original.clone();
394        let _ = format!("{cloned:?}");
395    }
396
397    #[test]
398    fn test_should_parse_user_from_status_output() {
399        let status = r"github.com
400  ✓ Logged in to github.com as octocat (keyring)
401  ✓ Git operations for github.com configured to use ssh protocol.
402  ✓ API calls for github.com should use https protocol
403";
404        assert_eq!(parse_user_from_status(status), Some("octocat".to_string()));
405    }
406
407    #[test]
408    fn test_should_parse_user_from_status_with_different_host() {
409        let status = r"github.com
410  ✓ Logged in to github.com as alice (oauth_token)
411  ✓ Token: gho_****
412";
413        assert_eq!(parse_user_from_status(status), Some("alice".to_string()));
414    }
415
416    #[test]
417    fn test_should_return_none_when_no_user_in_status() {
418        let status = "No active account found";
419        assert!(parse_user_from_status(status).is_none());
420    }
421
422    #[test]
423    fn test_should_return_none_for_empty_status() {
424        assert!(parse_user_from_status("").is_none());
425    }
426
427    #[test]
428    fn test_should_parse_user_without_suffix() {
429        let status = "Logged in to github.com as bob";
430        assert_eq!(parse_user_from_status(status), Some("bob".to_string()));
431    }
432
433    #[test]
434    fn test_should_parse_user_from_account_format() {
435        let status = r"github.com
436  ✓ Logged in to github.com account octocat (keyring)
437  ✓ Git operations for github.com configured to use ssh protocol.
438  ✓ API calls for github.com should use https protocol
439";
440        assert_eq!(parse_user_from_status(status), Some("octocat".to_string()));
441    }
442
443    #[test]
444    fn test_should_parse_user_from_account_format_without_suffix() {
445        let status = "Logged in to github.com account bob";
446        assert_eq!(parse_user_from_status(status), Some("bob".to_string()));
447    }
448
449    #[test]
450    fn test_should_parse_scopes_from_status_output() {
451        let status = r"github.com
452  ✓ Logged in to github.com account octocat (keyring)
453  - Token scopes: 'delete_repo', 'gist', 'read:org', 'repo', 'workflow'
454";
455        let scopes = parse_scopes_from_status(status);
456        assert_eq!(
457            scopes,
458            vec!["delete_repo", "gist", "read:org", "repo", "workflow"]
459        );
460    }
461
462    #[test]
463    fn test_should_parse_scopes_with_checkmark_prefix() {
464        let status = "  ✓ Token scopes: 'repo', 'read:org'";
465        let scopes = parse_scopes_from_status(status);
466        assert_eq!(scopes, vec!["repo", "read:org"]);
467    }
468
469    #[test]
470    fn test_should_return_empty_scopes_when_none() {
471        let status = "  - Token scopes: none";
472        let scopes = parse_scopes_from_status(status);
473        assert!(scopes.is_empty());
474    }
475
476    #[test]
477    fn test_should_return_empty_scopes_when_line_missing() {
478        let status = "Logged in to github.com as octocat";
479        let scopes = parse_scopes_from_status(status);
480        assert!(scopes.is_empty());
481    }
482
483    #[test]
484    fn test_should_parse_single_scope() {
485        let status = "  - Token scopes: 'repo'";
486        let scopes = parse_scopes_from_status(status);
487        assert_eq!(scopes, vec!["repo"]);
488    }
489
490    #[test]
491    fn test_should_report_authenticated_when_token_env_var_present() {
492        use gitflow_core::AuthChecker;
493        // AuthChecker 同步分支直接调用 std::process::Command,不读取注入的 runner;
494        // env 短路才是本测试确定性的来源。
495        let provider = GitHubAuthProvider::with_runner_and_env(
496            MockCommandRunner::success(""),
497            MockEnv::with("GH_TOKEN", "test_token"),
498        );
499        assert!(provider.is_authenticated());
500    }
501
502    #[test]
503    fn test_should_report_authenticated_status_without_reason_when_token_env_var_present() {
504        use gitflow_core::AuthChecker;
505        // AuthChecker 同步分支直接调用 std::process::Command,不读取注入的 runner;
506        // env 短路才是本测试确定性的来源。
507        let provider = GitHubAuthProvider::with_runner_and_env(
508            MockCommandRunner::success(""),
509            MockEnv::with("GH_TOKEN", "test_token"),
510        );
511        let result = provider.check_status();
512        assert!(result.authenticated);
513        assert!(result.reason.is_none());
514        assert!(result.hint.is_none());
515    }
516
517    // --- Failure-path tests using an injected MockCommandRunner ---
518
519    #[tokio::test]
520    async fn test_should_return_platform_error_when_gh_login_fails() {
521        let runner = MockCommandRunner::failure("login failed", 1);
522        let provider = GitHubAuthProvider::with_runner(runner);
523
524        let result = provider.login(None).await;
525
526        assert!(result.is_err());
527        assert!(matches!(
528            result.unwrap_err(),
529            gitflow_core::CoreError::Platform(_)
530        ));
531    }
532
533    #[tokio::test]
534    async fn test_should_login_with_token_via_stdin() {
535        let runner = MockCommandRunner::success("");
536        let provider = GitHubAuthProvider::with_runner(runner);
537
538        let result = provider.login(Some("ghp_secret_token")).await;
539
540        assert!(result.is_ok());
541    }
542
543    #[tokio::test]
544    async fn test_should_return_platform_error_when_gh_login_with_token_fails() {
545        let runner = MockCommandRunner::failure("token login failed", 1);
546        let provider = GitHubAuthProvider::with_runner(runner);
547
548        let result = provider.login(Some("ghp_secret_token")).await;
549
550        assert!(result.is_err());
551        assert!(matches!(
552            result.unwrap_err(),
553            gitflow_core::CoreError::Platform(_)
554        ));
555    }
556
557    #[tokio::test]
558    async fn test_should_return_platform_error_when_gh_logout_fails() {
559        let runner = MockCommandRunner::failure("logout failed", 1);
560        let provider = GitHubAuthProvider::with_runner(runner);
561
562        let result = provider.logout().await;
563
564        assert!(result.is_err());
565        assert!(matches!(
566            result.unwrap_err(),
567            gitflow_core::CoreError::Cli(_)
568        ));
569    }
570
571    #[tokio::test]
572    async fn test_should_return_not_logged_in_when_gh_status_spawn_fails() {
573        let runner = MockCommandRunner::spawn_error();
574        let provider = GitHubAuthProvider::with_runner(runner);
575
576        let result = provider.status().await;
577
578        assert!(result.is_ok());
579        let status = result.unwrap();
580        assert!(!status.logged_in);
581        assert!(status.user.is_none());
582        assert!(status.scopes.is_empty());
583    }
584
585    #[tokio::test]
586    async fn test_should_return_platform_error_when_gh_token_fails() {
587        let runner = MockCommandRunner::failure("token failed", 1);
588        let provider = GitHubAuthProvider::with_runner(runner);
589
590        let result = provider.token().await;
591
592        assert!(result.is_err());
593        assert!(matches!(
594            result.unwrap_err(),
595            gitflow_core::CoreError::Cli(_)
596        ));
597    }
598
599    #[tokio::test]
600    async fn test_should_return_error_when_gh_token_returns_empty() {
601        let runner = MockCommandRunner::success("");
602        let provider = GitHubAuthProvider::with_runner(runner);
603
604        let result = provider.token().await;
605
606        assert!(result.is_err());
607        assert!(matches!(
608            result.unwrap_err(),
609            gitflow_core::CoreError::Platform(_)
610        ));
611    }
612
613    // --- Success-path tests using an injected MockCommandRunner ---
614
615    #[test]
616    fn test_should_construct_with_custom_runner() {
617        let runner = MockCommandRunner::success("");
618        let provider = GitHubAuthProvider::with_runner(runner);
619        let debug = format!("{provider:?}");
620        assert!(debug.contains("GitHubAuthProvider"));
621    }
622
623    #[tokio::test]
624    async fn test_should_login_interactively() {
625        let runner = MockCommandRunner::success("");
626        let provider = GitHubAuthProvider::with_runner(runner);
627
628        let result = provider.login(None).await;
629
630        assert!(result.is_ok());
631    }
632
633    #[tokio::test]
634    async fn test_should_logout_successfully() {
635        let runner = MockCommandRunner::success("");
636        let provider = GitHubAuthProvider::with_runner(runner);
637
638        let result = provider.logout().await;
639
640        assert!(result.is_ok());
641    }
642
643    #[tokio::test]
644    async fn test_should_return_logged_in_status_when_authenticated() {
645        let stdout =
646            "Logged in to github.com as testuser (keyring)\n  - Token scopes: 'repo', 'read:org'\n";
647        let runner = MockCommandRunner::success(stdout);
648        let provider = GitHubAuthProvider::with_runner(runner);
649
650        let result = provider.status().await;
651
652        assert!(result.is_ok());
653        let status = result.unwrap();
654        assert!(status.logged_in);
655        assert_eq!(status.user, Some("testuser".to_string()));
656        assert_eq!(status.scopes, vec!["repo", "read:org"]);
657        assert!(status.hosts.is_empty());
658    }
659
660    #[tokio::test]
661    async fn test_should_return_not_logged_in_when_gh_status_indicates_not_authenticated() {
662        let runner = MockCommandRunner::failure("not logged in", 1);
663        let provider = GitHubAuthProvider::with_runner(runner);
664
665        let result = provider.status().await;
666
667        assert!(result.is_ok());
668        let status = result.unwrap();
669        assert!(!status.logged_in);
670        assert!(status.user.is_none());
671    }
672
673    #[tokio::test]
674    async fn test_should_return_cli_error_when_gh_status_fails_unknown() {
675        let runner = MockCommandRunner::failure("unknown server error", 128);
676        let provider = GitHubAuthProvider::with_runner(runner);
677
678        let result = provider.status().await;
679
680        assert!(result.is_err());
681        assert!(matches!(
682            result.unwrap_err(),
683            gitflow_core::CoreError::Cli(_)
684        ));
685    }
686
687    #[tokio::test]
688    async fn test_should_return_token_successfully() {
689        let runner = MockCommandRunner::success("ghp_test12345\n");
690        let provider = GitHubAuthProvider::with_runner(runner);
691
692        let result = provider.token().await;
693
694        assert!(result.is_ok());
695        assert_eq!(result.unwrap(), "ghp_test12345");
696    }
697
698    #[tokio::test]
699    async fn test_should_trim_whitespace_from_token() {
700        let runner = MockCommandRunner::success("  ghp_test12345  \n\n");
701        let provider = GitHubAuthProvider::with_runner(runner);
702
703        let result = provider.token().await;
704
705        assert!(result.is_ok());
706        assert_eq!(result.unwrap(), "ghp_test12345");
707    }
708}