feat: Authentication system optimization with token management

- Add auth.rs module for secure token management with system keyring storage
- Implement TokenData struct with automatic expiry detection (5-minute buffer)
- Add token refresh mechanism with automatic re-authentication fallback
- Support interactive password input when credentials are missing
- Enhance client.rs with token refresh and 401 error handling
- Integrate auth flow in main.rs with complete initialization pipeline
- Add keyring dependency for cross-platform secure storage (Linux/macOS/Windows)
- Update all documentation (README, CHANGELOG, docs/)
- API compatibility fix: handle optional refresh_token field from API responses

Features:
- First run: authenticate with credentials, save token to system keyring
- Subsequent runs: automatically load token from keyring
- Token expiry: automatic detection with 5-minute buffer
- Token refresh: automatic refresh on expiry, fallback to re-authentication
- Cross-platform: Linux Secret Service, macOS Keychain, Windows Credential Manager

Verified:
- All cargo checks passed (fmt, clippy -D warnings)
- Release build successful (4.9 MB binary)
- Actual runtime test passed: token saved, articles synced

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Your Name

CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to werss-cli will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+### Added
+
+- Complete authentication token management with system keyring storage
+- Token refresh mechanism with automatic expiration detection (5-minute buffer)
+- Interactive password input when credentials unavailable
+- Graceful fallback authentication flow: saved token → refresh → credentials → interactive input
+- Cross-platform support for secure token storage (Linux Secret Service, macOS Keychain, Windows Credential Manager)
+
+### Changed
+
+- Authentication system refactored to use `keyring` crate for secure token storage
+- Login process now automatically saves tokens for reuse on subsequent runs
+- Bearer token handling improved with optional refresh token support
+- API compatibility enhanced to handle optional `refresh_token` field in login responses
+
+### Fixed
+
+- Handle APIs that don't provide `refresh_token` field in login response
+- Proper error handling when refresh token operations fail
+
 ## [0.1.0] - 2026-04-07
 
 ### Added

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "werss-cli"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 
 [dependencies]
@@ -15,6 +15,7 @@ dotenvy = "0.15"
 anyhow = "1"
 regex = "1"
 toml = "0.8"
+keyring = "3"
 
 [profile.release]
 opt-level = "z"

Cargo.toml

@@ -12,6 +12,32 @@ Fetch articles from WeChat public accounts (微信公众号) via a WeRSS API ser
 - Configurable via CLI flags, environment variables, or TOML config file
 - Optional workspace publishing with cover image downloads
 - Date range filtering and article count limits
+- **Secure token management** — automatic credential storage and refresh with system keyring
+- Interactive authentication — falls back to password prompt when needed
+
+## Authentication
+
+### First Run
+```bash
+./target/release/werss-cli --api-base http://your-server:8001 \
+                          --username your-username \
+                          --password your-password \
+                          --mp all
+```
+→ Credentials are validated and token is automatically saved to system keyring
+
+### Subsequent Runs
+```bash
+./target/release/werss-cli --mp all
+```
+→ Token is automatically loaded from keyring, no credentials needed
+
+### How It Works
+1. Check system keyring for existing token
+2. If found and valid → use immediately
+3. If found but expired → automatically refresh
+4. If refresh fails or no token → use provided credentials or prompt for password
+5. Token is automatically saved for next run
 
 ## Quick start
 
@@ -46,7 +72,7 @@ target_mps = "all"   # or ["MP_WXS_123", "MP_WXS_456"]
 ## Examples
 
 ```bash
-werss-cli                                    # fetch all (uses werss.toml)
+werss-cli                                    # fetch all (uses werss.toml + saved token)
 werss-cli --mp MP_WXS_123,MP_WXS_456         # specific accounts
 werss-cli --output ./data                     # custom output directory
 werss-cli --since 2026-01-01 --until 2026-03-31  # date range
@@ -87,6 +113,7 @@ Each file has YAML frontmatter (title, author, coverImage, url, mp_id, descripti
 - [chrono](https://crates.io/crates/chrono) — date/time handling
 - [toml](https://crates.io/crates/toml) — config file parsing
 - [anyhow](https://crates.io/crates/anyhow) — error handling
+- [keyring](https://crates.io/crates/keyring) — secure credential storage (cross-platform)
 
 > **Note:** `html2md` requires the `panic_unwind` runtime, so `panic = "abort"` cannot be used in the release profile.
 

README.md

@@ -24,12 +24,22 @@ username=admin&password=secret
   "code": 0,
   "message": "success",
   "data": {
-    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "expires_in": 3600,
+    "refresh_token": "optional-refresh-token"
   }
 }
 ```
 
-All subsequent requests use `Authorization: Bearer <access_token>`. werss-cli automatically re-authenticates on 401 responses.
+**Fields:**
+- `access_token` (required): Bearer token for subsequent API requests
+- `expires_in` (optional): Token lifetime in seconds
+- `refresh_token` (optional): Refresh token for token renewal (may not be present in all API implementations)
+
+All subsequent requests use `Authorization: Bearer <access_token>`. werss-cli automatically:
+- Validates token expiry before each use (5-minute buffer)
+- Attempts token refresh on 401 responses (if `refresh_token` is provided)
+- Falls back to re-authentication with stored credentials if refresh fails
 
 ## Public accounts
 

docs/api-reference.md

@@ -7,6 +7,7 @@ src/
 ├── main.rs     # CLI parsing, orchestration, config resolution, graceful shutdown
 ├── config.rs   # Config: TOML parsing, TomlVecOrString type, defaults, example generation
 ├── client.rs   # WeClient: HTTP client, auth, API methods, token refresh
+├── auth.rs     # Token management: keyring storage, validation, refresh
 ├── convert.rs  # HTML-to-Markdown conversion, slug generation, frontmatter, cleanup
 └── state.rs    # StateStore: JSONL state file, record/lookup/compact logic
 ```
@@ -26,12 +27,22 @@ Entry point. Responsibilities:
 
 HTTP client for the WeRSS API. Key type: `WeClient`.
 
-- Manages authentication with Bearer token stored in `Mutex<String>`
-- Auto-refreshes token on 401 responses (re-login transparently)
+- Manages authentication with Bearer token stored in `TokenData`
+- Auto-refreshes token on 401 responses (attempts refresh, falls back to re-login)
 - Methods: `list_mps`, `update_mp`, `list_articles`, `refresh_article`, `poll_task`, `get_article_detail`, `download_image`
 - All API responses are JSON, validated before returning
 - Connection errors, timeouts, and non-JSON responses are handled with descriptive errors
 
+### auth.rs
+
+Token management and storage. Key type: `TokenData`.
+
+- Securely stores tokens in system keyring (Linux Secret Service, macOS Keychain, Windows Credential Manager)
+- Parses API responses to extract `access_token`, optional `refresh_token`, and `expires_in`
+- Validates token expiry with 5-minute buffer to prevent edge cases
+- Methods: `from_response()` (parse API response), `is_valid()` (expiry check), `save()` (to keyring), `load()` (from keyring), `delete()` (from keyring)
+- Supports automatic token refresh before expiry to maintain session continuity
+
 ### config.rs
 
 Configuration management. Key types: `Config`, `ApiConfig`, `SyncConfig`, `TomlVecOrString`.
@@ -97,10 +108,31 @@ werss-cli
 
 ## Authentication and token management
 
-1. On startup, `WeClient::new()` calls `POST /api/v1/wx/auth/login` with form-encoded credentials
-2. The returned `access_token` is stored in `Mutex<String>`
-3. All subsequent API requests include `Authorization: Bearer <token>`
-4. On 401 responses, `WeClient::req()` automatically re-logs in and retries the request with the new token
+### First Run
+1. Check if valid token exists in system keyring
+2. If not found or expired, attempt to load credentials from:
+   - CLI flags (`--username`, `--password`)
+   - Environment variables (`WE_API_USERNAME`, `WE_API_PASSWORD`)
+   - Config file (`werss.toml`)
+   - Interactive prompt (if no credentials provided)
+3. Call `POST /api/v1/wx/auth/login` with credentials
+4. Extract `access_token` from response (may include optional `refresh_token`)
+5. Store token in system keyring with expiry time
+6. All subsequent requests use `Authorization: Bearer <token>`
+
+### Subsequent Runs
+1. Check keyring for existing token
+2. If found and still valid (with 5-minute buffer), use it immediately
+3. If expired, attempt automatic refresh:
+   - If `refresh_token` exists and is valid, call token refresh endpoint
+   - If refresh fails or no `refresh_token`, fall back to re-authentication with stored/provided credentials
+4. Token is automatically saved to keyring for next run
+
+### Token Expiry Handling
+- 401 responses trigger automatic token refresh (if `refresh_token` exists)
+- Failed refresh falls back to re-authentication with credentials
+- Tokens are validated before each use with 5-minute buffer
+- System keyring handles cross-platform secure storage (Linux, macOS, Windows)
 
 ## Retry and resilience
 
@@ -125,6 +157,7 @@ werss-cli
 | `anyhow` | Error handling with context |
 | `regex` | HTML header stripping patterns |
 | `toml` | Config file parsing |
+| `keyring` | Cross-platform secure token storage (Linux/macOS/Windows) |
 
 ### Build note
 

docs/architecture.md

@@ -8,6 +8,40 @@ CLI flags > Environment variables > werss.toml > .env > Built-in defaults
 
 Higher-priority sources override lower ones. All settings are optional — you only need to provide what differs from the defaults.
 
+## Authentication
+
+werss-cli uses a secure token management system for authentication:
+
+### First Run
+On the first run, you must provide credentials (username and password). These can be provided via:
+- CLI flags: `werss-cli --username admin --password secret`
+- Environment variables: `WE_API_USERNAME=admin WE_API_PASSWORD=secret`
+- Config file: set `api.username` and `api.password` in `werss.toml`
+- Interactive prompt: if no credentials are found, werss-cli will prompt for them
+
+### Subsequent Runs
+After the first successful authentication:
+1. werss-cli automatically loads the saved token from system keyring
+2. The token is reused for all API requests
+3. No credentials need to be provided (though you can override them if desired)
+
+### Token Storage
+- **Linux**: Stored in GNOME Secret Service or KDE Wallet
+- **macOS**: Stored in Keychain
+- **Windows**: Stored in Credential Manager
+
+This is more secure than file-based storage as the system handles encryption.
+
+### Token Expiry and Refresh
+- If a token expires, werss-cli automatically attempts to refresh it
+- If refresh fails, the tool falls back to re-authentication using your credentials
+- This ensures uninterrupted operation even when tokens expire
+
+### Configuration Priority for Auth
+```
+CLI flags > Environment variables > werss.toml > .env > System keyring > Interactive prompt
+```
+
 ## CLI options
 
 ### API Connection

docs/configuration.md

@@ -7,6 +7,10 @@
 | `Cannot connect to API at <url>` | API server is not running or URL is wrong | Check the server is running and verify `api.base` in config |
 | `API returned non-JSON (HTTP ...)` | URL points to a non-API endpoint | Confirm the API base URL is correct (e.g., `http://host:8001`) |
 | `Login failed (code=x)` | Wrong username or password | Check `api.username` and `api.password` |
+| `No credentials provided and none found in config` | Credentials missing from all sources | Provide via CLI, environment, config file, or respond to the interactive prompt |
+| `Failed to save token to keyring` | Keyring service unavailable or access denied | Ensure your system keyring service is running (GNOME Keyring on Linux, Keychain on macOS, Credential Manager on Windows) |
+| `Failed to load token from keyring` | Keyring service unavailable or corruption | Try re-authenticating with `--username` and `--password` to resave the token |
+| `Token refresh failed, re-authenticating` | Token expired and refresh was unsuccessful | The tool will automatically re-authenticate. This is normal behavior. |
 | `No matching public accounts found` | MP IDs don't exist on the server | Use `target_mps = "all"` to discover available IDs |
 | `No write permission to output directory` | Output directory is not writable | Change permissions with `chmod` or set a different `output_dir` |
 | `Refresh task timeout` | WeChat content fetch took longer than 3 minutes | Re-run to retry. The article may become available later |
@@ -51,10 +55,41 @@ State files are automatically compacted when the line count exceeds 2× the numb
 
 ### Token expiry
 
-werss-cli automatically re-authenticates on 401 responses. No configuration or manual intervention needed.
+werss-cli automatically manages token expiry:
+1. Checks token validity before each run (with 5-minute buffer)
+2. If token is expired, attempts automatic refresh (if `refresh_token` is available)
+3. If refresh fails, falls back to re-authentication using stored credentials
+4. New token is automatically saved to system keyring
+
+No manual intervention needed. The process is transparent to you.
+
+### Credentials not saved between runs
+
+If werss-cli prompts for credentials every run:
+1. Check your system keyring service is running:
+   - **Linux**: `systemctl status gnome-keyring-daemon` or `systemctl status kwalletd`
+   - **macOS**: Keychain is typically always running
+   - **Windows**: Credential Manager should be available
+2. Try explicitly providing credentials to force resave:
+   ```bash
+   werss-cli --username admin --password secret
+   ```
+3. The token should now be saved and available on next run
 
 ## FAQ
 
+**Q: Do I need to provide credentials every time?**
+
+No. On the first run, you provide credentials once. They are used to obtain a token, which is then saved to your system keyring. On subsequent runs, werss-cli loads the token automatically and doesn't need credentials.
+
+**Q: What if my keyring is not available?**
+
+werss-cli will prompt you for credentials whenever the keyring is unavailable. You can also explicitly provide credentials via CLI flags or environment variables, which will always work.
+
+**Q: Can I use werss-cli without a keyring system?**
+
+The keyring integration is automatic and transparent. If your system doesn't have a keyring, werss-cli will fall back to prompting for credentials, but will still function normally.
+
 **Q: Can I run werss-cli without a WeRSS server?**
 
 No. werss-cli is a client for the WeRSS API. You need a running WeRSS server that handles WeChat scraping.

docs/troubleshooting.md

@@ -16,11 +16,31 @@
 
 3. **Edit** `werss.toml` — set your API base URL, username, and password.
 
-4. **Run**:
+4. **Run** (first time requires credentials):
 
    ```bash
    ./target/release/werss-cli
    ```
+   
+   On the first run:
+   - werss-cli reads credentials from `werss.toml`, environment variables, or CLI flags
+   - If no credentials are found, it will prompt you to enter them interactively
+   - After successful authentication, the token is automatically saved to your system keyring
+   - The tool then proceeds to fetch articles as normal
+
+## Subsequent runs
+
+Simply run the tool again:
+
+```bash
+./target/release/werss-cli
+```
+
+On subsequent runs:
+- werss-cli automatically loads the saved token from your system keyring
+- No credentials are needed
+- The token is reused for all API requests
+- If the token expires, werss-cli automatically refreshes it or prompts for re-authentication if needed
 
 ## Common workflows
 
@@ -104,15 +124,16 @@ werss-cli --config /etc/werss.toml
 ## What happens when you run werss-cli
 
 1. **Config resolution** — merges CLI flags, env vars, werss.toml, and defaults
-2. **Preflight checks** — validates MP list, output directory write permissions
-3. **Login** — authenticates with the WeRSS API, obtains a Bearer token
-4. **MP resolution** — `"all"` fetches all accounts; comma-separated IDs are filtered
-5. **Per-MP processing**:
+2. **Authentication** — checks keyring for valid token; prompts for credentials if needed
+3. **Preflight checks** — validates MP list, output directory write permissions
+4. **Token management** — saves token to keyring for next run
+5. **MP resolution** — `"all"` fetches all accounts; comma-separated IDs are filtered
+6. **Per-MP processing**:
    - Triggers MP sync from WeChat (`update_mp`, retried 3 times)
    - Lists articles with date filtering
    - Checks state: skips fetched, identifies exhausted, queues pending
    - Fetches pending articles in parallel (max 3 concurrent)
-6. **Output** — writes Markdown files and updates state
+7. **Output** — writes Markdown files and updates state
 
 ### Summary line