docs: rename auth spec to 001_trello_auth_spec.md

2026-05-26 23:02:41 +00:00
parent 43acd5bfbf
commit 65fe867cf5
1 changed files with 1 additions and 0 deletions
@@ -0,0 +1,112 @@
+# 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