🔑 认证

管理 Composer 的 auth.json 凭据文件，为私有仓库与受保护 API 配置 GitHub / GitLab / Bitbucket / Bearer / HTTP Basic 认证令牌。

Composer Skills 把 auth.json 的读写封装为一组类型安全的方法。所有 Add 方法都遵循「读取 → 修改 → 写回」的原子模式：先调用 GetAuthConfig 拿到当前配置（文件不存在则返回空配置），在内存里增改条目，再调用 SaveAuthConfig 以 0600 权限写回 ~/.composer/auth.json。

何时使用

• 🗝️ 项目依赖了私有 Git 仓库（自建 GitLab、Bitbucket 团队空间），composer install 需要令牌才能拉取。
• 🤖 CI 脚本里动态注入部署凭据，而不想把令牌硬编码进 auth.json。
• 🔄 轮换令牌：移除旧 token、写入新 token。
• 🔍 审计：列出当前已配置的认证条目，确认没有遗留的废弃凭据。

结构化类型

AuthConfig

GetAuthConfig / SaveAuthConfig 操作的顶层结构，对应 auth.json 的根对象。

type AuthConfig struct {
    GitHub       map[string]string `json:"github-oauth,omitempty"`
    GitLab       map[string]string `json:"gitlab-oauth,omitempty"`
    GitLabToken  map[string]string `json:"gitlab-token,omitempty"`
    Bitbucket    map[string]string `json:"bitbucket-oauth,omitempty"`
    Bearer       map[string]string `json:"bearer,omitempty"`
    HTTPBasic    map[string]string `json:"http-basic,omitempty"`
    AWSAccessKey map[string]string `json:"aws-access-key,omitempty"`
}

每个字段是「域名 → 凭据」的映射。Bitbucket 与 HTTPBasic 的值以 consumer:token / username:password 形式存储。

authType 字符串常量

RemoveToken / GetToken 的第一个参数 authType 必须是以下之一：github-oauth、gitlab-oauth、bitbucket-oauth、bearer、http-basic。传入其他值会返回 ErrInvalidAuthType。

方法签名

方法	签名	说明
🔑 GetAuthConfig	func (c *Composer) GetAuthConfig() (*AuthConfig, error)	读取 auth.json，文件不存在返回空配置
💾 SaveAuthConfig	func (c *Composer) SaveAuthConfig(config *AuthConfig) error	以 0600 权限写回 auth.json
🐙 AddGitHubToken	func (c *Composer) AddGitHubToken(domain string, token string) error	添加 GitHub OAuth 令牌
🦊 AddGitLabToken	func (c *Composer) AddGitLabToken(domain string, token string) error	添加 GitLab OAuth 令牌
🪣 AddBitbucketToken	func (c *Composer) AddBitbucketToken(domain string, consumer string, token string) error	添加 Bitbucket OAuth 令牌（consumer:token）
🎟️ AddBearerToken	func (c *Composer) AddBearerToken(domain string, token string) error	添加 Bearer 令牌
🔐 AddHTTPBasicAuth	func (c *Composer) AddHTTPBasicAuth(domain string, username string, password string) error	添加 HTTP Basic 认证（username:password）
🗑️ RemoveToken	func (c *Composer) RemoveToken(authType string, domain string) error	按类型与域名移除令牌
🔍 GetToken	func (c *Composer) GetToken(authType string, domain string) (string, error)	按类型与域名读取令牌

参数说明

AddBitbucketToken

参数	类型	说明
domain	string	仓库域名，如 bitbucket.org 或自建实例域名
consumer	string	OAuth consumer key
token	string	OAuth access token

RemoveToken / GetToken

参数	类型	说明
authType	string	认证类型，见上方常量清单
domain	string	令牌对应的域名

示例

注入 GitHub 令牌

package main

import (
	"fmt"
	"log"

	"github.com/scagogogo/composer-skills/pkg/composer"
)

func main() {
	comp, err := composer.New(composer.DefaultOptions())
	if err != nil {
		log.Fatalf("初始化 Composer 失败: %v", err)
	}

	// 为 github.com 写入 OAuth 令牌
	if err := comp.AddGitHubToken("github.com", "ghp_xxxxxxxxxxxxxxxxxxxxxxxx"); err != nil {
		log.Fatalf("写入 GitHub 令牌失败: %v", err)
	}

	// 读回校验
	token, err := comp.GetToken("github-oauth", "github.com")
	if err != nil {
		log.Fatalf("读取令牌失败: %v", err)
	}
	fmt.Printf("github.com 令牌前缀: %s...\n", token[:10])
}

为自建 GitLab 配置多种凭据

// 自建 GitLab 实例
if err := comp.AddGitLabToken("gitlab.example.com", "glpat-xxxxxxxxxxxxxxxxxxxx"); err != nil {
	log.Fatal(err)
}

// 私有 Composer 仓库用 HTTP Basic
if err := comp.AddHTTPBasicAuth("packages.example.com", "ci-deploy", "s3cret-pass"); err != nil {
	log.Fatal(err)
}

// 另一个仓库用 Bearer
if err := comp.AddBearerToken("api.example.com", "Bearer-token-value"); err != nil {
	log.Fatal(err)
}

轮换令牌：移除旧的，写入新的

// 移除旧 GitHub 令牌
if err := comp.RemoveToken("github-oauth", "github.com"); err != nil {
	if err == composer.ErrInvalidAuthType {
		log.Fatal("传入了不支持的认证类型")
	}
	log.Fatal(err)
}

// 写入新令牌
if err := comp.AddGitHubToken("github.com", "ghp_newrotatedtoken"); err != nil {
	log.Fatal(err)
}

完整读取并遍历

config, err := comp.GetAuthConfig()
if err != nil {
	log.Fatal(err)
}
for domain, token := range config.GitHub {
	fmt.Printf("github-oauth  %s  %s***\n", domain, token[:6])
}
for domain := range config.HTTPBasic {
	fmt.Printf("http-basic   %s\n", domain)
}

进阶

0600 权限

SaveAuthConfig 用 0600（仅属主可读写）写入 auth.json，避免令牌泄露给同机其他用户。请勿手动 chmod 放宽权限。

不支持 AWS 令牌的便捷方法

AuthConfig 含 AWSAccessKey 字段以保留兼容性，但当前未提供 AddAWSAccessKey 便捷方法。如需写入，可手动构造 *AuthConfig 后调用 SaveAuthConfig。

与 GetComposerHome 的关系

所有方法通过 c.GetComposerHome() 解析 auth.json 路径。若设置了 COMPOSER_HOME 环境变量，文件就落在该目录下；否则使用 Composer 的默认主目录。