FlowPilot/docs/superpowers/plans/2026-04-10-hotmail-oauth-mail-pool.md

Hotmail OAuth Mail Pool Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a Hotmail account pool with Microsoft OAuth authorization and Microsoft Graph mail polling, then wire it into the existing automation flow as a new mail provider.

Architecture: Keep the existing 1~9 step orchestrator in background.js, add a new hotmail-api provider path, and extend the side panel to manage Hotmail accounts. Preserve QQ, 163, and Inbucket behavior while introducing account allocation, token management, and Graph-based verification-code retrieval.

Tech Stack: Chrome Extension MV3, plain JavaScript, chrome.identity.launchWebAuthFlow, fetch, chrome.storage.local, chrome.storage.session

---

Task 1: Extend State Model for Hotmail Accounts

Files:

• Modify: background.js

• Modify: README.md

• Step 1: Write the failing test

Document the expected account shape and provider behavior in code comments or development notes before implementation:

// Expected local storage shape:
// hotmailAccounts: [{ id, email, password, clientId, accessToken, refreshToken, expiresAt, status, lastUsedAt, lastAuthAt, lastError }]
// mailProvider accepts 'hotmail-api'

• Step 2: Run test to verify it fails

Run a manual smoke check by loading the current extension and confirming there is no hotmail-api provider and no persisted Hotmail account state.

Expected: The provider does not exist yet and account state is absent.

• Step 3: Write minimal implementation

Add new persisted keys and runtime state helpers in background.js:

• hotmailAccounts

• currentHotmailAccountId

• helper functions to read, write, upsert, delete, and mark account status

• Step 4: Run test to verify it passes

Reload the extension and confirm Hotmail account state can be read and written through background message handlers.

• Step 5: Commit

git add background.js README.md
git commit -m "feat: add hotmail account state model"

Task 2: Add Hotmail Account Pool UI

Files:

• Modify: sidepanel/sidepanel.html

• Modify: sidepanel/sidepanel.css

• Modify: sidepanel/sidepanel.js

• Step 1: Write the failing test

Describe the expected UI state:

• provider selector includes hotmail-api

• Hotmail account section renders a list

• user can add, authorize, test, and delete accounts

• Step 2: Run test to verify it fails

Reload the current extension.

Expected: No Hotmail provider option and no account section.

• Step 3: Write minimal implementation

Add:

• a new provider option

• a Hotmail accounts management section

• side panel event handlers for add, authorize, test, delete, and select current account status

• Step 4: Run test to verify it passes

Reload the extension and verify:

• the new provider is visible

• the section appears only when selected

• account rows render correctly from stored state

• Step 5: Commit

git add sidepanel/sidepanel.html sidepanel/sidepanel.css sidepanel/sidepanel.js
git commit -m "feat: add hotmail account pool panel"

Task 3: Implement Microsoft OAuth Authorization

Files:

• Modify: background.js

• Modify: manifest.json

• Step 1: Write the failing test

Define the expected authorization flow in a focused helper-oriented checklist:

• PKCE code verifier/challenge can be created

• auth URL includes client ID, redirect URI, state, scope, and challenge

• callback code is parsed and validated

• token response updates the account record

• Step 2: Run test to verify it fails

Trigger the new Authorize action from the side panel.

Expected: The action is not implemented yet and fails.

• Step 3: Write minimal implementation

Add background handlers and helpers for:

• PKCE generation

• OAuth URL creation

• chrome.identity.getRedirectURL()

• chrome.identity.launchWebAuthFlow

• code exchange via Microsoft token endpoint

• account token persistence and error reporting

• Step 4: Run test to verify it passes

Manually authorize a Hotmail account and confirm:

• the login flow opens

• tokens are saved to the target account

• account status becomes authorized

• Step 5: Commit

git add background.js manifest.json
git commit -m "feat: add microsoft oauth authorization"

Task 4: Implement Token Refresh and Graph Mail Polling

Files:

• Modify: background.js

• Step 1: Write the failing test

Define the expected helper behavior:

• expired access token refreshes with refresh_token

• Graph mail fetch returns recent inbox messages

• filtering returns the newest matching verification code after the requested timestamp

• Step 2: Run test to verify it fails

Use the side panel Test Mail Access action before implementing the Graph path.

Expected: The action fails because Graph mail polling does not exist yet.

• Step 3: Write minimal implementation

Add helpers in background.js for:

• token freshness check

• refresh-token grant request

• Graph inbox fetch

• mail filtering

• verification code extraction

• Step 4: Run test to verify it passes

Authorize a Hotmail account and verify the test action can fetch mailbox data and surface a success or meaningful “no matching mail” response.

• Step 5: Commit

git add background.js
git commit -m "feat: add graph mail polling"

Task 5: Wire Hotmail Provider into Step 3, Step 4, Step 7, and Auto Run

Files:

• Modify: background.js

• Modify: sidepanel/sidepanel.js

• Modify: README.md

• Step 1: Write the failing test

Define the expected run behavior:

• Auto mode chooses a fresh authorized Hotmail account for each new run

• Step 3 uses the selected account email and password

• Step 4 and Step 7 read verification mail through Graph instead of mailbox tabs

• Step 2: Run test to verify it fails

Select hotmail-api and run a manual or auto flow.

Expected: The flow cannot yet allocate an account or fetch verification codes from Graph.

• Step 3: Write minimal implementation

Update:

• provider branching in getMailConfig() or a replacement provider resolver

• account allocation at fresh run start

• Step 3 account-backed credentials

• Step 4 and Step 7 Graph polling path

• auto-run preconditions for Hotmail accounts

• Step 4: Run test to verify it passes

Run:

1. manual Step 3 + Step 4 on a selected account
2. manual Step 6 + Step 7 on the same account
3. one full Auto run with hotmail-api

Expected: no mailbox tab is opened for Hotmail, and verification codes come from Graph.

• Step 5: Commit

git add background.js sidepanel/sidepanel.js README.md
git commit -m "feat: integrate hotmail api provider into automation flow"

Task 6: Regression Verification and Cleanup

Files:

• Modify: README.md

• Step 1: Write the failing test

List the required regression checks:

• QQ provider still opens QQ mail tab

• 163 provider still opens 163 mail tab

• Inbucket provider still opens mailbox page

• Hotmail provider uses API path only

• Step 2: Run test to verify it fails

Manually inspect pre-change behavior expectations against the new code before cleanup.

Expected: Any missing provider branch or broken selector is identified.

• Step 3: Write minimal implementation

Clean up labels, update README usage instructions, and ensure all branches show accurate UI copy.

• Step 4: Run test to verify it passes

Reload the extension and perform:

• provider switch smoke test

• account add/delete smoke test

• one OAuth authorization smoke test

• one mail access smoke test

• Step 5: Commit

git add README.md
git commit -m "docs: document hotmail oauth mail provider"