# OAuth Device Flow — CLI Agent Login Checklist

> OAuth device flow checklist for CLI and agent login. Covers user codes, polling intervals, token storage, logs, and security boundaries.

## Install

Copy the content below into your project:

---
title: OAuth Device Flow — CLI Agent Login Checklist
asset_kind: knowledge
target_tools: [codex, claude_code, cursor, gemini_cli]
install_mode: single
entrypoint: README.md
---

# OAuth Device Flow — CLI Agent Login Checklist

Use this checklist when an agent needs to design or review a CLI login flow that should work without opening an embedded browser. OAuth 2.0 Device Authorization Grant is the usual fit for terminals, SSH sessions, CI setup, and agent-controlled environments where copy-paste is safer than browser automation.

## Quick Use

The interaction should look like this:

```text
1. CLI asks the auth server for device_code + user_code.
2. CLI prints a verification URL and short user_code.
3. Human opens the URL in a normal browser and approves.
4. CLI polls the token endpoint at the allowed interval.
5. CLI stores the resulting token in the OS keychain or a permission-restricted config file.
```

The CLI must not ask the agent to scrape browser cookies, automate login pages, or paste passwords into terminal history.

## Implementation Checks

Verify these fields and behaviors:

| Check | Expected behavior |
|---|---|
| `device_code` | Secret to the CLI, never shown to the user. |
| `user_code` | Short enough to type, expires quickly. |
| `verification_uri` | HTTPS page controlled by the auth provider. |
| `interval` | CLI respects polling interval and backs off on `slow_down`. |
| Expiry | CLI stops polling when `expires_in` is reached. |
| Storage | Token is stored with local file permissions or keychain support. |

## Security Boundaries

- Do not log access tokens, refresh tokens, or device codes.
- Do not store tokens in the repo.
- Do not print full bearer headers in debug output.
- Do not ask an LLM agent to operate the user's browser session unless the user explicitly authorizes it.
- Prefer short-lived access tokens and rotate refresh tokens when supported.

## Agent Review Prompt

```text
Review this CLI OAuth device flow. Check polling interval handling, token storage,
error states, terminal output, and whether any secret can appear in logs,
shell history, repository files, or agent transcripts.
```

## Source & Thanks

This is an original TokRepo checklist by William Wang. It is based on OAuth 2.0 Device Authorization Grant in [RFC 8628](https://www.rfc-editor.org/rfc/rfc8628) and general OAuth security guidance from the [OAuth working group](https://oauth.net/2/).

<!-- ZH -->

# OAuth Device Flow：CLI Agent 登录清单

当 Agent 需要设计或审查 CLI 登录时，用这份清单。终端、SSH、CI 初始化和 Agent 环境不适合内嵌浏览器；OAuth 2.0 Device Authorization Grant 通常更安全。

## 快速使用

正确流程是：CLI 获取 `device_code` 和 `user_code`，打印验证 URL 和短码；人类在正常浏览器里打开并确认；CLI 按服务器给出的 interval 轮询 token endpoint；拿到 token 后存到 keychain 或权限受限配置文件。

## 安全边界

- 不记录 access token、refresh token、device code。
- 不把 token 写进仓库。
- debug 日志不要打印完整 bearer header。
- 不要求 LLM Agent 自动操作用户浏览器登录，除非用户明确授权。
- 支持时优先用短期 access token 和 refresh token rotation。


---
Source: https://tokrepo.com/en/workflows/oauth-device-flow-cli-agent-login-checklist-09df47ef
Author: henuwangkai