# Auth Module

Authenticate with ChatArt using the OAuth 2.0 Device Authorization Grant.
Run once — credentials are saved locally and auto-loaded by all other modules.

## Subcommands

| Subcommand | Description |
|------------|-------------|
| `login`  | Full flow: init → open browser → poll → save credentials |
| `poll`   | Resume a previously interrupted login (recovery only) |
| `logout` | Remove saved credentials file |
| `status` | Show current login state (uid, email, name, masked api_key) |
| `accountswitch` | Switch to a different account (unbind device + re-login) |

## Usage

```bash
python {baseDir}/scripts/auth.py <subcommand>
```

## `login` — Complete Login Flow

```bash
python {baseDir}/scripts/auth.py login
```

This single command handles the **entire login flow**:
1. Calls the remote OAuth server to start a device session
2. Opens the authorization page in the user's browser
3. Automatically polls until the user authorizes (or the session expires)
4. Saves credentials to `~/.ChatArt/credentials.json` on success

**The agent must extract the `URL:` from the login output and send it to the user as a clickable link.**

Many users are in chat apps (Feishu, etc.) and **cannot see browser popups**. The script does call `webbrowser.open()` but this may not be visible — the direct link is the only reliable way.

### Full sequence

```
Agent runs:  python auth.py login
                 ↓ script prints URL and opens browser (user may not see the browser)
                 ↓ command keeps polling automatically in background
Agent sends user: the direct authorization link (see SKILL.md login template)
                 ↓ user clicks the link, logs in, clicks Authorize
                 ↓ command detects approval, saves credentials
Credentials saved to ~/.ChatArt/credentials.json ✓
```

### What to send the user

Extract the `URL: https://...` line from the login output and use the login message template from SKILL.md. The template includes both Chinese and English versions — pick the one matching the user's language.

**Do NOT say** "浏览器已经打开" or "请在浏览器中操作" or "去那台电脑上看" — the user cannot see the browser or the machine running the agent.

**Do NOT tell the user to register at chatartpro.com first.** The authorization page includes both login and registration. New users can sign up directly on that page.

**Do NOT ask the user "which method do you want?"** — just run `auth.py login`, get the link, and send it. Login is a means, not a choice to present.

### If the URL is missing from the output

If `auth.py login` was run in the background or the output was not captured and you cannot find the `URL:` line:

1. **Re-run `auth.py login`** to start a new session and capture the URL this time.
2. **NEVER** fall back to telling the user to "check the browser popup" or "go to the computer". The user **cannot** see the agent's machine.
3. The old session will expire on its own — starting a new one is safe.

## `poll` — Resume Interrupted Login

```bash
python {baseDir}/scripts/auth.py poll
```

Use **only** if `login` was interrupted (e.g., terminal closed during polling).
Reads the pending session from `~/.ChatArt/pending_device.json` and resumes polling.

## `status` — Check Login State

```bash
python {baseDir}/scripts/auth.py status
```

Output when logged in:

```
Logged in
  uid:         NsDAaOPF4jLuAie4ewyg
  name:        John Doe
  email:       user@example.com
  api_key:     sk-...3HB
  charge_type: pro
  authorized:  2026-03-04T10:00:00+00:00
  file:        /Users/you/.ChatArt/credentials.json
```

## `logout` — Remove Credentials

```bash
python {baseDir}/scripts/auth.py logout
```

## `accountswitch` — Switch Accounts

```bash
python {baseDir}/scripts/auth.py accountswitch
```

Use this command when you need to switch to a different ChatArt account on the same device.

### What it does
1. Calls the server to unbind the current device from the logged-in account
2. Removes the local credentials file (~/.ChatArt/credentials.json)
3. Automatically starts a new login flow (same as login)
4. Opens the authorization page and polls for the new account's approval

### Important Notes
**Before switching accounts, it is recommended to:**
- Log out of your ChatArt web account on the website, OR
- Log in with the new account you want to switch to on the website

This ensures a smooth transition between accounts and prevents potential conflicts.

### When to use
- User wants to switch from ChatArt Account A to Account B

## Credential File

Saved at: `~/.ChatArt/credentials.json`. File permissions are set to `0600` (owner read/write only).

## Credential Load Priority

All modules use `shared/config.py` which loads credentials in this order:

1. Environment variables `CHATART_UID` + `CHATART_API_KEY` (CI/scripting)
2. `~/.ChatArt/credentials.json` (set by `auth.py login`)
3. Error — prompts to run `auth.py login`

## Agent Rules

- **NEVER** ask the user to run `python auth.py login` or any other command themselves.
- **NEVER** ask the user to set `CHATART_UID` or `CHATART_API_KEY` env vars manually.
- **NEVER** mention terminal output, browser popups, command lines, or environment variables to the user.
- **NEVER** tell the user to "go look at the browser", "check the popup", or "operate on the agent's computer". The user cannot see any of that.
- **NEVER** skip sending the login link. If you don't have the URL, re-run `auth.py login` to get it.
- **ALWAYS** run `auth.py login` yourself, extract the `URL:` from the output, and send the direct authorization link to the user.
- **ALWAYS** use the login message template from SKILL.md — keep it chat-friendly and beginner-level.
- **ALWAYS** wait for the user to confirm (e.g. "好了") before continuing the task.