docs: add Flow C and Flow D documentation for self-service profile updates and social identity linking; remove outdated SPA flow documentation; update README with architecture changes

Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888

Assisted by [Claude Code](https://claude.ai/code)

Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>

Author: mauriciozanettisalomao

…/auth-flows/C-spa-profile-update-oidc.md docs/auth-flows/C-profile-update.mddocs/auth-flows/C-spa-profile-update-oidc.md renamed to docs/auth-flows/C-profile-update.md docs/auth-flows/C-spa-profile-update-oidc.md renamed to docs/auth-flows/C-profile-update.md

@@ -1,7 +1,7 @@
-# Flow C: Self-Service Profile Update via SPA OIDC for Management API audience ('self' Auth0 access)
+# Flow C: Self-Service Profile Update via Regular Web Client
 
 ## Description
-OpenID Connect (OIDC) flow for the Auth0 Management API audience, allowing users to manage their own profiles (“self” Auth0 access). This flow shares the same client used by Flow D’s SPA client.
+Flow for the Auth0 Management API audience, allowing users to manage their own profiles ("self" Auth0 access). This flow uses the LFX One Profile Client (regular web application) and implements a dual authentication pattern where users first authenticate with the main LFX One client, then obtain additional access tokens for Management API access.
 
 ## Sequence Diagram
 
@@ -14,7 +14,7 @@ sequenceDiagram
     participant Auth0 as Auth0 Authentication API
     participant Auth0Mgmt as Auth0 Management API
 
-    Note over User,Auth0Mgmt: Flow C: 2nd OIDC flow for Management API audience<br/>("self" Auth0 access)
+    Note over User,Auth0Mgmt: Flow C: Secondary authentication flow for Management API audience<br/>("self" Auth0 access)
 
     User->>SSR: Request to update own profile
 

docs/auth-flows/D-social-identity-linking.md

@@ -0,0 +1,48 @@
+# Flow D: Link Social Identity via Regular Web Client (No Audience)
+
+## Description
+Regular web client flow for linking social identities by authenticating with the social provider. Uses the LFX One Profile Client and access_token_mgmt_self from Flow C (Management API token) to perform the actual linking operation. This flow uses server-side redirects instead of popup/webmessage pattern.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Browser as User Browser
+    participant SSR as LFX One SSR
+    participant Auth0 as Auth0 Authentication API
+    participant NATS as NATS
+    participant AuthSvc as Auth Service
+    participant Auth0Mgmt as Auth0 Management API
+
+    Note over Browser,Auth0Mgmt: Flow D: Link social identity via regular web client<br/>(no audience - just authenticate with social provider)
+    
+    Browser->>SSR: User clicks "Link Google"<br/>(or other social provider)
+    
+    SSR->>Auth0: D1: GET /authorize<br/>w/ "LFX One Profile" client<br/>response_type=code<br/>[NO audience]<br/>connection=google-oauth2<br/>redirect_uri=SSR_callback
+    
+    Auth0->>Browser: Present social provider<br/>authentication
+    
+    Browser->>Auth0: User authenticates with<br/>social provider
+    
+    Auth0->>SSR: D2: Redirect with auth_code
+    
+    SSR->>Auth0: D3: POST /oauth2/token<br/>[authorization_code grant]<br/>w/ "LFX One Profile" client credentials<br/>+ auth_code<br/>[NO audience]
+    
+    Auth0-->>SSR: D4: access_token_social<br/>for /userinfo (IGNORE) +<br/>id_token_social
+
+    Note over SSR: SSR uses<br/>access_token_mgmt_self from Flow C<br/>(Management API token)
+
+    SSR->>NATS: D5: Publish link request<br/>with access_token_mgmt_self + id_token_social
+    Note over NATS,AuthSvc: Auth Service subscribed to NATS subject
+    NATS->>AuthSvc: Deliver request
+
+    AuthSvc->>Auth0Mgmt: Link social identity<br/>using access_token_mgmt_self<br/>w/ id_token_social claims
+    
+    Auth0Mgmt-->>AuthSvc: Identity linked successfully
+    AuthSvc->>NATS: Publish response
+    NATS->>SSR: Deliver response
+    
+    SSR-->>Browser: Update UI with<br/>newly linked identity
+    
+    Note over Browser,Auth0Mgmt: Auth Service abstracts all Auth0 Management API calls
+```

docs/auth-flows/D-spa-social-identity-linking.md

@@ -1,29 +1,29 @@
 # Flow E: Link Email Identity via Passwordless
 
 ## Description
-SPA/SSR flow for linking additional email addresses to a user's account using passwordless authentication. All Auth0 API calls (both passwordless and Management API) are made by Auth Service, with SSR communicating via NATS pub/sub pattern. Uses access_token_mgmt_self from Flow C (Management API token) to perform the actual linking operation. The user verifies ownership of the email by entering a one-time verification code in LFX One.
+SSR flow for linking additional email addresses to a user's account using passwordless authentication. Uses the LFX One Profile Client for the passwordless OTP flow. All Auth0 API calls (both passwordless and Management API) are made by Auth Service, with SSR communicating via NATS pub/sub pattern. Uses access_token_mgmt_self from Flow C (Management API token) to perform the actual linking operation. The user verifies ownership of the email by entering a one-time verification code in LFX One.
 
 ## Sequence Diagram
 
 ```mermaid
 sequenceDiagram
-    participant Browser as User Browser/SPA
+    participant Browser as User Browser
     participant SSR as LFX One SSR
     participant NATS as NATS
     participant AuthSvc as Auth Service
     participant Auth0 as Auth0 Authentication API
     participant MUA as Mail User Agent
     participant Auth0Mgmt as Auth0 Management API
 
-    Note over Browser,Auth0Mgmt: Flow E: Link email identity via passwordless<br/>(email verification with OTP code)
+    Note over Browser,Auth0Mgmt: Flow E: Link email identity via passwordless<br/>(email verification with OTP code using LFX One Profile Client)
     
     Browser->>SSR: User clicks "Add Email"<br/>and enters new email address
     
     SSR->>NATS: E1: Publish passwordless<br/>start request with email
     Note over NATS,AuthSvc: Auth Service subscribed to NATS subject
     NATS->>AuthSvc: Deliver request
     
-    AuthSvc->>Auth0: E2: POST /passwordless/start<br/>w/ "LFX One Passwordless" client credentials<br/>email=new_email@example.com<br/>connection=email<br/>send=code
+    AuthSvc->>Auth0: E2: POST /passwordless/start<br/>w/ "LFX One Profile" client credentials<br/>email=new_email@example.com<br/>connection=email<br/>send=code
     
     Auth0->>MUA: Send verification code
     
@@ -41,7 +41,7 @@ sequenceDiagram
     SSR->>NATS: E3: Publish verification request<br/>with code + access_token_mgmt_self
     NATS->>AuthSvc: Deliver request
 
-    AuthSvc->>Auth0: E4: POST /oauth2/token<br/>[passwordless grant]<br/>w/ "LFX One Passwordless" client credentials<br/>username=new_email@example.com<br/>otp=verification_code<br/>[NO audience]
+    AuthSvc->>Auth0: E4: POST /oauth2/token<br/>[passwordless grant]<br/>w/ "LFX One Profile" client credentials<br/>username=new_email@example.com<br/>otp=verification_code<br/>[NO audience]
 
     Auth0-->>AuthSvc: E5: access_token_pwdless<br/>for /userinfo (IGNORE) +<br/>id_token_pwdless
 

docs/auth-flows/E-passwordless-email-linking.md

@@ -7,8 +7,7 @@ This directory contains sequence diagrams documenting the authentication flows u
 The authentication architecture uses multiple Auth0 clients and flows to support different use cases:
 
 - **LFX One Client**: Regular web application used for server-side rendering authentication with LFX v2 API access
-- **LFX One Profile Client**: Single Page Application (SPA) used for social account linking and self-service Auth0 access (user profile updates)
-- **LFX One Passwordless Client**: Regular web application used for passwordless email linking flow via Auth Service. This client supports the OTP grant type and may use different validation in the postLogin action.
+- **LFX One Profile Client**: Regular web application used for social account linking, self-service Auth0 access (user profile updates), and passwordless email linking. This client supports both Authorization Code flow for Management API access and OTP grant type for passwordless flows.
 - **LFX V2 Auth Service Client**: Machine-to-machine client used by Auth Service for reading user profiles
 
 ## Authentication Flows
@@ -17,20 +16,17 @@ The authentication architecture uses multiple Auth0 clients and flows to support
 |------|-------------|-------------|----------|---------|
 | [Flow A](A-auth-service-m2m-profile-lookup.md) | Auth Service M2M | Auth Service M2M | `auth0_mgmt` | Read user profiles and check email-to-username mappings |
 | [Flow B](B-lfx-one-login-ssr-oidc.md) | LFX One Login (SSR OIDC) | LFX One | `lfxv2` | Authenticate users and obtain access tokens for LFX v2 API |
-| [Flow C](C-spa-profile-update-oidc.md) | Self-Service Profile Updates | LFX One Profile | `auth0_mgmt` | Allow users to update their own profiles via Management API |
-| [Flow D](D-spa-social-identity-linking.md) | Social Identity Linking | LFX One Profile | None | Link social identities (Google, GitHub, etc.) to user accounts |
-| [Flow E](E-passwordless-email-linking.md) | Email Identity Linking | LFX One Passwordless | None | Link additional email addresses using passwordless OTP verification |
+| [Flow C](C-profile-update.md) | Self-Service Profile Updates | LFX One Profile | `auth0_mgmt` | Allow users to update their own profiles via Management API |
+| [Flow D](D-social-identity-linking.md) | Social Identity Linking | LFX One Profile | None | Link social identities (Google, GitHub, etc.) to user accounts |
+| [Flow E](E-passwordless-email-linking.md) | Email Identity Linking | LFX One Profile | None | Link additional email addresses using passwordless OTP verification |
 
 ## Client Descriptions
 
 ### LFX One Client
 The main server-side rendering client used for user authentication. This is a regular web application client that implements the authorization code flow with grant types `authorization_code` and `refresh_token` (plus `password-realm` in dev environments for Cypress testing). It obtains access tokens with the `lfxv2` audience for accessing the LFX v2 API (Traefik/Heimdall). This client is used exclusively in Flow B for the initial user login.
 
 ### LFX One Profile Client
-This client is used for social account linking and self-service Auth0 access. This is a **Single Page Application (SPA)** client (`app_type: spa`) that uses the authorization code flow with PKCE and public client authentication (no client secret). It implements the popup/webmessage flow for social identity linking and allows users to update their own profiles through the Auth0 Management API with restricted permissions (users can only modify their own data). Used in Flows C and D.
-
-### LFX One Passwordless Client
-A specialized client used for the passwordless email linking flow, primarily by the Auth Service. This is a **regular web application** client (`app_type: regular_web`) that uses the passwordless OTP grant type (`http://auth0.com/oauth/grant-type/passwordless/otp`). This client is specifically designed for email verification flows and may use different validation logic in the postLogin action compared to other clients. Used exclusively in Flow E.
+A **regular web application** client (`app_type: regular_web`) used for Auth0 Management API access and passwordless flows. This client uses the authorization code flow for obtaining Management API access tokens that allow users to update their own profiles and link identities. It also supports the passwordless OTP grant type (`http://auth0.com/oauth/grant-type/passwordless/otp`) for email verification flows. This client implements a dual authentication pattern where users first authenticate with the main LFX One client, then use this client to obtain additional access tokens for specific audiences (Management API) or perform passwordless verification. Used in Flows C, D, and E.
 
 ### LFX V2 Auth Service M2M Client
 A **machine-to-machine (M2M)** client named "LFX V2 Auth Service" that uses the client credentials grant type. This client has restricted permissions with only `read:users` scope (but **not** `update:users`) for the Auth0 Management API. It is used exclusively by the Auth Service to perform read-only operations such as profile lookups and checking email-to-username mappings. Used exclusively in Flow A.
@@ -78,3 +74,34 @@ All Auth0 Management API calls are abstracted through the Auth Service, which co
 4. **Token Scoping**: Each access token is scoped to specific audiences and permissions
 5. **Abstraction Layer**: Management API calls go through Auth Service, not directly from client
 
+## Architecture Changes (December 2025)
+
+### Consolidation to Regular Web Clients
+
+Based on the PoC implementation in `poc/2025-12-Express-Two-Audiences`, the authentication architecture has been updated to remove the SPA client and consolidate to regular web applications:
+
+**Previous Architecture:**
+- LFX One Client (Regular Web) - Main login
+- LFX One Profile Client (SPA) - Management API access and social linking
+- LFX One Passwordless Client (Regular Web) - Email verification
+
+**Updated Architecture:**
+- LFX One Client (Regular Web) - Main login for LFX v2 API access
+- LFX One Profile Client (Regular Web) - All Management API operations, social linking, and passwordless flows
+
+### Dual Authentication Pattern
+
+The new architecture implements a dual authentication pattern:
+
+1. **Primary Authentication**: Users first authenticate with the LFX One Client to establish their session and get LFX v2 API access
+2. **Secondary Authentication**: When Management API access is needed, users authenticate again with the LFX One Management Client to get audience-specific tokens
+
+This pattern provides better security isolation and allows for different scopes and permissions for different purposes while maintaining a unified user experience.
+
+### Benefits
+
+- **Simplified Architecture**: Fewer clients to manage and configure
+- **Better Security**: Clear separation between different token audiences
+- **Consistent UX**: All flows use server-side redirects instead of mixed SPA/popup patterns
+- **Easier Deployment**: No client-side secret management or CORS concerns
+

docs/auth-flows/README.md

@@ -183,23 +183,6 @@ The email verification and linking functionality is exposed via three NATS subje
 - Verifies the token has the required `update:current_user_identities` scope
 - Uses the extracted `user_id` to make the identity linking API call with the `link_with` ID token
 
-### Auth0 Configuration Requirements
-
-To enable email verification, configure the following in your Auth0 tenant:
-
-1. **Enable Passwordless Connection:**
-   - Go to Authentication → Passwordless
-   - Enable the Email connection
-   - Configure email template for OTP delivery
-
-2. **Application Configuration:**
-   - Ensure your Auth0 application has passwordless authentication enabled
-   - Configure callback URLs if needed
-
-3. **Email Template:**
-   - Customize the OTP email template in Authentication → Passwordless → Email
-   - Template should include the `{{ code }}` placeholder for the 6-digit OTP
-
 ### Security & Rate Limiting
 
 **Auth0 Security Features:**