authentication-patterns

概述

Authentication Patterns 提供对接外部服务时常见的认证模式，目标是给凭证管理、验证与错误处理提供一致的实现方法。它关注的是「如何以统一方式完成认证」，而非某一家服务专有的登录细节。

用途与适用场景

适合以下情况使用：

集成外部 API；
需要验证凭证是否有效；
需要管理多种认证方式；
需要优雅地处理认证失败。

不适合以下情况：

项目未使用 leyline 基础设施模式；
只是简单脚本，不需要服务架构层面的能力。

支持的认证方式

资料中列出了四类认证方式及其适用场景与对应环境变量：

API Key：适合简单集成，环境变量形如 {SERVICE}_API_KEY；
OAuth：适合需要用户认证的场景，采用浏览器流程；
Token：适合基于会话的场景，环境变量形如 {SERVICE}_TOKEN；
None：适合公开 API，无环境变量。

主要能力

凭证验证

提供 verify_auth 与 AuthMethod，可按不同认证方式检查服务认证状态。示例以 API Key 方式验证 gemini：

from leyline.auth import verify_auth, AuthMethod

# API Key verification
status = verify_auth(
    service="gemini", method=AuthMethod.API_KEY, env_var="GEMINI_API_KEY"
)

if not status.authenticated:
    print(f"Auth failed: {status.message}")
    print(f"Action: {status.suggested_action}")

失败时会输出失败信息与建议操作（suggested_action）。

冒烟测试

可用简单请求验证认证是否真正可用：

def verify_with_smoke_test(service: str) -> bool:
    """Verify auth with simple request."""
    result = execute_simple_request(service, "ping")
    return result.success

标准认证流程

技能给出三步标准流程：

检查环境：从环境变量读取凭证，缺失时提示；

def check_credentials(service: str, env_var: str) -> bool:
    value = os.getenv(env_var)
    if not value:
        print(f"Missing {env_var}")
        return False
    return True

向服务验证：调用服务自身的 auth status 命令并解析返回码与输出；

def verify_with_service(service: str) -> AuthStatus:
    result = subprocess.run([service, "auth", "status"], capture_output=True)
    return AuthStatus(
        authenticated=(result.returncode == 0), message=result.stdout.decode()
    )

处理失败：按认证方式给出对应的修复建议；

def handle_auth_failure(service: str, method: AuthMethod) -> str:
    actions = {
        AuthMethod.API_KEY: f"Set {service.upper()}_API_KEY environment variable",
        AuthMethod.OAUTH: f"Run '{service} auth login' for browser auth",
        AuthMethod.TOKEN: f"Refresh token with '{service} token refresh'",
    }
    return actions[method]

集成方式

在自己的技能 frontmatter 中声明依赖：

dependencies: [leyline:authentication-patterns]

交互式认证（Shell）

对于需要交互式认证、令牌缓存与会话管理的工作流，可使用交互式认证脚本：

# Source the interactive auth script
source plugins/leyline/scripts/interactive_auth.sh

# Ensure authentication before proceeding
ensure_auth github || exit 1
ensure_auth gitlab || exit 1
ensure_auth aws || exit 1

# Continue with authenticated operations
gh pr view 123
glab issue list
aws s3 ls

其特性包括：

为 GitHub、GitLab、AWS 等提供交互式 OAuth 流程；
令牌缓存（5 分钟 TTL）；
会话持久化（24 小时 TTL）；
兼容 CI/CD（自动检测非交互环境）；
多服务支持。

验证方式

资料中多处给出验证手段：

运行命令时加 --help 标志以验证可用性；
运行 pytest -v 以验证测试通过；
冒烟测试确认认证确实可用。

完成标准

凭证已通过验证，或给出明确的失败信息；
针对认证失败给出建议操作；
冒烟测试确认认证可用。

详细资源

认证方式细节：见 modules/auth-methods.md；
验证模式：见 modules/verification-patterns.md；
交互式认证：见 modules/interactive-auth.md。

限制

该技能依赖 leyline 基础设施模式，不适用于未采用该模式的项目或无需服务架构的简单脚本。其余如具体服务的认证配置细节、费用或平台支持范围，资料中暂未提供。