/home/techb158/cosmic.abdallabala.com/docs
Edit: /home/techb158/cosmic.abdallabala.com/docs/15-step-7-1-oauth-live-connectors.md (4545B)
# Step 7.1, OAuth Credentials and Live PM API Clients
## Purpose
This step converts the previous local PM adapter simulation into a real integration boundary for Trello, Jira, Asana, and Microsoft Planner.
The live clients remain controlled by a safety flag so the prototype does not create external work items by accident.
```text
COSMIC_LIVE_PM_ENABLED=true
```
When the flag is not set, the dashboard still supports the simulated integration workflow from Step 6.
## Source alignment
This is an implementation extension of the COSMIC-Risk source direction. The source deck defines a software prototype, REST API, risk analysis engine, and integration with project management tools. This step operationalizes that direction through OAuth and live API clients.
## Security rules
1. Do not hardcode credentials.
2. Do not commit `.env` files.
3. Use `.env.example` only as a template.
4. Store OAuth tokens only when `COSMIC_TOKEN_ENCRYPTION_KEY` is configured.
5. Keep `COSMIC_LIVE_PM_ENABLED=false` until each connector is tested.
6. Use test boards, test projects, and test plans before connecting production workspaces.
## Added backend modules
| File | Role |
|---|---|
| `src/integrations/oauthProviderConfig.js` | Provider OAuth configuration and authorization URL builder |
| `src/services/oauthService.js` | OAuth state handling, token exchange, encrypted token storage |
| `src/security/tokenVault.js` | AES-256-GCM token encryption and redaction |
| `src/integrations/livePmClientFactory.js` | Creates provider-specific live PM clients |
| `src/integrations/pmClients/trelloClient.js` | Trello REST client |
| `src/integrations/pmClients/jiraClient.js` | Jira Cloud REST client |
| `src/integrations/pmClients/asanaClient.js` | Asana REST client |
| `src/integrations/pmClients/plannerClient.js` | Microsoft Graph Planner client |
| `public/oauth-trello-token.html` | Captures Trello token returned in URL fragment |
## New API endpoints
```text
GET /api/oauth/providers
GET /api/oauth/{provider}/status
GET /api/oauth/{provider}/authorize
GET /api/oauth/{provider}/callback
POST /api/oauth/Trello/store-token
GET /api/integrations/{integrationId}/live/status
POST /api/integrations/{integrationId}/live/test
POST /api/integrations/{integrationId}/live/sync
```
## Provider mapping
| Provider | Auth model | Risk object | Mitigation object | Required external target |
|---|---|---|---|---|
| Trello | API key + user token, or Trello OAuth token | Card | Checklist item | Trello list ID |
| Jira | OAuth 2.0 3LO, or API-token basic auth fallback | Issue | Sub-task or linked issue | Jira project key |
| Asana | OAuth 2.0 authorization code | Task | Subtask | Asana project GID |
| Microsoft Planner | Microsoft Graph OAuth 2.0 | Planner task | Checklist/details extension boundary | Plan ID and bucket ID |
## Environment variables
Use `.env.example` as the template. The current native Node.js prototype does not load `.env` automatically. Export variables in the shell before starting the app, or use a process manager that injects them.
Example:
```bash
export COSMIC_TOKEN_ENCRYPTION_KEY="replace-with-long-random-secret"
export COSMIC_LIVE_PM_ENABLED="true"
export TRELLO_API_KEY="..."
export TRELLO_TOKEN="..."
export TRELLO_LIST_ID="..."
node server.js
```
## Live sync behavior
When live mode is enabled:
1. The connector reads credentials from environment variables or encrypted stored OAuth tokens.
2. The connector tests the external account.
3. Each COSMIC risk is created or updated as an external work item.
4. Mitigation actions are sent where the provider supports a direct structure.
5. External IDs and URLs are stored in `external_work_item_mappings`.
6. A `project_management_sync_runs` record is created.
7. An audit event records the live sync.
When live mode is disabled:
1. The `/live/test` endpoint returns a dry-run message.
2. The `/live/sync` endpoint falls back to the local simulated sync.
3. No third-party API is called.
## Database additions
```text
oauth_states
oauth_tokens
project_management_integrations.live_enabled
project_management_integrations.live_config_json
project_management_sync_runs.failure_json
```
## Validation
The following test was added:
```bash
npm run test:oauth
```
It verifies:
1. OAuth authorization URL construction.
2. Credential status detection.
3. Token encryption and redaction.
4. Stored token availability.
5. Live status hints.
6. Dry-run protection.
7. Trello live client request construction with a mock fetch implementation.