Auth Flow · workflow

auth-token-flow-audit

23-auth-token-flow-audit.md

🔐

P1 source: codex-sessions created: 2026-06-13

◉

WHAT IS THIS

定位

跨 repo token flow 审计 workflow。适合 cdc-web、Spring Boot 后端、AIDA authorize、desktop callback、agent token exchange、logout 清理这类多层认证链路。

这个 workflow 的核心判断是：先画清 token 应该在哪一层交换、存储和使用，再写代码。不要把 exchange 放到错误层级。

⚡

TRIGGERS

触发场景

▸前端、agent backend、desktop 都在处理同一登录态。

▸Access-Token、agent token、backend token、AIDA token id 混用。

▸Login 成功，但 AI chat、tool backend、desktop callback 认证失败。

▸用户指出 token exchange 应该发生在另一层。

▸登出、修改密码、切换 endpoint 后旧 token 未清理。

↹

INPUT & OUTPUT

输入 / 产出

↘ INPUT

登录入口和 callback URL。
Token 类型列表。
前端 token storage。
Agent auth endpoints。
Spring Boot token exchange endpoint。
Desktop config path 或 keychain/storage。
Logout/removeToken 代码路径。
相关测试。

↗ OUTPUT

Token flow diagram。
每种 token 的 owner、scope、storage、lifetime、清理规则。
错误层级修正 patch。
Auth regression tests。
手工 smoke 步骤。

🪜

STEPS

编排步骤

1
列 token 类型
明确 backend token、agent token、AIDA token id、callback code、session token 的用途。
2
画 owner flow
标出每个 token 在哪一层生成、交换、存储、读取、清理。
3
查当前实现
用 rg 找 login、authorize、exchange、readToken、removeToken、callback、tool auth。
4
找层级错误
判断 exchange 是该在 frontend、agent backend 还是 Spring Boot。不要因为调用方便就放在 UI。
5
修 canonical flow
只让 owner 层处理 token exchange。Consumer 只读取被允许的 token 或 token id。
6
清理 logout 路径
登出、修改密码、endpoint 变更、token 过期都必须清理相关 token。
7
补测试和 smoke
覆盖 login success、exchange failure、callback、logout、tool request auth header。

⚙

AGENT ROLES

Agent 分工

⚙

Flow Mapper

画 token flow。

⚙

Frontend Agent

检查 UI token storage 和 readToken。

⚙

Agent Backend Agent

检查 authorize/exchange/token provider。

⚙

Spring Backend Agent

检查 exchange contract。

⚙

Desktop Agent

检查 callback 和 config storage。

⚙

Verifier Agent

跑 tests 和登录 smoke。

✓

ACCEPTANCE GATE

验收 gate

✓每种 token 有唯一 owner。
✓Exchange 只发生在 canonical 层。
✓前端不存不该持有的 token。
✓Tool backend request 使用正确 token。
✓Logout 和 endpoint 切换会清理旧 token。
✓Auth tests 覆盖成功和失败路径。
✓Smoke 能从登录入口走到目标业务请求。

⊘

FAILURE HANDLING

失败处理

⊘

如果 token contract 不清楚，先写 ADR，不继续散改。

⤳

如果需要后端新接口，转 →#01。

⤳

如果 desktop callback 或真实登录 smoke 失败，转 →#22。

⌘

TEMPLATE

Flow 模板

TEMPLATE

| Token | Owner | Created by | Stored in | Used by | Cleared by |
| --- | --- | --- | --- | --- | --- |