gogcli 凭据管理:`gog auth tokens delete` 删除 Refresh Token 的命令详解与实现原理

原创2026-09-15 19:43:081,620 阅读

gogcli 凭据管理:gog auth tokens delete 删除 Refresh Token 的命令详解与实现原理

gog auth tokens delete 是 gogcli(Google Workspace 命令行工具)中用于**删除已存储刷新令牌(refresh token)**的认证管理命令,常用于账号切换、凭据轮换或撤销已失效的授权。本文以 docs/commands/gog-auth-tokens-delete.md 为主体,结合 internal/cmd/auth_tokens.go 与 internal/secrets/token.go 的源码实现,完整讲解命令用法、全部可用 Flags、底层删除逻辑(含多键清理与 keyring 写入锁)、确认机制与测试验证,帮助你安全、精确地管理本机存储的 OAuth 凭据。

命令概述

该命令删除一个已存储的刷新令牌,对应的帮助文本为 “Delete a stored refresh token”。它是 gog auth tokens 子命令组(gog auth tokens)的一员,同组还包含:

  • gog auth tokens list — 仅按键名列出已存储令牌
  • gog auth tokens export — 将刷新令牌导出到文件(含机密)
  • gog auth tokens import — 从文件导入刷新令牌到 keyring

在 internal/cmd/auth_tokens.go 中,这四个子命令通过 Kong 框架以结构体字段的形式注册,Delete 字段对应 AuthTokensDeleteCmd:

type AuthTokensCmd struct {
	List   AuthTokensListCmd   `cmd:"" name:"list" help:"List stored tokens (by key only)"`
	Delete AuthTokensDeleteCmd `cmd:"" name:"delete" help:"Delete a stored refresh token"`
	Export AuthTokensExportCmd `cmd:"" name:"export" help:"Export a refresh token to a file (contains secrets)"`
	Import AuthTokensImportCmd `cmd:"" name:"import" help:"Import a refresh token file into keyring (contains secrets)"`
}

注意:本文档页面头部标注 “Generated from gog schema --json. Do not edit this page by hand; run make docs-commands”,说明命令帮助与参数表由 CLI schema 自动生成,保证文档与实际命令行为一致。

用法与位置参数

gog auth tokens delete <email>

唯一的位置参数 email 是要删除令牌的账号邮箱,对应源码中的参数定义:

type AuthTokensDeleteCmd struct {
	Email string `arg:"" name:"email" help:"Email"`
}

执行时,命令会先对 email 做 strings.TrimSpace 去空白处理;若结果为空,直接返回 usage("empty email") 错误并退出(见 internal/cmd/auth_tokens.go),因此不会出现空参数误删的情况。

典型使用示例:

# 删除默认 OAuth client 下 user@example.com 的令牌
gog auth tokens delete user@example.com

# 指定 OAuth client 后删除
gog auth tokens delete --client my-client user@example.com

# 非交互式(CI 或脚本)强制删除,跳过确认
gog auth tokens delete -y user@example.com

# 先预览将要执行的操作(不实际删除)
gog auth tokens delete --dry-run user@example.com

# 以 JSON 输出结果,便于脚本解析
gog auth tokens delete --json user@example.com

Flags 完整参考

与 gogcli 所有命令一致,gog auth tokens delete 继承并支持以下全局 Flags(默认值、别名与帮助文本均取自当前仓库 schema,可直接用于脚本与自动化):

Flag 类型 默认值 说明
--access-token string 直接使用提供的 access token(绕过已存储的 refresh token;token 约 1 小时过期)
-a
--account
--acct
string 账号邮箱、别名或 auto,用于已认证的 Google API 命令
--client string OAuth client 名称(选择已存储的凭据 + token bucket)
--color string auto 颜色输出:auto|always|never
--disable-commands string 逗号分隔的禁用命令列表;支持点路径
-n
--dry-run
--dryrun
--noop
--preview
bool 不执行实际修改,打印预期操作后成功退出
--enable-commands string 逗号分隔的启用命令前缀列表;支持点路径(限制 CLI)
--enable-commands-exact string 逗号分隔的精确启用命令列表;点路径且父命令不会启用子命令
-y
--force
--assume-yes
--yes
bool 跳过破坏性命令的确认提示
--gmail-no-send bool false 阻止 Gmail 发送操作(Agent 安全)
-h
--help
kong.helpFlag 显示上下文相关的帮助
--home string 覆盖 gogcli 的 config/data/state/cache 根目录(等价于 GOG_HOME)
-j
--json
--machine
bool false 输出 JSON 到 stdout(最适合脚本)
--no-input
--non-interactive
--noninteractive
bool 永不提示;失败即退出(适合 CI)
-p
--plain
--tsv
bool false 输出稳定可解析的文本到 stdout(TSV;无颜色)
--quota-project string 用于结算 API 用量的 Google Cloud 项目(作为 X-Goog-User-Project 发送;部分 API 与 --access-token 或 ADC 配合时需要)
--readonly bool false 运行时阻止变更型 API 请求;auth add 也会请求只读 OAuth scopes
--results-only bool JSON 模式下仅输出主要结果(丢弃 envelope 字段如 nextPageToken)
--select
--pick
--project
string JSON 模式下选择逗号分隔的字段(尽力而为;支持点路径)
-v
--verbose
bool 启用详细日志
--version kong.VersionFlag 打印版本并退出
--wrap-untrusted bool false 在 JSON/raw 输出中,用外部不可信内容标记包裹抓取的文本字段

其中与删除操作最相关的 Flags:

  • --client:指定 OAuth client 名称。若不指定,源码会通过 resolveClientForEmail(见下文)按邮箱自动解析。
  • --force / -y:跳过破坏性命令的二次确认,脚本化删除时推荐配合使用。
  • --dry-run:只打印将要执行的动作、不真正删除,是审计与演练的首选。
  • --json:将结果输出为结构化 JSON,便于 CI 校验。

删除流程与源码级执行链路

在 internal/cmd/auth_tokens.go 中,AuthTokensDeleteCmd.Run 的执行顺序如下:

func (c *AuthTokensDeleteCmd) Run(ctx context.Context, flags *RootFlags) error {
	u := ui.FromContext(ctx)
	email := strings.TrimSpace(c.Email)
	if email == "" {
		return usage("empty email")
	}

	if err := dryRunAndConfirmDestructive(ctx, flags, "auth.tokens.delete", map[string]any{
		"email": email,
	}, fmt.Sprintf("delete stored token for %s", email)); err != nil {
		return err
	}

	store, err := openAuthSecretsStore(ctx)
	if err != nil {
		return err
	}
	client, err := resolveClientForEmail(ctx, email, flags)
	if err != nil {
		return err
	}
	if err := store.DeleteToken(client, email); err != nil {
		return err
	}
	return writeResult(ctx, u,
		kv("deleted", true),
		kv("email", email),
		kv("client", client),
	)
}

1. 破坏性操作保护:dry-run 与二次确认

dryRunAndConfirmDestructive(定义于 internal/cmd/confirm.go)先执行 dryRunExit,再调用 confirmDestructiveChecked:

func dryRunAndConfirmDestructive(ctx context.Context, flags *RootFlags, op string, request any, action string) error {
	if err := dryRunExit(ctx, flags, op, request); err != nil {
		return err
	}
	return confirmDestructiveChecked(ctx, flagsWithoutDryRun(flags), action)
}

这意味着:

  • 传入 --dry-run(或 --noop / --preview)时,命令打印意图(deleted、email、client 等信息)后直接成功退出,不会真正删除;
  • 未指定 --force 时,终端会弹出确认提示,回答非 y 将返回退出码 1 并取消操作;
  • 只有传入 -y / --force / --assume-yes / --yes 才跳过确认——这一点对 CI 与批处理脚本尤其重要,建议与 --no-input 一并使用以确保在无 TTY 环境下的确定性。

2. 打开密钥存储(keyring)

openAuthSecretsStore 打开 gogcli 的 secrets store(默认基于系统 keyring)。删除操作因此作用于操作系统密钥环中持久化的 OAuth 凭据,而不是内存会话,重启后删除依然生效。

3. 解析 OAuth client

resolveClientForEmail(见 internal/cmd/client_helpers.go)将 --client Flags 中的显式覆盖值与邮箱一起交给 authclient.ResolveClientWithOverride:

func resolveClientForEmail(ctx context.Context, email string, flags *RootFlags) (string, error) {
	override := resolveClientOverride(flags)
	return authclient.ResolveClientWithOverride(ctx, email, override)
}

即:若用户显式指定 --client,优先使用之;否则根据邮箱在已配置的 OAuth client 中自动解析。

4. 底层删除:KeyringStore.DeleteToken 的多键清理

真正执行删除的是 internal/secrets/token.go 中的 KeyringStore.DeleteToken:

func (s *KeyringStore) DeleteToken(client string, email string) error {
	return s.withWriteLock(func() error {
		return s.deleteTokenNoLock(client, email)
	})
}

deleteTokenNoLock 展示了删除操作的完整语义,它不止删除一个键:

  1. 规范化 email(小写/去空白)与 client 名称,避免因大小写差异留下孤儿凭据;
  2. 读取令牌以获取 Subject(服务账号场景);
  3. 删除主键 token:<client>:<email>(键格式见 internal/secrets/token.go);
  4. 若使用的是默认 OAuth client,额外删除遗留格式的旧键 token:<email>,兼容历史版本迁移数据;
  5. 若令牌带有 Subject,再删除 subject 键 token-sub:<client>:<subject>,防止按主题索引的映射残留。

每次 ring.Remove 遇到 keyring.ErrKeyNotFound 都会被容忍(说明该键本就不存在),因此重复删除同一邮箱不会报错,具备幂等性。同时整个流程包在写入锁(withWriteLock)中,避免与并发的读/写操作产生竞态。

输出结果与脚本化

命令成功后会输出 deleted、email、client 三个字段(writeResult + kv 构造):

deleted	true
email	user@example.com
client	<resolved-client>

加 --json 后输出为 JSON:

gog auth tokens delete --json -y user@example.com
{"deleted":true,"email":"user@example.com","client":"default"}

--plain / --tsv 则输出无颜色、稳定的 TSV 文本,适合 grep/awk 管道处理。

测试验证

仓库在 internal/cmd/auth_cmd_test.go 中给出了该命令的端到端行为验证:先用 --json auth tokens list 断言存在 2 个令牌键,随后执行

executeWithRuntime([]string{"--json", "--force", "auth", "tokens", "delete", "a@b.com"}, runtime)

并断言返回结果中 deleted=true、email=a@b.com;紧接着再次执行 auth tokens list 断言键列表已变为空。这组测试同时验证了:

  • 删除命令的 JSON 输出契约(deleted / email 字段);
  • --force 与 --json 的组合在无交互场景下可用;
  • 删除后 tokens list 同步反映存储状态。

与相邻凭据管理命令的分工

在 docs/commands/gog-auth-tokens-delete.md 的 “See Also” 中,该命令与以下文档关联,构成完整的凭据管理闭环:

如果需要删除账号及其关联凭据(而非仅删除某个 token),请使用 gog auth remove;若仅想移除某条 keyring 凭据,可参考 gog auth credentials remove。此外,gog auth tokens 组内的 export / import 支持令牌的迁移与备份,配合 delete 即可实现“导出 → 迁移 → 清理源机”的完整凭据转移流程。

安全实践建议

  • 删除前先演练:使用 --dry-run 预览将删除的邮箱与 client,确认无误后再加 -y 执行。
  • 脚本中固定输出格式:CI 中建议 --json --no-input -y 三件套,保证无提示、结果可解析、不会被交互卡住。
  • 迁移后清理源机:在旧机器执行 gog auth tokens delete <email>,确保 refresh token 不再残留在 keyring 中。
  • 多 client 场景显式指定:当同一邮箱对应多个 OAuth client 时,务必用 --client 精确指定,避免删错目标凭据。
  • 配合只读模式审计:--readonly 主要约束 API 调用,删除操作属本地凭据管理,具体安全策略可参考 safety-profiles.md 与 safety-profiles/ 下的示例配置(如 agent-safe.yaml),在 Agent 场景下控制命令可用范围。

小结

gog auth tokens delete 表面上是“删一个令牌”,实际实现中体现了 gogcli 对凭据安全的细致处理:键名规范化、多键级联清理、遗留格式兼容、keyring 写入锁、dry-run 预览与破坏性确认一应俱全。掌握本命令及其 Flags,配合 list / export / import,即可在终端中完成完整、可控的 Google Workspace 凭据生命周期管理。

登录后查看全文
gogcli