feat: 删除过时的 Hotmail OAuth 相关文档
This commit is contained in:
QLHazyCoder
@@ -1,197 +0,0 @@
|
||||
# Hotmail OAuth + Graph Mail Design
|
||||
|
||||
## Goal
|
||||
|
||||
Replace the existing DuckDuckGo plus webmail polling flow with a Hotmail account pool that:
|
||||
|
||||
- authorizes each Hotmail account inside the extension via Microsoft OAuth
|
||||
- stores per-account tokens locally
|
||||
- selects a fresh account for each automated run
|
||||
- fetches verification emails through Microsoft Graph instead of mailbox page DOM polling
|
||||
|
||||
The existing 1~9 step flow should remain intact wherever possible. The new work should be isolated to account selection, authorization, and email retrieval.
|
||||
|
||||
## Existing Constraints
|
||||
|
||||
- The project is a Manifest V3 Chrome extension with no build step.
|
||||
- Runtime orchestration lives in `background.js`.
|
||||
- The side panel is plain HTML/CSS/JS.
|
||||
- Step 4 and Step 7 currently depend on provider-specific content scripts for QQ, 163, and Inbucket mailbox polling.
|
||||
- Auto mode already supports retries, pauses, and restoring session state.
|
||||
|
||||
## Design Summary
|
||||
|
||||
The new Hotmail path introduces three focused subsystems:
|
||||
|
||||
1. `hotmail-account-pool`
|
||||
Maintains a reusable list of Hotmail accounts and their OAuth credentials.
|
||||
2. `microsoft-oauth`
|
||||
Handles Microsoft authorization code flow with PKCE through `chrome.identity.launchWebAuthFlow`.
|
||||
3. `hotmail-graph-mail`
|
||||
Reads inbox messages from Microsoft Graph and extracts verification codes for Step 4 and Step 7.
|
||||
|
||||
The main flow continues to use the existing step state machine in `background.js`.
|
||||
|
||||
## Architecture
|
||||
|
||||
### 1. Account Pool
|
||||
|
||||
Persist a new `hotmailAccounts` array in `chrome.storage.local`.
|
||||
|
||||
Each account record stores:
|
||||
|
||||
- `id`
|
||||
- `email`
|
||||
- `password`
|
||||
- `clientId`
|
||||
- `accessToken`
|
||||
- `refreshToken`
|
||||
- `expiresAt`
|
||||
- `status`
|
||||
- `lastUsedAt`
|
||||
- `lastAuthAt`
|
||||
- `lastError`
|
||||
|
||||
The current run stores `currentHotmailAccountId` in `chrome.storage.session`.
|
||||
|
||||
When `mailProvider = hotmail-api`, Auto mode must allocate one account at the start of a fresh run, write its email into the existing `email` runtime field, and reuse the same account through Step 3, Step 4, Step 6, and Step 7.
|
||||
|
||||
### 2. OAuth Flow
|
||||
|
||||
Each account is authorized separately from the side panel.
|
||||
|
||||
Flow:
|
||||
|
||||
1. User clicks `Authorize` on an account row.
|
||||
2. Background generates PKCE verifier/challenge and a random `state`.
|
||||
3. Background launches Microsoft sign-in via `chrome.identity.launchWebAuthFlow`.
|
||||
4. Microsoft redirects back to the extension redirect URL.
|
||||
5. Background validates `state`, exchanges `code` for tokens, and updates the account record.
|
||||
|
||||
The extension requests delegated scopes only:
|
||||
|
||||
- `openid`
|
||||
- `profile`
|
||||
- `offline_access`
|
||||
- `https://graph.microsoft.com/Mail.Read`
|
||||
- `https://graph.microsoft.com/User.Read`
|
||||
|
||||
The design assumes one shared `clientId` across accounts is valid, while `refreshToken` remains per account.
|
||||
|
||||
### 3. Graph Mail Retrieval
|
||||
|
||||
Hotmail mail retrieval runs inside background logic and does not require a mail tab or content script.
|
||||
|
||||
The provider performs:
|
||||
|
||||
1. Resolve the current Hotmail account from session state.
|
||||
2. Refresh the token if missing or near expiry.
|
||||
3. Call Microsoft Graph to fetch recent inbox messages.
|
||||
4. Filter by sender, subject, and time window.
|
||||
5. Extract a 6-digit verification code from message metadata or preview/body.
|
||||
6. Return the code to the existing Step 4 or Step 7 submission flow.
|
||||
|
||||
The first iteration should prefer stable fields such as:
|
||||
|
||||
- `from.emailAddress.address`
|
||||
- `subject`
|
||||
- `receivedDateTime`
|
||||
- `bodyPreview`
|
||||
|
||||
Full HTML body parsing is explicitly deferred unless needed.
|
||||
|
||||
## Integration with Existing Steps
|
||||
|
||||
### Step 3
|
||||
|
||||
Step 3 keeps filling the OpenAI page in the same way, but when `mailProvider = hotmail-api`, the email comes from the selected account pool entry instead of the manual email box or Duck address.
|
||||
|
||||
### Step 4 and Step 7
|
||||
|
||||
The existing retry and resend behavior stays in place, but the provider path changes:
|
||||
|
||||
- old providers: `qq`, `163`, `inbucket`
|
||||
- new provider: `hotmail-api`
|
||||
|
||||
The orchestration layer should branch before opening any mailbox tab. For `hotmail-api`, it calls a background helper instead of `sendToMailContentScriptResilient`.
|
||||
|
||||
### Auto Run
|
||||
|
||||
Auto run changes:
|
||||
|
||||
- remove the Duck auto-fetch dependency when `hotmail-api` is selected
|
||||
- allocate a fresh Hotmail account at the start of a new run
|
||||
- fail early if no authorized account is available
|
||||
- preserve the existing retry and skip-failure semantics
|
||||
|
||||
## Side Panel Changes
|
||||
|
||||
The current single email entry remains for backward compatibility, but a new account-pool section is added when `hotmail-api` is selected.
|
||||
|
||||
New UI capabilities:
|
||||
|
||||
- list Hotmail accounts
|
||||
- add an account
|
||||
- delete an account
|
||||
- authorize an account
|
||||
- test mail access for an account
|
||||
- show status and last error
|
||||
|
||||
The existing provider selector gains a `hotmail-api` option.
|
||||
|
||||
## Error Handling
|
||||
|
||||
The new path must surface actionable errors:
|
||||
|
||||
- no Hotmail account available
|
||||
- missing `clientId`
|
||||
- OAuth denied or cancelled
|
||||
- token exchange failed
|
||||
- refresh token invalid
|
||||
- Graph mail read failed
|
||||
- no matching verification mail found in the time window
|
||||
|
||||
Account-level failures should update the account record `status` and `lastError` without corrupting unrelated accounts.
|
||||
|
||||
## Security and Storage Tradeoffs
|
||||
|
||||
- Tokens and account passwords are stored in `chrome.storage.local` for operator convenience.
|
||||
- This is acceptable for the current operator-managed extension model, but it increases the trust requirement of the local browser profile.
|
||||
- No secret should be hard-coded in the repository.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
Because the project has no automated test harness today, implementation should carve out pure helper functions where possible and validate them with focused runtime checks.
|
||||
|
||||
The minimum verification surface:
|
||||
|
||||
- account selection logic
|
||||
- PKCE helper generation
|
||||
- OAuth callback parsing and state validation
|
||||
- token refresh request/response handling
|
||||
- Graph message filtering and code extraction
|
||||
- Step 4 and Step 7 provider branch behavior
|
||||
- Auto run allocation of a fresh account per run
|
||||
|
||||
## Deferred Work
|
||||
|
||||
The first version intentionally excludes:
|
||||
|
||||
- bulk import/export UX
|
||||
- bulk authorize all accounts
|
||||
- advanced HTML message parsing
|
||||
- mailbox delete/move/archive behavior
|
||||
- background local service or server proxy
|
||||
- removal of existing QQ/163/Inbucket support
|
||||
|
||||
## Implementation Boundary
|
||||
|
||||
Modify only the minimum set of files needed to add the new provider while keeping current providers operational:
|
||||
|
||||
- `manifest.json`
|
||||
- `background.js`
|
||||
- `sidepanel/sidepanel.html`
|
||||
- `sidepanel/sidepanel.css`
|
||||
- `sidepanel/sidepanel.js`
|
||||
|
||||
If helper extraction becomes necessary, prefer adding small new files under `content/` or the repo root only if they clearly reduce complexity in `background.js`.
|
||||
Reference in New Issue
Block a user