gogcli 凭据管理:`gog auth tokens delete` 删除 Refresh Token 的命令详解与实现原理
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; runmake 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 展示了删除操作的完整语义,它不止删除一个键:
- 规范化
email(小写/去空白)与client名称,避免因大小写差异留下孤儿凭据; - 读取令牌以获取
Subject(服务账号场景); - 删除主键
token:<client>:<email>(键格式见 internal/secrets/token.go); - 若使用的是默认 OAuth client,额外删除遗留格式的旧键
token:<email>,兼容历史版本迁移数据; - 若令牌带有 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” 中,该命令与以下文档关联,构成完整的凭据管理闭环:
- gog auth tokens — 子命令组入口
- gog auth — 认证命令组入口
- Command index — 全命令索引
如果需要删除账号及其关联凭据(而非仅删除某个 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 凭据生命周期管理。