oadmin/sub2api
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: add auth identity payment foundation design spec

Browse Source
This commit is contained in:
IanShaw027
2026-04-20 13:18:30 +08:00
parent 6c73b6212c
commit e01c1eaceb
1 changed files with 540 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

540
docs/superpowers/specs/2026-04-20-auth-identity-payment-foundation-design.md Normal file
View File

@@ -0,0 +1,540 @@
# Auth Identity And Payment Foundation Design
**Date:** 2026-04-20
**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`, `wechat`) 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
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.
- Third-party first login behavior:
- Existing bound identity: direct login
- Missing identity: start first-login flow
- 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.
- 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.
### 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`
- `wechat`
- 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.
### 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, 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.
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.
Fields:
- `user_id`
- `provider_type`: `email`, `linuxdo`, `oidc`, `wechat`
- `provider_key`
- `provider_subject`
- `verified_at`
- `issuer`
- `metadata`
- timestamps
Uniqueness:
- `provider_type + provider_key + provider_subject` must be unique
Rules:
- email identity uses canonicalized local email
- LinuxDo uses stable provider subject
- OIDC uses stable issuer + subject
- WeChat uses `unionid` as canonical subject
### `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`
- `pending_password_hash`
- `upstream_identity_payload`
- `metadata`
- `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
### `identity_adoption_decisions`
Persists user adoption preference for a specific identity.
Fields:
- `identity_id`
- `adopt_display_name`
- `adopt_avatar`
- `decided_at`
- timestamps
### `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
## 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
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
- 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 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
- 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
### WeChat login and channel mapping
- environment chooses `mp` or `open`
- 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`
- `wechat`
### 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.
### 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
### 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
## 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` and `mp` settings with config-valid and health indicators
### 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
- WeChat capability matrix:
- 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
### 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 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 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
### 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
### Rolling upgrade tolerance
- do not assume simultaneous frontend/backend deployment
- new backend must tolerate short-lived older frontend request shapes
## 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 payment config
- legacy auth payload field names
- historical payment result handling
## 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:
- 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
- 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
References:
- RFC 9700: <https://www.rfc-editor.org/rfc/rfc9700>
- 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>