# Trello Plugin — Authentication & Connection

**Feature:** US: Authenticate and Connect to Trello Account
**Issue:** #1
**Branch:** `feature/trello-auth`
**Doc:** 001

## Overview

This feature provides the authentication layer for the Trello plugin. Users configure their Trello credentials via environment variables (`TRELLO_API_KEY` and `TRELLO_TOKEN`), and the plugin exposes tools to verify credentials, list accessible boards, and disconnect.

## Design Decisions

- **No interactive credential input** — The Hermes Agent has no UI for prompting users. Credentials are set in the profile's `.env` or `config.yaml` as environment variables, which is the standard Hermes pattern.
- **Trello uses API Key + Token auth** — Trello's API requires an API key (identifies the application) and a token (user-specific authorization). Both are required for any API call.
- **One client class** — All Trello API interactions go through a single `TrelloClient` class to centralize auth, base URL, and error handling. Future features (boards, lists, cards) will extend this same client.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TRELLO_API_KEY` | Yes | Trello API application key |
| `TRELLO_TOKEN` | Yes | Trello user authorization token |

## Tools Exposed

### 1. `trello_verify_credentials`

Verifies that `TRELLO_API_KEY` and `TRELLO_TOKEN` are set and the Trello API responds successfully.

**Parameters:** None

**Returns:**
```json
{
  "success": true,
  "message": "✓ Trello credentials verified successfully (authenticated as user@example.com)"
}
```

On failure:
```json
{
  "success": false,
  "message": "✗ Trello authentication failed: invalid key"
}
```

### 2. `trello_list_boards`

Fetches and returns all Trello boards accessible to the authenticated user.

**Parameters:** None

**Returns:**
```json
{
  "success": true,
  "boards": [
    {"id": "abc123", "name": "My Project Board", "url": "https://trello.com/b/abc123"},
    {"id": "def456", "name": "Personal Tasks", "url": "https://trello.com/b/def456"}
  ]
}
```

### 3. `trello_disconnect`

Clears the stored credentials from memory. Note: this does not revoke the Trello token — the user must invalidate it via Trello's settings if needed.

**Parameters:** None

**Returns:**
```json
{
  "success": true,
  "message": "Trello credentials cleared. Set TRELLO_API_KEY and TRELLO_TOKEN again to reconnect."
}
```

## API Contract

### Internal: `TrelloClient`

```python
class TrelloClient:
    def __init__(self, api_key: str | None = None, token: str | None = None)

    def verify_credentials(self) -> dict
    def list_boards(self) -> list[dict]
    def disconnect(self) -> dict
```

### Trello API Endpoints Used

| Purpose | Method | Endpoint | Docs |
|---------|--------|----------|------|
| Verify credentials | GET | `/1/members/me` | https://developer.atlassian.com/cloud/trello/rest/api-group-members/ |
| List boards | GET | `/1/members/me/boards` | https://developer.atlassian.com/cloud/trello/rest/api-group-boards/ |

## Error Handling

- Missing env vars → return `{"success": false, "message": "TRELLO_API_KEY and TRELLO_TOKEN must be set"}` with env var name
- Network errors → catch `requests.exceptions.RequestException` and return descriptive message
- Auth failures (401/403) → clear message about invalid credentials
- Rate limiting → Trello returns 429; surface the retry-after header

## Testing

- Unit tests with mocked HTTP responses
- Test all error paths: missing creds, invalid creds, network error, rate limit
- Test successful verification via mock that returns member info
- Test board listing with mock JSON response