| **Alipay (Direct)** | Desktop QR code, mobile Alipay redirect | Direct integration with Alipay Open Platform, returning desktop QR codes and mobile WAP/app launch links |
| **WeChat Pay (Direct)** | Native QR, H5, MP/JSAPI Pay | Direct integration with WeChat Pay APIv3 with environment-aware routing |
| **Stripe** | Card, Alipay, WeChat Pay, Link, etc. | International payments, multi-currency support |
> Alipay/WeChat Pay direct and EasyPay can both exist as backend provider instances, but the frontend always exposes only two visible buttons: `Alipay` and `WeChat Pay`. Admins choose exactly one source for each visible method: direct or EasyPay. Direct channels connect to payment APIs directly with lower fees; EasyPay aggregates through third-party platforms with easier setup.
> **EasyPay Provider Recommendations**: Both options below are third-party aggregators compatible with the EasyPay protocol. Pick based on the funding channel and settlement currency you need:
>
> - **Domestic channel / CNY settlement** — [ZPay](https://z-pay.cn/?uid=23808) (`https://z-pay.cn/?uid=23808`): direct integration with official Alipay / WeChat Pay APIs, fee **1.6%**; funds go straight to the merchant account with **T+1 automatic settlement**. Supports **individual users** (no business license required) with up to 10,000 CNY daily transactions; business-licensed accounts have no limit. Link contains the referral code of [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) original author [@touwaeriol](https://github.com/touwaeriol) — feel free to remove it.
> - **International channel / USDT or USD settlement** — [Kyren Topup](https://kyren.top/?code=SUB2API) (`https://kyren.top/?code=SUB2API`): a ready-to-launch global payment stack for AI startups with WeChat Pay and Alipay support, local-currency checkout, and USD settlement. Fees: WeChat 2%, Alipay 2.5%; withdrawal 0.1% (min $40, max $150), settled in **USDT or USD**. No qualification review required — sign up and use immediately, making it the lowest barrier to entry. Withdrawal threshold is relatively high, recommended for users **who do not use domestic Chinese payment channels, cannot tolerate Stripe's 6%+ fees, have high transaction volume, and have USD or USDT channels to receive withdrawn funds**. Kyren Topup charges a $200 account opening fee; signing up via this link (which contains Sub2Api author [@Wei-Shaw](https://github.com/Wei-Shaw)'s referral code) **waives the opening fee**. Feel free to remove it if you prefer.
>
> Please evaluate the security, reliability, and compliance of any third-party payment provider on your own — this project does not endorse or guarantee any of them.
---
## Quick Start
1. Go to Admin Dashboard → **Settings** → **Payment Settings** tab
| **Order Timeout** | Order timeout in minutes (minimum 1) | 30 |
| **Max Pending Orders** | Maximum concurrent pending orders per user | 3 |
| **Load Balance Strategy** | Strategy for selecting provider instances | Round Robin |
### Frontend Visible Method Routing
The current payment UX keeps the frontend method list unified and does not expose provider brands directly:
-**Alipay**: when enabled, this button must be routed to either `Alipay (Direct)` or `EasyPay Alipay`
-**WeChat Pay**: when enabled, this button must be routed to either `WeChat Pay (Direct)` or `EasyPay WeChat`
- Each visible method can route to only one source at a time
- If a visible method is enabled without a selected source, the frontend will not expose that method
### Load Balance Strategies
| Strategy | Description |
|----------|-------------|
| **Round Robin** | Distribute orders to instances in rotation |
| **Least Amount** | Prefer instances with the lowest daily cumulative amount |
### Cancel Rate Limiting
Prevents users from repeatedly creating and canceling orders:
| Setting | Description |
|---------|-------------|
| **Enable Limit** | Toggle |
| **Window Mode** | Sliding / Fixed window |
| **Time Window** | Window duration |
| **Window Unit** | Minutes / Hours |
| **Max Cancels** | Maximum cancellations allowed within the window |
### Help Information
| Setting | Description |
|---------|-------------|
| **Help Image** | Customer service QR code or help image (supports upload) |
| **Help Text** | Instructions displayed on the payment page |
---
## Provider Configuration
Each provider type requires different credentials. Select the type when adding a new provider instance in **Provider Management → Add Provider**.
> **Callback URLs are auto-generated**: When adding a provider, the Notify URL and Return URL are automatically constructed from your site domain. You only need to confirm the domain is correct.
### EasyPay
Compatible with any payment service that implements the EasyPay protocol.
| Parameter | Description | Required |
|-----------|-------------|----------|
| **Merchant ID (PID)** | EasyPay merchant ID | Yes |
Direct integration with Alipay Open Platform. Desktop flows return a QR code for in-page display, while mobile flows return an Alipay WAP/app redirect URL.
> Replace `your-domain.com` with your actual domain. For EasyPay / Alipay / WeChat Pay, the callback URL is auto-filled when adding the provider — no manual configuration needed.
### Stripe Webhook Setup
1. Log in to [Stripe Dashboard](https://dashboard.stripe.com/)
2. Go to **Developers → Webhooks**
3. Add an endpoint with the callback URL
4. Subscribe to events: `payment_intent.succeeded`, `payment_intent.payment_failed`
5. Copy the generated Webhook Secret (`whsec_...`) to your provider configuration
### Important Notes
- Callback URLs must use **HTTPS** (required by Stripe, strongly recommended for others)
- Ensure your firewall allows callback requests from payment platforms
- The system automatically verifies callback signatures to prevent forgery
- Balance top-up is processed automatically upon successful payment — no manual intervention needed
---
## Payment Flow
```
User selects amount and payment method
│
▼
Create Order (PENDING)
├─ Validate amount range, pending order count, daily limit
| `FAILED` | Balance credit failed, admin can retry |
| `REFUND_REQUESTED` | Refund requested |
| `REFUNDING` | Refund in progress |
| `REFUNDED` | Refund completed |
### Timeout and Fallback
- Before marking an order as expired, the background job queries the upstream payment status first
- If the user has actually paid but the callback was delayed, the system will reconcile automatically
- The background job runs every 60 seconds to check for timed-out orders
---
## Migrating from Sub2ApiPay
If you previously used [Sub2ApiPay](https://github.com/touwaeriol/sub2apipay) as an external payment system, you can migrate to the built-in payment system:
### Key Differences
| Aspect | Sub2ApiPay | Built-in Payment |
|--------|-----------|-----------------|
| Deployment | Separate service (Next.js + PostgreSQL) | Built into Sub2API, no extra deployment |
| Configuration | Environment variables + separate admin UI | Unified in Sub2API admin dashboard |
| Top-up Integration | Via Admin API callback | Internal processing, more reliable |
| Subscription Plans | Supported | Not yet (planned) |
| Order Management | Separate admin interface | Integrated in Sub2API admin dashboard |
### Migration Steps
1. Enable payment in Sub2API admin dashboard and configure providers (use the same payment credentials)
2. Update webhook callback URLs to Sub2API's callback endpoints
3. Verify that new orders are processed correctly via built-in payment
4. Decommission the Sub2ApiPay service
> **Note**: Historical order data from Sub2ApiPay will not be automatically migrated. Keep Sub2ApiPay running for a while to access historical records.
# Auth Identity Payment Foundation 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:** Rebuild the auth identity, profile binding, payment routing, and OpenAI advanced scheduler foundation on top of a clean `origin/main` branch while preserving historical compatibility for existing email users, existing LinuxDo users, historical LinuxDo/WeChat/OIDC synthetic-email users, and historical WeChat `openid`-only records.
**Architecture:** A unified identity foundation centered on durable provider subjects (`email`, `linuxdo`, `oidc`, `wechat`) and transactional pending-auth sessions; backend-owned payment source routing behind stable frontend methods (`alipay`, `wxpay`); compatibility-first migration/backfill before feature enablement.
- [ ] Preserve login continuity for existing email users, existing LinuxDo users, and historically migrated third-party users.
- [ ] During migration, backfill historical LinuxDo/WeChat/OIDC synthetic-email users into explicit third-party identities before first post-upgrade login whenever deterministic recovery is possible.
- [ ] During migration, surface historical WeChat `openid`-only records through explicit migration reports and remediation rules; do not silently reinterpret them as valid canonical identities.
- [ ] Keep existing email login and add third-party login/bind for `linuxdo`, `oidc`, and `wechat`.
- [ ] On first third-party login:
- identity exists: direct login.
- identity does not exist: start pending-auth flow.
- local email binding is required only when system config says so.
- upstream provider email verification never counts as local email verification.
- [ ] When user-entered and locally verified email already exists:
- offer bind-existing-account after local re-authentication.
- offer change-email-and-create-new-account.
- when email binding is mandatory, do not allow bypass without changing to another email.
- [ ] On first third-party login or first third-party bind, provider nickname/avatar must be presented as independent replace options for the current nickname and avatar. They are not auto-applied.
- [ ] Source-specific initial grants must support per-source defaults for balance, concurrency, and subscriptions.
- [ ] Default grant timing: on successful new-account creation.
- [ ] Optional grant timing: on first successful bind for the configured source.
- [ ] Migration/backfill must never trigger first-bind or first-signup grants retroactively.
- [ ] Avatar profile supports:
- direct URL storage.
- image data URL upload compressed to `<=100KB` before storing in DB.
- explicit delete.
- [ ] Admin user management must expose and sort by `last_login_at` and `last_active_at`.
- [ ] WeChat login rules:
- WeChat environment uses MP login.
- non-WeChat browser uses Open/QR login.
- canonical identity uses `unionid`.
- when `unionid` is unavailable, fail the login/bind flow under the approved option-1 policy.
- discovery issuer and ID token `iss` must match exactly.
-`userinfo.sub` must match ID token `sub` when UserInfo is used.
- upstream `email_verified` does not satisfy local email verification.
- [ ] Payment UI rules:
- user-facing methods stay `支付宝` and `微信支付`.
- backend decides whether each method routes to official provider instance or EasyPay.
- at runtime, each visible method may only have one active source.
- [ ] Alipay rules:
- PC: in-page QR.
- mobile browser: jump to Alipay payment.
- [ ] WeChat Pay rules:
- PC: in-page QR.
- WeChat H5: MP/JSAPI first, fallback to H5 pay.
- non-WeChat H5: H5 pay, or prompt to open in WeChat when unavailable.
- [ ] Payment success pages are informational only; actual fulfillment depends on webhook or server-side reconciliation.
- [ ] WeChat in-app payment requiring `openid` must use a dedicated server-backed payment OAuth resume flow rather than frontend-only recovery state.
- [ ] OpenAI advanced scheduler is available but default-disabled.
## Hard Technical Constraints From Audit
- [ ] Browser-based third-party auth must use Authorization Code + PKCE `S256`.
- [ ] PKCE must not be admin-configurable off for browser authorization-code providers.
- [ ] OIDC identity primary key must be `(issuer, subject)`, not email.
- [ ] Email equality must never auto-link accounts.
- [ ] Bind-existing-account must require explicit local re-authentication and TOTP verification when enabled.
- [ ] Bind-current-user must originate from an already-authenticated local user and preserve explicit bind intent across callback completion.
- [ ] OAuth redirect URI must be fixed server config, exact-match, and never derived from user input.
- [ ] User-supplied redirect may only choose a normalized same-origin internal route after completion.
- [ ] WeChat canonical identity must be `unionid`; `openid` remains channel/app-scoped support data only.
- [ ] Every canonical identity uniqueness rule must include provider namespace (`provider_key`) consistently.
- [ ] Callback completion must use backend session completion or a one-time opaque exchange code that is short-lived, one-time, browser-session-bound, `POST`-redeemed, and unusable as a bearer token.
- [ ] Every payment order must snapshot the selected provider instance plus the order-time verification inputs required for callback verification, reconciliation, refund, and audit.
- [ ] Frontend must not receive first-party bearer tokens through callback URL fragments in the rebuilt flow.
- [ ] Public payment result polling must not expose order data by raw `out_trade_no` alone; use authenticated lookup or signed opaque result token.
- [ ] WeChat Pay webhook handling must verify signature, decrypt payload, and compare `appid`, `mchid`, `out_trade_no`, `amount`, `currency`, and provider trade state against the order snapshot before fulfillment.
## Baseline Notes
- [ ] Current clean branch head when this plan was written: `721d7ab3`.
- [ ] Baseline backend verification on clean `origin/main`: `cd backend && go test ./...` passes.
- [ ] Baseline frontend verification on clean `origin/main`: `cd frontend && pnpm test:run` currently fails in unrelated existing suites. New work must add targeted tests and avoid claiming full frontend green until those baseline failures are addressed separately.
- [ ] Existing migration directory currently ends at `107_*`; this rebuild reserves `108` through `111`.
- grant-tracking columns/tables required to prevent double-award
- [ ] Add uniqueness/index rules:
- one canonical identity per `(provider, provider_key, provider_subject)`
- one channel record per `(provider, provider_channel, provider_app_id, provider_channel_subject)`
- one adoption decision per pending session
- [ ] Model `pending_auth_sessions` so immutable upstream claims and mutable local flow state are stored separately; do not reintroduce a mixed `metadata` catch-all.
- [ ] Preserve null-safe compatibility defaults so historical rows remain readable before backfill finishes.
- [ ] Add explicit rollback blocks only where safe; never repeat the destructive pattern observed in old `112_update_pending_auth_sessions.sql`.
### Task 2. Materialize historical identities before runtime
- [ ] Implement `backend/migrations/109_auth_identity_compat_backfill.sql` to backfill:
- existing email users into `auth_identities(provider=email, provider_subject=normalized_email)`
- historical LinuxDo users into `auth_identities(provider=linuxdo, provider_subject=linuxdo_subject)`
- historical synthetic-email LinuxDo users into explicit LinuxDo identity rows by parsing legacy email mode and legacy provider metadata
- historical synthetic-email WeChat users into explicit WeChat identities where `unionid` or equivalent deterministic provider identity is recoverable
- historical synthetic-email OIDC users into explicit OIDC identities where deterministic provider identity is recoverable
- profile/channel rows from historical `user_external_identities`-style data when present in upgraded databases
- [ ] Write migration report output in `backend/internal/repository/auth_identity_migration_report.go` so production can inspect unmatched rows, `openid`-only WeChat rows, and non-deterministic synthetic-email rows instead of silently skipping them.
- [ ] Set `signup_source` and provider provenance when recoverable from historical data. Do not flatten everything to `email`.
### Task 3. Provider default grant and scheduler config migration
git commit -m"feat: add auth identity foundation schema"
```
## Phase 2: Backend Identity Flow Rebuild
### Task 5. Build a single repository contract for identity lookups and grants
- [ ] Implement `backend/internal/repository/user_profile_identity_repo.go` with transactional helpers for:
- get user by canonical identity
- get user by channel identity
- create canonical + channel identity together
- bind identity to existing user after verified re-auth
- record one-time provider grant award
- record adoption preference decisions
- update `last_login_at` and `last_active_at`
- [ ] Add repository contract coverage in `backend/internal/repository/user_profile_identity_repo_contract_test.go`.
- [ ] Enforce dual-write for email registration/login so `users.email` and `auth_identities(provider=email, ...)` stay consistent from this phase onward.
- [ ] Add repository coverage proving `last_login_at` and `last_active_at` use the required field names and are not silently replaced by derived `last_used_at` logic.
### Task 6. Rebuild transactional pending-auth service
- [ ] Implement `backend/internal/service/auth_pending_identity_service.go` and tests to own these flows:
- create pending session from third-party callback
- verify local email code
- create new account from pending session with correct `signup_source`
- bind pending identity to existing account after password/TOTP re-auth
- apply configured provider defaults on the correct trigger only once
- store provider nickname/avatar candidates and user opt-in replacement decisions independently
- [ ] Implement callback completion so pending auth can finish through backend session completion or a one-time exchange code:
- short TTL
- one-time use
- browser-session binding
-`POST` redemption only
- safe mixed-version bridge to legacy pending-token aliases during rollout
- [ ] Keep pending session payload normalized:
- provider identity fields live in typed columns/JSON structure
- mutable local progression lives separately from immutable upstream claims
- avoid the old branch’s mixed `metadata` and `upstream_identity_payload` ambiguity
- [ ] Do not call plain email registration helpers from this flow. The old feature branch bug where pending third-party signup fell back to `RegisterWithVerification` must not reappear.
### Task 7. Rebuild provider callback adapters
- [ ] Refactor these handlers to thin adapters over the shared pending-auth service:
- verify `userinfo.sub == id_token.sub` when UserInfo is used
- persist canonical identity as `(issuer, sub)`
- [ ] For WeChat:
- MP flow in WeChat UA
- Open/QR flow outside WeChat UA
- website login uses authorization-code flow and persists channel/app binding
- persist channel identity by `(channel, appid, openid)`
- persist canonical identity by `unionid`
- hard-fail when `unionid` is absent under the approved product policy
- [ ] Replace callback URL fragment token delivery with backend session completion or one-time exchange code consumed by `frontend/src/stores/auth.ts`.
### Task 8. Rebuild auth endpoints and profile binding endpoints
- [ ] Rebuild `backend/internal/service/payment_config_service.go` to expose a stable method-routing contract:
- frontend visible methods remain `alipay` and `wxpay`
- admin chooses which provider instance serves each method
- runtime validation guarantees only one active source per visible method
- [ ] Add migration logic and tests to normalize historical provider-instance config:
-`supported_types`
-`payment_mode`
- legacy aliases such as `wxpay_direct`
- historical limit config
- [ ] Rebuild `backend/internal/service/payment_order.go` and `backend/internal/service/payment_order_lifecycle.go` so order creation snapshots:
- visible method
- selected provider instance id
- provider type
- provider capability mode
- verification-critical provider fields needed for later callback/query/refund validation
- [ ] Rebuild `backend/internal/handler/payment_handler.go` for UX rules:
- Alipay PC: QR page
- Alipay mobile: direct jump
- WeChat PC: QR page
- WeChat H5 in WeChat: MP/JSAPI first, fallback to H5
- WeChat H5 outside WeChat: H5 or “open in WeChat” prompt when unavailable
- [ ] Never derive canonical return URL from `Referer`; use configured or signed internal callback targets only.
- [ ] Implement `backend/internal/service/payment_resume_service.go` so WeChat in-app payment OAuth resume is server-backed rather than localStorage-backed:
- comparison of `appid`, `mchid`, `out_trade_no`, `amount`, `currency`, and trade state against the order snapshot
- [ ] Harden `frontend/src/views/user/PaymentResultView.vue` and `frontend/src/api/payment.ts` so result polling uses an authenticated order lookup or signed opaque token, not a raw public `out_trade_no` query.
### Task 16. Rebuild payment frontend views
- [ ] Rebuild `frontend/src/views/user/PaymentView.vue`, `frontend/src/views/user/PaymentQRCodeView.vue`, and `frontend/src/stores/payment.ts` so:
- only two buttons are shown to user: `支付宝` and `微信支付`
- frontend does not leak official-vs-EasyPay distinction
**Status:** Draft approved in conversation, written for implementation planning
**Goal**
Rebuild the `feat/auth-identity-foundation` intent on a clean branch from `main`, covering unified user identity, third-party login and binding, profile adoption, source-based signup defaults, unified payment routing and UX, admin configuration, compatibility with existing `main` data, and an opt-in OpenAI advanced scheduling switch.
## Scope
This design includes:
- Email login and registration
- Third-party login and binding for `LinuxDo`, `OIDC`, and `WeChat`
- Unified identity storage for email and third-party identities
- Pending auth sessions for callback-to-login/register/bind continuation
- User-controlled nickname/avatar adoption during first relevant third-party flow
- Profile binding management and avatar upload/delete
- Source-based initial grants for balance, concurrency, and subscriptions
- User management support for `last_login_at` and `last_active_at` sorting
- Unified payment display methods (`alipay`, `wxpay`) mapped to a single active backend source each
- Alipay and WeChat UX routing rules across PC, mobile, H5, and WeChat environments
- Admin settings for auth providers, source defaults, payment sources, and OpenAI advanced scheduling
- Incremental migration and compatibility for existing email users, existing LinuxDo users, historical LinuxDo/WeChat/OIDC synthetic-email users, and historical WeChat `openid`-only identity records
This design does not treat unrelated upstream merges, docs churn, or license changes from the old branch as required scope.
## Product Rules
### Auth and identity
- Existing email users remain valid and continue to log in with no manual action.
- Existing LinuxDo, OIDC, and WeChat users represented by historical third-party or synthetic-email data must remain recoverable during migration.
- Third-party first login behavior:
- Existing bound identity: direct login
- Missing identity: start first-login flow
- Browser-based third-party authorization-code login always uses PKCE `S256`; this is not an admin-toggleable feature.
- If `force_email_on_third_party_signup` is disabled, a first-login user may create an account without binding an email.
- If `force_email_on_third_party_signup` is enabled, the user must provide an email.
- If the provided and verified email already exists:
- show that the email already exists
- allow "verify and bind existing account"
- allow "change email and continue registration"
- do not allow bypassing the email requirement
- Upstream provider email verification is not trusted as a local bound email.
- Matching upstream email must never auto-link to an existing local account.
- Linking to an existing local account is allowed only when:
- the user explicitly chooses that target account
- the target account passes fresh local re-authentication
- required TOTP verification succeeds
- New third-party bind initiated from profile must start from an already logged-in local account and preserve explicit bind intent end-to-end.
-`redirect_to` may only represent a normalized same-origin internal route. It must never contain a third-party URL and must never be derived from `Referer`.
- OIDC validation rules:
- canonical identity key is `issuer + sub`
- discovery issuer and ID token `iss` must match exactly
-`userinfo.sub` must match ID token `sub` when UserInfo is used
- upstream `email_verified` may improve UX copy but does not satisfy local email-binding requirements
- WeChat login chooses channel by environment:
- in WeChat environment: `mp`
- outside WeChat: `open`
- WeChat primary identity key is `unionid`.
- If a WeChat login/bind flow cannot produce `unionid`, the flow fails and no fallback `openid` identity is created.
- Historical WeChat records that only contain `openid` are treated as migration-remediation cases, not as a valid long-term canonical identity model.
- WeChat website login uses authorization code flow, random `state`, and the provider channel/app binding must be persisted alongside the resolved identity.
### Profile adoption
- During the first relevant third-party flow, the user can independently decide:
- replace current nickname or not
- replace current avatar or not
- This applies to first third-party registration and first third-party binding.
- The decision is explicit user choice, not automatic replacement.
### Source-based initial grants
- Source-specific defaults exist for `email`, `linuxdo`, `oidc`, and `wechat`.
- Each source defines:
- default balance
- default concurrency
- default subscriptions
- grant on signup
- grant on first bind
- Default behavior:
- grant on signup: enabled
- grant on first bind: disabled
- First-bind grants are optional and controlled per source.
- Grants must be idempotent.
### Avatar management
- Avatar supports:
- external URL
- image `data:` URL
-`data:` URL images are compressed to at most `100KB` before persistence.
- Avatar storage is database-backed.
- Avatar delete is supported.
### Payment UX and routing
- Frontend shows only two display methods:
-`alipay`
-`wxpay`
- Users never choose between official providers and EasyPay explicitly.
- Backend allows only one active source per display method at a time.
- Alipay UX:
- PC: show QR code in page
- mobile: jump to Alipay app/payment flow
- WeChat UX:
- PC: show QR code in page
- non-WeChat H5: prefer H5 pay; if unavailable, tell the user to open in WeChat
- WeChat environment: prefer MP/JSAPI pay; if unavailable, fall back to H5 pay
- Payment success is confirmed by backend order state, webhook, and/or query, not only frontend return.
- Frontend-visible labels remain `支付宝` and `微信支付`, while internal visible-method identifiers remain `alipay` and `wxpay`.
- Public result pages must not verify order state by exposing raw `out_trade_no`; they use authenticated lookup or a signed opaque result token instead.
- Payment callback or return URLs must be fixed same-origin internal targets. They must not be inferred from `Referer`.
- WeChat payment webhook handling must use a fixed HTTPS `notify_url` with no query parameters and must not depend on user login state.
### OpenAI advanced scheduling
- OpenAI advanced scheduling is supported.
- It is disabled by default.
- Admin can enable it explicitly.
## Architecture
Keep `users` as the account owner table and move login identities, channel mappings, pending auth state, callback completion state, and first-bind grant idempotency into dedicated tables and services. Keep email login working while progressively introducing unified identity reads and writes.
Payment uses a similar split between user-visible display methods and backend provider sources. Frontend works only with stable display methods while backend resolves to the currently active source and capability matrix, and stores enough order-time snapshot data to survive later provider-config changes.
Compatibility is a first-class concern: migrations are additive, reads are compatibility-aware, and rollout must tolerate existing `main` data and short-lived frontend/backend version skew.
## Data Model
### `users`
Preserve existing account ownership and local-login fields. Extend or use:
-`email`
-`password_hash`
-`totp_enabled`
-`signup_source`
-`last_login_at`
-`last_active_at`
The `users` table remains the primary business subject for balance, concurrency, subscriptions, permissions, and profile.
### `auth_identities`
Represents all canonical login or bindable identities.
-`provider_type + provider_key + provider_subject` must be unique
Rules:
- email identity uses canonicalized local email
- LinuxDo uses stable provider subject under the configured provider namespace
- OIDC uses stable issuer + subject, with issuer namespace represented consistently through `provider_key` and `issuer`
- WeChat uses `unionid` as canonical subject under the configured Open Platform namespace
### `auth_identity_channels`
Stores channel-specific subject mappings for an identity.
Primary use:
- WeChat `open` / `mp` / payment channel mapping
Fields:
-`identity_id`
-`provider_type`
-`provider_key`
-`channel`
-`channel_app_id`
-`channel_subject`
-`metadata`
- timestamps
Rules:
- canonical WeChat identity still keys on `unionid`
-`openid` values live here as channel mappings
### `pending_auth_sessions`
Stores callback state between third-party callback and final account action.
Fields:
-`intent`
-`provider_type`
-`provider_key`
-`provider_subject`
-`target_user_id`
-`redirect_to`
-`resolved_email`
-`registration_password_hash`
-`upstream_identity_claims`
-`local_flow_state`
-`browser_session_key`
-`completion_code_hash`
-`completion_code_expires_at`
-`email_verified_at`
-`password_verified_at`
-`totp_verified_at`
-`expires_at`
-`consumed_at`
- timestamps
Responsibilities:
- continue provider callback into register/login/bind flows
- persist nickname/avatar suggestions
- persist explicit adoption decisions
- survive navigation between auth pages
- support mixed-version rollout through short-lived legacy token aliases when required
Security rules:
- callback completion uses backend session completion or a one-time exchange code
- exchange codes are short-lived, one-time, bound to browser session and pending session, and redeemed via `POST`
- exchange codes must not behave as bearer tokens and must not be logged, stored in URL fragments, or reused after redemption
-`local_flow_state` stores mutable local progression only; immutable upstream claims remain in `upstream_identity_claims`
### `identity_adoption_decisions`
Persists user adoption preference collected during a pending-auth flow and resolved onto the bound identity.
Fields:
-`pending_auth_session_id`
-`identity_id`
-`adopt_display_name`
-`adopt_avatar`
-`decided_at`
- timestamps
Rules:
- one adoption-decision row exists per pending session
-`identity_id` is filled once final account creation or bind succeeds
### `user_avatars`
Stores the currently effective custom avatar.
Fields:
-`user_id`
-`storage_provider`
-`storage_key`
-`url`
-`content_type`
-`byte_size`
-`sha256`
- timestamps
Rules:
- supports URL-backed and inline data-backed representations
- hard maximum payload size is `100KB`
### `user_provider_default_grants`
Stores idempotency state for source grants.
Fields:
-`user_id`
-`provider_type`
-`granted_at`
- timestamps
Responsibilities:
- prevent duplicate first-bind grants
- allow signup grants and first-bind grants to be reasoned about independently
## Identity Keys And Canonicalization
- Email canonical key: `lower(trim(email))`
- LinuxDo canonical key: provider subject from LinuxDo
- OIDC canonical key: `issuer + sub`
- WeChat canonical key: `unionid`
WeChat-specific rule:
-`openid` never becomes the primary stored identity key
- if only `openid` is available, login/bind fails with a configuration/identity error
- historical `openid`-only records must be reported and either remediated during migration or explicitly blocked from silent auto-upgrade
## Core Flows
### Email register/login
- Existing email auth flow remains
- On email registration, create canonical `email` identity
- Apply `email` source signup defaults
### Third-party login with existing identity
- Resolve canonical identity
- Login mapped `user`
- Update `last_login_at`
- Do not issue signup or first-bind grants again
### Third-party first login with no identity
- Create `pending_auth_session`
- Frontend callback flow decides next action
- Pending session creation stores immutable upstream claims separately from mutable local progress fields
Branches:
- no forced email binding:
- user can create account directly
- forced email binding:
- user must supply local email
If supplied local email already exists:
- tell the user the email already exists
- allow verify-and-bind-existing-account
- allow changing email to continue registration
On new account creation:
- create `users` row
- create canonical third-party identity
- create or update canonical email identity when local email binding succeeds
- apply source signup grants
- apply adoption choices if selected
### Bind third-party identity to current logged-in user
- current user starts bind flow
- callback resolves to `bind_current_user`
- bind intent is tied to the initiating local user session and cannot be re-targeted by email match
- bind canonical identity to current user
- if configured and first bind for that provider, apply first-bind grants
- present nickname/avatar replacement choice
### Bind existing account during first-login flow
- user explicitly selects bind-existing-account
- verify password for existing account
- if account requires TOTP, verify TOTP
- bind canonical identity to target account
- optionally apply first-bind grants
- present nickname/avatar replacement choice
- no automatic profile or metadata merge occurs beyond explicitly selected nickname/avatar replacement
### Callback completion and exchange flow
- third-party callback never returns first-party bearer tokens in URL fragments
- callback completion uses either:
- backend session completion tied to the initiating browser session
- one-time opaque exchange code redeemed by `POST`
- mixed-version rollout may temporarily emit legacy pending token aliases in addition to the new completion path
- legacy alias support is transitional and bounded to rollout windows only
### WeChat login and channel mapping
- environment chooses `mp` or `open`
- website login uses authorization-code flow with provider-configured app/channel binding
- callback must resolve to `unionid`
- channel `openid` is optionally recorded in `auth_identity_channels`
- failure to obtain `unionid` aborts flow
### Avatar upload and delete
- URL avatar: validate and persist reference
- data URL avatar:
- decode
- validate image type
- compress to `<=100KB`
- persist database-backed inline representation
- delete removes current custom avatar entry
## Payment Routing Model
### User-visible methods
-`alipay`
-`wxpay`
### Backend source abstraction
Each display method maps to exactly one active configured backend source:
-`official_alipay`
-`easypay_alipay`
-`official_wechat`
-`easypay_wechat`
Frontend submits display method only. Backend resolves display method to active source and capability set.
### Legacy payment-config normalization
- existing provider-instance `supported_types`, legacy aliases such as `wxpay_direct`, and per-type limit structures are migrated into the visible-method model
- migration preserves historical payment capability and refund semantics
- the system keeps one normalized visible-method mapping per provider instance for rollout and audit
### Alipay routing
- PC: create QR-oriented result and show QR in page
- mobile: create jump/redirect-oriented result
### WeChat routing
- PC: QR result
- non-WeChat H5:
- prefer H5 pay
- if unavailable, show "open in WeChat" requirement
- WeChat environment:
- prefer MP/JSAPI
- if unavailable, fall back to H5 pay
### WeChat payment OAuth recovery
- if WeChat in-app payment requires `openid` and the current request does not already hold it, backend returns an `oauth_required` response instead of guessing
- backend creates a server-backed payment-resume context containing:
- target visible method
- amount/order type/plan context
- redirect target
- anti-replay state
- backend redirects through a dedicated WeChat payment OAuth start endpoint
- callback exchanges the provider code server-side, stores `openid` in the payment-resume context, and returns a same-origin internal resume target
- frontend resumes the original order flow through the resume context instead of trusting raw callback query state or long-lived local storage
### Payment completion
- frontend return restores context and UI state
- backend order state remains source of truth
- webhook and/or order query remain authoritative for fulfillment
- order fulfillment validates webhook or query payload against order-time snapshot data including provider instance, merchant identifiers, amount, currency, and provider order references
- result pages use authenticated lookup or signed opaque result tokens, never raw public `out_trade_no`
## Admin Configuration Model
### Auth provider settings
- email registration and verification settings
- force email on third-party signup
- LinuxDo client settings
- OIDC issuer/client settings and provider display name
- WeChat `open` / `mp` capability indicators derived from environment-backed configuration, surfaced to the frontend/admin read models as effective availability rather than full in-panel credential editing
### Source default settings
Per source (`email`, `linuxdo`, `oidc`, `wechat`):
- default balance
- default concurrency
- default subscriptions
- grant on signup
- grant on first bind
### Payment settings
- active source for `alipay`
- active source for `wechat`
- source-specific credentials and enablement
- effective WeChat payment capabilities may differ by enabled provider instances and selected visible-method source:
- QR available
- H5 available
- MP/JSAPI available
### Scheduling settings
- OpenAI advanced scheduling enabled/disabled
- default disabled
## Compatibility And Rollout
Compatibility is mandatory, especially for:
- existing email users
- existing LinuxDo users
- historical LinuxDo synthetic-email accounts
- historical WeChat synthetic-email accounts
- historical OIDC synthetic-email accounts
- historical WeChat `openid`-only records created by older branches
### Additive migrations
- preserve existing `users` data and behavior
- add identity and pending-session tables
- avoid destructive schema swaps
### Migration backfill
- backfill canonical `email` identities for valid existing email users
- backfill canonical `linuxdo` identities during migration for historical synthetic-email LinuxDo users
- backfill canonical `wechat` and `oidc` identities when historical synthetic-email or `user_external_identities` data allows deterministic reconstruction
- emit migration reports for historical WeChat `openid`-only records that cannot be safely promoted to canonical `unionid`
- backfill must be idempotent and repeatable
### Compatibility reads
During rollout:
- read new identity model first
- where necessary, retain compatibility logic for existing email and historical LinuxDo/WeChat/OIDC synthetic-email recognition
### Grant idempotency
- migration backfill must not trigger signup or first-bind grants
- first-bind grants must use explicit idempotency tracking
### API compatibility
Retain transitional support for legacy/new request and response shapes where needed, including:
-`pending_auth_token`
-`pending_oauth_token`
- old callback parsing expectations
- historical profile field mappings
- legacy callback fragment readers during the bounded rollout window
### Settings and payment compatibility
- preserve existing payment configs and order semantics from `main`
- add new settings incrementally
- avoid rewriting the entire settings schema in one cutover
- preserve legacy provider-instance capabilities by explicitly mapping historical `supported_types`, `payment_mode`, and limit config into normalized visible-method routing
### Rolling upgrade tolerance
- do not assume simultaneous frontend/backend deployment
- new backend must tolerate short-lived older frontend request shapes
- rollout must define the deployment order and removal point for legacy callback token parsing and legacy payment resume parsing
## Testing Strategy
### Repository tests
- identity upsert and lookup
- WeChat channel mapping
- pending auth session persistence
- source grant idempotency
- avatar persistence and delete
- migration backfill behavior
### Service tests
- direct login by existing identity
- first third-party signup
- forced email flow
- existing-email bind-existing-account flow
- first-bind grant on/off
- nickname/avatar adoption choices
- WeChat `unionid` required behavior
- payment routing resolution
### Handler and route tests
- LinuxDo/OIDC/WeChat callback handling
- bind-existing
- bind-current-user
- create-account
- TOTP continuation
- payment create and recovery
### Frontend tests
- third-party callback flow state machine
- register/login continuation
- profile bindings card
- avatar interactions
- payment page routing behavior
- admin settings UI
### Compatibility tests
- existing email users
- historical LinuxDo synthetic-email users
- historical WeChat synthetic-email users
- historical OIDC synthetic-email users
- historical WeChat `openid`-only records reported or remediated correctly
- historical payment config
- legacy auth payload field names
- historical payment result handling
- mixed-version callback token bridge behavior
## Implementation Phases
1. Add schema, migrations, compatibility backfill, and repository support
2. Implement unified identity services and pending auth session flows
3. Integrate profile binding, avatar, and adoption decision flows
4. Add per-source default grants and admin config surfaces
5. Rebuild payment routing abstraction and frontend payment UX
6. Add user-management sorting and OpenAI advanced scheduling switch
7. Run compatibility, rollout, and regression hardening
## External Constraints And Best Practices
Implementation must follow current primary-source guidance:
- PKCE (RFC 7636): require `S256` on browser authorization-code flows
- OpenID Connect Core: stable issuer/subject handling for OIDC identities
- Account linking best practice: require explicit user confirmation or re-authentication before linking to existing accounts
- WeChat UnionID and website-login guidance: treat `unionid` as canonical cross-channel subject and persist channel/app binding with website login responses
- WeChat Pay webhook guidance: verify signatures, decrypt payloads, and confirm merchant/order/amount fields against order-time state before fulfillment
- Payment success-page guidance: custom success pages are informational and must not be the only fulfillment trigger
- OpenAI advanced scheduler layering and test-backed behavior
Keep these operational flow ideas from `personal-dev-branch`:
- LinuxDo pending identity callback flow
- WeChat pending identity callback flow
- profile bindings UX and “cannot disconnect last usable login method” rule
- separate WeChat login OAuth and WeChat payment OAuth entry points
- historical synthetic-email recognition logic as a migration bridge
- explicit WeChat payment OAuth recovery protocol as a product requirement, but reimplemented with server-backed resume state
### Adapt
These areas must be reimplemented with the same intent but stricter boundaries:
- third-party account creation from pending-auth state must be transactional and must not register a plain local user before identity finalization succeeds
- email identity lifecycle must become real dual-write state, not just one migration-time backfill
-`signup_source` must be backfilled more accurately for known historical third-party users
- WeChat payment recovery state must move from frontend-only storage to server-backed continuation state
- avatar adoption fetches must be security-hardened and failure-visible
- pending-auth payload modeling must clearly separate immutable upstream payload from mutable local metadata
- callback completion must use a real exchange/session model instead of fragment-delivered bearer tokens
- profile binding/avatar DTOs must be simplified to one authoritative backend contract instead of sprawling frontend fallback parsing
- admin settings should preserve capability while reducing duplicated or transitional config branches
### Drop
Drop these as long-term design choices:
-`user_external_identities` as the primary long-term identity model
- synthetic email as a long-term canonical identity representation
- OIDC as a side-path that does not participate in the same identity foundation as LinuxDo and WeChat
- frontend multi-endpoint probing and broad compatibility parsing once the clean branch becomes the sole supported contract
- unrelated branch noise such as generated-file churn, locale-only churn, or upstream merge residue as design inputs
## Audit-Driven Hard Constraints
The audit and source review establish these hard constraints:
### Auth
- all browser authorization-code providers use PKCE `S256` and do not expose an admin-off switch
- callback handling uses strict `redirect_uri` discipline and state validation
- OIDC identity key is `issuer + sub`
- existing-account linking after email conflict must require explicit user action plus local-account verification
- WeChat canonical identity key is `unionid`; `openid` is channel-scoped only
### Compatibility
- existing email users must continue to work with no manual intervention
- existing LinuxDo users must not split into duplicate accounts
- historical LinuxDo/WeChat/OIDC synthetic-email users must be backfilled into canonical identities during migration when deterministic recovery is possible
- historical WeChat `openid`-only records must be surfaced through migration reporting and explicit remediation rules
- migration backfills must not trigger signup or first-bind grants
- legacy `pending_auth_token` and `pending_oauth_token` contracts must remain accepted during rollout
- legacy auth/public setting aliases needed by older frontend builds must remain available during rollout
- existing payment configs and historical order semantics must remain valid
### Payment
- frontend return pages do not determine final payment success
- backend order state, webhook processing, and/or provider status query remain authoritative
- each visible method (`alipay`, `wxpay`) may have only one active backend source at a time
- public result pages must not expose raw `out_trade_no` lookup
- WeChat Pay callback handling must verify signature, decrypt payload, and compare order fields against order-time snapshot data
## Known Risks To Eliminate In Implementation
These are specifically observed problems in the existing branches that the clean rebuild must eliminate:
- third-party forced-email account creation currently bypasses the provider-aware account creation path and can leave orphan local accounts if bind finalization fails
- post-migration email accounts are not fully dual-written into `auth_identities`
- avatar adoption currently risks silent failure and insecure outbound fetch behavior
- pending-auth payload responsibilities are internally inconsistent
- OIDC parity is incomplete in `personal-dev-branch`; it must become a first-class provider in the unified identity model
- WeChat union/open/channel identity handling is conceptually correct in the feature branch but still partially transitional across the codebase
- WeChat payment recovery in `personal-dev-branch` is frontend-local and not robust across tabs or concurrent attempts
- the existing pending-auth migration update is too destructive to reuse unchanged in a safer rollout
- historical provider provenance should not be permanently flattened to `signup_source = email`
- design/plan drift can reintroduce ambiguous identity uniqueness or ambiguous adoption-decision ownership if not aligned before implementation
## Rollout Gates
The rebuild is not ready for rollout until all of these are satisfied:
1. Identity schema and migration chain are linearized and production-safe.
2. Email identity backfill is complete and idempotent.
3. Historical LinuxDo/WeChat/OIDC synthetic-email backfill to canonical identity is complete where deterministic, and non-recoverable rows are reported.
4. Historical WeChat `openid`-only rows are either remediated or explicitly blocked with operator-visible reporting.
5.`signup_source` backfill is accurate for known historical provider-created users.
6. Dual token acceptance, exchange bridge behavior, and required legacy field aliases are present for the bounded rollout window.
7. Existing payment configs are normalized and verified against current frontend-visible capabilities.
8. New frontend flows are verified against mixed-version backend compatibility windows.
9. Duplicate-account creation, first-bind grants, and payment route selection have regression coverage.
