docs: harden auth identity payment design

docs/superpowers/specs/2026-04-20-auth-identity-payment-foundation-design.md

@@ -20,10 +20,10 @@ This design includes:
 - 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`, `wechat`) mapped to a single active backend source each
+- 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 and historical LinuxDo synthetic-email users
+- 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.
 
@@ -32,9 +32,11 @@ This design does not treat unrelated upstream merges, docs churn, or license cha
 ### 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:
@@ -43,11 +45,25 @@ This design does not treat unrelated upstream merges, docs churn, or license cha
   - 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
 
@@ -85,7 +101,7 @@ This design does not treat unrelated upstream merges, docs churn, or license cha
 
 - Frontend shows only two display methods:
   - `alipay`
-  - `wechat`
+  - `wxpay`
 - Users never choose between official providers and EasyPay explicitly.
 - Backend allows only one active source per display method at a time.
 - Alipay UX:
@@ -96,6 +112,10 @@ This design does not treat unrelated upstream merges, docs churn, or license cha
   - 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
 
@@ -105,9 +125,9 @@ This design does not treat unrelated upstream merges, docs churn, or license cha
 
 ## Architecture
 
-Keep `users` as the account owner table and move login identities, channel mappings, pending auth state, and first-bind grant idempotency into dedicated tables and services. Keep email login working while progressively introducing unified identity reads and writes.
+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.
+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.
 
@@ -148,9 +168,9 @@ Uniqueness:
 Rules:
 
 - email identity uses canonicalized local email
-- LinuxDo uses stable provider subject
-- OIDC uses stable issuer + subject
-- WeChat uses `unionid` as canonical subject
+- 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`
 
@@ -189,9 +209,12 @@ Fields:
 - `target_user_id`
 - `redirect_to`
 - `resolved_email`
-- `pending_password_hash`
-- `upstream_identity_payload`
-- `metadata`
+- `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`
@@ -205,19 +228,33 @@ Responsibilities:
 - 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 for a specific identity.
+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.
@@ -265,6 +302,7 @@ 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
 
@@ -285,6 +323,7 @@ WeChat-specific rule:
 
 - Create `pending_auth_session`
 - Frontend callback flow decides next action
+- Pending session creation stores immutable upstream claims separately from mutable local progress fields
 
 Branches:
 
@@ -303,6 +342,7 @@ 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
 
@@ -310,21 +350,34 @@ On new account creation:
 
 - 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
@@ -344,7 +397,7 @@ On new account creation:
 ### User-visible methods
 
 - `alipay`
-- `wechat`
+- `wxpay`
 
 ### Backend source abstraction
 
@@ -357,6 +410,12 @@ Each display method maps to exactly one active configured backend source:
 
 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
@@ -372,11 +431,25 @@ Frontend submits display method only. Backend resolves display method to active
   - 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
 
@@ -420,6 +493,9 @@ 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
 
@@ -431,6 +507,8 @@ Compatibility is mandatory, especially for:
 
 - 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
@@ -438,7 +516,7 @@ Compatibility is mandatory, especially for:
 During rollout:
 
 - read new identity model first
-- where necessary, retain compatibility logic for existing email and historical LinuxDo synthetic-email recognition
+- where necessary, retain compatibility logic for existing email and historical LinuxDo/WeChat/OIDC synthetic-email recognition
 
 ### Grant idempotency
 
@@ -453,17 +531,20 @@ Retain transitional support for legacy/new request and response shapes where nee
 - `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
 
@@ -509,9 +590,13 @@ Retain transitional support for legacy/new request and response shapes where nee
 
 - 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
 
@@ -528,9 +613,12 @@ Retain transitional support for legacy/new request and response shapes where nee
 Implementation must follow current primary-source guidance:
 
 - OAuth 2.0 Security BCP (RFC 9700): strict redirect handling, state protection, mix-up resistant design
-- PKCE (RFC 7636): use on authorization code flows where applicable
+- 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
 
 References:
 
@@ -538,6 +626,10 @@ References:
 - RFC 7636: <https://www.rfc-editor.org/rfc/rfc7636>
 - OpenID Connect Core 1.0: <https://openid.net/specs/openid-connect-core-1_0.html>
 - Auth0 account linking guidance: <https://auth0.com/docs/manage-users/user-accounts/user-account-linking>
+- WeChat UnionID guidance: <https://developers.weixin.qq.com/doc/service/guide/product/unionid.html>
+- WeChat website login guidance: <https://developers.weixin.qq.com/doc/oplatform/Website_App/WeChat_Login/Wechat_Login.html>
+- WeChat Pay callback/signature guidance: <https://pay.weixin.qq.com/doc/v3/merchant/4012075249>
+- Stripe Checkout fulfillment guidance: <https://docs.stripe.com/checkout/fulfillment>
 
 ## Audit Synthesis
 
@@ -553,7 +645,7 @@ The clean rebuild direction is not to copy either existing branch directly.
 - `personal-dev-branch` has the better real-world closure:
   - LinuxDo and WeChat callback flows are more operationally complete
   - profile binding and avatar UX is more complete
-  - historical synthetic-email users are recognized and recovered in live flows
+  - historical synthetic-email users across multiple providers are recognized and recovered in live flows
   - WeChat payment OAuth and recovery behavior is more complete
 - Primary-source guidance supplies hard constraints for OAuth/OIDC, account linking, WeChat identity handling, and payment completion semantics.
 
@@ -584,6 +676,7 @@ Keep these operational flow ideas from `personal-dev-branch`:
 - 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
 
@@ -595,6 +688,7 @@ These areas must be reimplemented with the same intent but stricter boundaries:
 - 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
 
@@ -614,7 +708,7 @@ The audit and source review establish these hard constraints:
 
 ### Auth
 
-- all authorization-code providers use PKCE where applicable
+- 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
@@ -624,7 +718,8 @@ The audit and source review establish these hard constraints:
 
 - existing email users must continue to work with no manual intervention
 - existing LinuxDo users must not split into duplicate accounts
-- historical LinuxDo synthetic-email users must be backfilled into canonical LinuxDo identities during migration, not only lazily on next login
+- 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
@@ -634,7 +729,9 @@ The audit and source review establish these hard constraints:
 
 - 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`, `wechat`) may have only one active backend source at a time
+- 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
 
@@ -649,6 +746,7 @@ These are specifically observed problems in the existing branches that the clean
 - 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
 
@@ -656,9 +754,10 @@ 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 synthetic-email backfill to canonical LinuxDo identity is complete and idempotent.
-4. `signup_source` backfill is accurate for known historical provider-created users.
-5. Dual token acceptance and required legacy field aliases are present.
-6. Existing payment configs are normalized and verified against current frontend-visible capabilities.
-7. New frontend flows are verified against mixed-version backend compatibility windows.
-8. Duplicate-account creation, first-bind grants, and payment route selection have regression coverage.
+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.