From 4c8f2ffbb4a46a6a51263998c2ed5b987e27337a Mon Sep 17 00:00:00 2001 From: abose Date: Fri, 29 Aug 2025 17:50:02 +0530 Subject: [PATCH 1/2] docs: login-service-no_dist.md explaning how login works in browser --- src/services/login-browser.js | 24 ++++ src/services/login-service-no_dist.md | 191 ++++++++++++++++++++++++++ 2 files changed, 215 insertions(+) create mode 100644 src/services/login-service-no_dist.md diff --git a/src/services/login-browser.js b/src/services/login-browser.js index dcfaf2e1d5..336984f016 100644 --- a/src/services/login-browser.js +++ b/src/services/login-browser.js @@ -18,6 +18,30 @@ /*global logger*/ +/** + * Phoenix Browser Login Service + * + * This module handles user authentication for Phoenix browser applications. + * It integrates with the Phoenix login service to provide secure authentication + * across the phcode.dev domain ecosystem. + * + * IMPORTANT: For detailed setup instructions, development workflows, and + * troubleshooting guide, see: src/services/login-service-no_dist.md + * + * Key Features: + * - Domain-wide session management using 'session' cookie at .phcode.dev level + * - Proxy server support for localhost development (serve-proxy.js) + * - Support for both production (account.phcode.dev) and custom login servers + * - Automatic session validation and user profile management + * + * Development Notes: + * - Production: Uses account.phcode.dev directly with domain-wide cookies + * - Development: Uses /proxy/accounts route through serve-proxy.js for localhost:8000 to account.phcode.dev + * - Session cookies must be manually copied from account.phcode.dev to localhost for testing + * + * @see src/services/login-service-no_dist.md for comprehensive documentation + */ + define(function (require, exports, module) { const EventDispatcher = require("utils/EventDispatcher"), PreferencesManager = require("preferences/PreferencesManager"), diff --git a/src/services/login-service-no_dist.md b/src/services/login-service-no_dist.md new file mode 100644 index 0000000000..65d37f596e --- /dev/null +++ b/src/services/login-service-no_dist.md @@ -0,0 +1,191 @@ +# Phoenix Login Service Integration + +This document provides comprehensive documentation for integrating with the Phoenix login service in browser applications. + +## Overview + +The Phoenix browser application uses a login service to authenticate users across the phcode.dev domain ecosystem. The login service handles user authentication, session management, and provides secure API endpoints for login operations. + +**Key Files:** +- `src/services/login-browser.js` - Main browser login implementation +- `serve-proxy.js` - Proxy server for localhost development +- This documentation file for detailed integration guide + +## Architecture + +### Production Environment + +In production, the browser application uses `https://account.phcode.dev` as the login service endpoint. + +**Domain-Wide Session Management:** +- Login service sets a `session` cookie at the `.phcode.dev` domain level +- This cookie is automatically shared across all subdomains: + - `phcode.dev` + - `dev.phcode.dev` + - `*.phcode.dev` (any subdomain) +- Users login once and stay authenticated across the entire ecosystem + +**Communication Flow:** +``` +Browser App (*.phcode.dev) → account.phcode.dev + ← session cookie set for .phcode.dev +``` + +### Development Environment (localhost:8000) + +**Challenge:** +localhost:8000 doesn't share the `.phcode.dev` domain, so session cookies from account.phcode.dev are not automatically available. + +**Solution:** +Manual session cookie copying with proxy server routing. + +#### Proxy Server Architecture + +The `serve-proxy.js` server handles API routing for localhost development: + +``` +Browser (localhost:8000) → /proxy/accounts/* → serve-proxy.js → https://account.phcode.dev/* + ← Response with cookies + ← Cookies forwarded back to browser +``` + +**Key Function in login-browser.js:** +```javascript +function _getAccountBaseURL() { + if (location.hostname === 'localhost' || location.hostname === '127.0.0.1') { + return '/proxy/accounts'; // Use proxy for localhost + } + return Phoenix.config.account_url.replace(/\/$/, ''); // Direct URL for production +} +``` + +## Development Setup Instructions + +### Standard Development (localhost:8000 → account.phcode.dev) + +1. **Login to Production Account Service:** + - Open browser and navigate to `https://account.phcode.dev` + - Login with your credentials + - Account service sets `session` cookie for `.phcode.dev` domain + +2. **Copy Session Cookie to Localhost:** + - Open Chrome DevTools (F12) on `https://account.phcode.dev` + - Go to Application → Cookies → `https://account.phcode.dev` + - Find the `session` cookie and copy its value + +3. **Set Cookie in Localhost App:** + - Navigate to `http://localhost:8000/src/` + - Open Chrome DevTools (F12) + - Go to Application → Cookies → `http://localhost:8000` + - Create new cookie: + - **Name:** `session` + - **Value:** [paste copied value] + - **Domain:** `localhost` + - **Path:** `/` + - **HttpOnly:** ✓ (check if available) + +4. **Verify Integration:** + - Refresh `http://localhost:8000/src/` + - Login should work automatically using the copied session + +### Custom Login Server Development (localhost:5000) + +For testing with a local account server instance: + +1. **Configure Proxy Server:** + - Edit `serve-proxy.js` + - **Comment out:** `const ACCOUNT_SERVER = 'https://account.phcode.dev'; // Production` + - **Uncomment:** `const ACCOUNT_SERVER = 'http://localhost:5000'; // Local development` + +2. **Setup Local Account Server:** + - Start your local account development stack on `localhost:5000` + - Ensure all login endpoints are properly configured + +3. **Login and Copy Session:** + - Navigate to `http://localhost:5000` in browser + - Login with test credentials + - Copy `session` cookie value from DevTools + +4. **Set Cookie in Phoenix App:** + - Navigate to `http://localhost:8000/src/` + - Open Chrome DevTools → Application → Cookies + - Create `session` cookie with copied value (same process as above) + +5. **Verify Local Integration:** + - API calls from localhost:8000 now route through serve-proxy.js to localhost:5000 + - Authentication should work with local account server + +## API Endpoints + +The login service provides these key endpoints: + +### Authentication +- `POST /signOutPost` - Sign out user (new endpoint with proper JSON handling) +- `GET /resolveBrowserSession` - Validate and resolve current session +- `GET /signOut` - Legacy signout endpoint (deprecated for browser use) + +### Session Management +- Session validation through `session` cookie +- Automatic session invalidation on logout +- Session sharing across domain ecosystem + +## Communication Paths + +### Production (phcode.dev subdomains): +``` +Browser App → Direct HTTPS → account.phcode.dev + ← Session cookie for .phcode.dev ← +``` + +### Development (localhost): +``` +Browser (localhost:8000) → /proxy/accounts/* → serve-proxy.js + ↓ + account.phcode.dev (or localhost:5000) + ↓ + ← API response ← serve-proxy.js +``` + +## Troubleshooting + +### Common Issues + +**1. "No session found" errors:** +- Verify `session` cookie is set correctly in browser +- Check cookie domain and path settings +- Ensure cookie hasn't expired + +**2. CORS errors in development:** +- Verify serve-proxy.js is running on port 8000 +- Check proxy configuration in serve-proxy.js +- Confirm account server URL is correct + +**3. Login popup doesn't appear:** +- Check if popup blockers are enabled +- Verify account service URL is accessible +- Check browser console for JavaScript errors + +**4. Session not persisting:** +- Ensure cookie is set with correct domain +- Check if HttpOnly flag is properly configured +- Verify account service is responding correctly + +### Development Tips + +1. **Always use Chrome DevTools** to inspect cookies and network requests +2. **Monitor Network tab** to see actual API calls and responses +3. **Check Console** for authentication-related errors +4. **Verify proxy routing** by checking serve-proxy.js logs +5. **Test both login and logout flows** to ensure complete functionality + +## Security Considerations + +- Session cookies are HttpOnly and secure in production +- Always use HTTPS in production environments +- Local development should never use production user credentials in local account servers +- Session cookies should have appropriate expiration times +- Logout should properly invalidate sessions on both client and server + +--- + +For implementation details, see the source code in `src/services/login-browser.js` and related files. \ No newline at end of file From 7df98c378a0dfa824f108264219e4ff45de003c8 Mon Sep 17 00:00:00 2001 From: abose Date: Fri, 29 Aug 2025 18:25:34 +0530 Subject: [PATCH 2/2] docs: for login service arch in desktop and browser --- gulpfile.js/index.js | 3 +- ...ist.md => readme-login-browser-no_dist.md} | 9 +- src/services/readme-login-desktop-no_dist.md | 329 ++++++++++++++++++ 3 files changed, 336 insertions(+), 5 deletions(-) rename src/services/{login-service-no_dist.md => readme-login-browser-no_dist.md} (91%) create mode 100644 src/services/readme-login-desktop-no_dist.md diff --git a/gulpfile.js/index.js b/gulpfile.js/index.js index 7e70b6c62d..48405c4b1a 100644 --- a/gulpfile.js/index.js +++ b/gulpfile.js/index.js @@ -66,7 +66,8 @@ function cleanUnwantedFilesInDist() { 'dist/nls/*/expertTranslations.json', 'dist/nls/*/lastTranslated.json', 'dist/nls/*/*.js.map', - 'dist/extensions/default/*/unittests.js.map' + 'dist/extensions/default/*/unittests.js.map', + 'dist/**/*no_dist.*' ]); } diff --git a/src/services/login-service-no_dist.md b/src/services/readme-login-browser-no_dist.md similarity index 91% rename from src/services/login-service-no_dist.md rename to src/services/readme-login-browser-no_dist.md index 65d37f596e..87c8946fa4 100644 --- a/src/services/login-service-no_dist.md +++ b/src/services/readme-login-browser-no_dist.md @@ -1,6 +1,6 @@ -# Phoenix Login Service Integration +# Phoenix Browser Login Service Integration -This document provides comprehensive documentation for integrating with the Phoenix login service in browser applications. +This document provides comprehensive documentation for integrating with the Phoenix login service in browser applications specifically. For desktop application authentication, see `readme-login-desktop-no_dist.md`. ## Overview @@ -9,7 +9,8 @@ The Phoenix browser application uses a login service to authenticate users acros **Key Files:** - `src/services/login-browser.js` - Main browser login implementation - `serve-proxy.js` - Proxy server for localhost development -- This documentation file for detailed integration guide +- `readme-login-browser-no_dist.md` - This documentation file for detailed integration guide +- `readme-login-desktop-no_dist.md` - Desktop authentication documentation ## Architecture @@ -188,4 +189,4 @@ Browser (localhost:8000) → /proxy/accounts/* → serve-proxy.js --- -For implementation details, see the source code in `src/services/login-browser.js` and related files. \ No newline at end of file +For browser implementation details, see the source code in `src/services/login-browser.js` and related files. For desktop authentication, see `src/services/login-desktop.js` and `readme-login-desktop-no_dist.md`. \ No newline at end of file diff --git a/src/services/readme-login-desktop-no_dist.md b/src/services/readme-login-desktop-no_dist.md new file mode 100644 index 0000000000..1e7ee1cc23 --- /dev/null +++ b/src/services/readme-login-desktop-no_dist.md @@ -0,0 +1,329 @@ +# Phoenix Desktop Login Service Integration + +This document provides comprehensive documentation for integrating with the Phoenix login service in desktop applications. For browser application authentication, see `readme-login-browser-no_dist.md`. + +## Overview + +The Phoenix desktop application uses a fundamentally different authentication approach compared to browser applications. Instead of session cookies, desktop apps use API keys with enhanced security measures to prevent phishing attacks and ensure secure credential storage. + +**Key Files:** +- `src/services/login-desktop.js` - Main desktop login implementation +- `readme-login-desktop-no_dist.md` - This documentation file +- `readme-login-browser-no_dist.md` - Browser authentication documentation +- Kernel Mode Trust files - For secure credential storage (referenced for further reading) + +## Architecture Overview + +### Core Differences from Browser Authentication + +| Feature | Desktop Application | Browser Application | +|---------|-------------------|-------------------| +| **Authentication Method** | API Keys | Session Cookies | +| **Storage** | System Keychain via Tauri APIs | Browser cookies | +| **Security Layer** | Kernel Mode Trust | Domain-based security | +| **Phishing Protection** | Verification Codes | Domain validation | +| **Cross-window sync** | Preference-based notifications | Shared domain cookies | + +## Desktop Authentication Flow + +### 1. API Key-Based Authentication + +Desktop applications do **NOT** use session cookies. Instead, they use API keys that are: + +- Obtained through a secure authentication flow +- Stored securely in the system keychain via Tauri APIs +- Inaccessible to browser extensions due to Kernel Mode Trust security posture +- Required with every API request + +### 2. Verification Code Security System + +To prevent phishing attacks where malicious users could send authentication URLs to unsuspecting victims, the desktop app implements a verification code system: + +**The Attack Vector:** +- Malicious user generates an authentication URL +- Sends it to victim via email/message +- Victim clicks and logs in, unknowingly giving access to malicious user + +**The Protection:** +- Desktop app generates a unique verification code for each login session +- User must enter this verification code to complete authentication +- Even if a victim logs in with a malicious URL, they cannot provide the verification code + +### 3. Auto-Verification Flow + +For improved user experience, the desktop app includes an automatic verification system: + +**Components:** +- **Local Node.js Server:** Started by desktop app on a dynamically detected free port (port 0) +- **Random URL Security:** Auto auth endpoint uses randomly generated URL path (`/AutoAuth${randomNonce(8)}`) for security +- **Account Service Integration:** account.phcode.dev/auth communicates with the secure localhost endpoint +- **Automatic Code Exchange:** Verification code automatically provided if on same machine + +**Browser Compatibility:** +- ✅ **Chrome/Chromium:** Full auto-verification support +- ✅ **Firefox:** Full auto-verification support +- ❌ **Safari:** Auto-verification **BLOCKED** - Safari's security policy prevents HTTPS sites from connecting to localhost +- ⚠️ **Other Browsers:** May vary based on security policies + +**Flow:** +1. Desktop app starts local Node.js server on a dynamically detected free port +2. Random secure auto auth URL is generated: `http://localhost:{port}/AutoAuth{randomNonce}` +3. User initiates login, gets verification code and auto auth URL +4. Desktop app sends verification code to local server via `setVerificationCode()` +5. User clicks "Open in Browser" → goes to account.phcode.dev/auth +6. Account service attempts GET to `{autoAuthURL}/autoVerifyCode` endpoint +7. **If successful (Chrome/Firefox):** verification code automatically retrieved and used +8. Account service calls `{autoAuthURL}/appVerified` to notify desktop app +9. **If failed (Safari/blocked):** user manually enters verification code + +## Secure Credential Storage + +### Kernel Mode Trust Integration + +Desktop applications leverage Kernel Mode Trust for secure credential management: + +- **API Key Storage:** Securely stored in system keychain via Tauri APIs +- **Extension Isolation:** External extensions cannot access credentials +- **Integrated Extensions Only:** Only integrated extensions have access to Kernel Mode Trust +- **Cross-Platform Security:** Tauri provides secure storage across Windows, Mac, Linux + +**For detailed technical implementation of Kernel Mode Trust security architecture, refer to the Kernel Mode Trust source files (out of scope for this document).** + +## Authentication Endpoints and APIs + +### Key API Endpoints + +#### Authentication Session Management +```javascript +// Get app authentication session +GET ${Phoenix.config.account_url}getAppAuthSession?autoAuthPort=${authPortURL}&appName=${appName} +// Response: {"isSuccess":true,"appSessionID":"uuid...","validationCode":"SWXP07"} +``` + +#### API Key Resolution +```javascript +// Resolve API key with verification code +GET ${Phoenix.config.account_url}resolveAppSessionID?appSessionID=${apiKey}&validationCode=${validationCode} +// Response: User profile details if valid +``` + +#### Session Logout +```javascript +// Logout session +POST ${Phoenix.config.account_url}logoutSession +// Body: {"appSessionID": "api_key"} +``` + +#### Auto-Verification Endpoints (Local Server) + +The desktop app creates a local Node.js server with secure auto-authentication endpoints: + +```javascript +// Auto auth base URL (generated with random nonce for security) +// Example: http://localhost:43521/AutoAuthDI0zAUJo +const autoAuthURL = KernalModeTrust.localAutoAuthURL; + +// Get verification code endpoint +GET {autoAuthURL}/autoVerifyCode +// Response: {"code": "SWXP07"} or 404 if no code available +// Headers: Access-Control-Allow-Origin: https://account.phcode.dev + +// App verified notification endpoint +GET {autoAuthURL}/appVerified +// Response: "ok" +// Triggers desktop app to check login status +``` + +**Security Features:** +- **Random URL Path:** `/AutoAuth{randomNonce(8)}` makes URL unguessable +- **Origin Restrictions:** Only `https://account.phcode.dev` allowed +- **One-time Use:** Verification code returned only once, then cleared +- **Localhost Only:** Server binds to localhost interface only + +### API Request Authentication + +Unlike browser applications that rely on automatic cookie transmission, desktop applications must explicitly include the API key with every request: + +```javascript +// Every API call must include the API key +const userProfile = await KernalModeTrust.getCredential(KernalModeTrust.CRED_KEY_API); +const apiKey = JSON.parse(userProfile).apiKey; +// Include apiKey in request headers or parameters +``` + +## Implementation Details + +### Login Process + +1. **Initiate Login:** + ```javascript + const appAuthSession = await _getAppAuthSession(); + const {appSessionID, validationCode} = appAuthSession; + ``` + +2. **Setup Auto-Verification:** + ```javascript + await setAutoVerificationCode(validationCode); + ``` + +3. **Show Verification Dialog:** + - Display verification code to user + - Provide "Open in Browser" button + - Allow manual code entry if auto-verification fails + +4. **Monitor Authentication Status:** + ```javascript + const resolveResponse = await _resolveAPIKey(appSessionID, validationCode); + if(resolveResponse.userDetails) { + // Authentication successful + userProfile = resolveResponse.userDetails; + await KernalModeTrust.setCredential(KernalModeTrust.CRED_KEY_API, JSON.stringify(userProfile)); + } + ``` + +### Credential Management + +#### Storing Credentials +```javascript +// Store API key securely in system keychain +await KernalModeTrust.setCredential(KernalModeTrust.CRED_KEY_API, JSON.stringify(userProfile)); +``` + +#### Retrieving Credentials +```javascript +// Retrieve stored credentials +const savedUserProfile = await KernalModeTrust.getCredential(KernalModeTrust.CRED_KEY_API); +const userProfile = JSON.parse(savedUserProfile); +``` + +#### Removing Credentials (Logout) +```javascript +// Remove credentials from keychain +await KernalModeTrust.removeCredential(KernalModeTrust.CRED_KEY_API); +``` + +## Multi-Window Synchronization + +Desktop applications handle multi-window authentication synchronization through preferences: + +```javascript +const PREF_USER_PROFILE_VERSION = "userProfileVersion"; + +// Notify other windows of login state changes +PreferencesManager.stateManager.set(PREF_USER_PROFILE_VERSION, crypto.randomUUID()); + +// Listen for changes in other windows +const pref = PreferencesManager.stateManager.definePreference(PREF_USER_PROFILE_VERSION, 'string', '0'); +pref.watchExternalChanges(); +pref.on('change', _verifyLogin); +``` + +## Security Considerations + +### Phishing Attack Prevention +- **Verification Code System:** Prevents unauthorized access even if user logs in with malicious URL +- **Time-Limited Sessions:** Authentication sessions expire after 5 minutes +- **Local Verification:** Auto-verification only works on same machine + +### Secure Storage +- **System Keychain:** Credentials stored in OS-provided secure storage +- **Tauri Security:** Leverages Tauri's security model for cross-platform protection +- **Extension Isolation:** External extensions cannot access stored credentials + +### API Key Management +- **Unique Per Session:** Each authentication generates new API key +- **Server-Side Validation:** All API keys validated server-side +- **Proper Logout:** Server-side session invalidation on logout + +## Development and Testing + +### Testing with Local Login Server + +For testing desktop authentication with a local account server: + +1. **Configure Account URL:** + - Edit `src/config.json` + - Change `account_url` from `https://account.phcode.dev/` to `http://localhost:5000/` (or your local server URL) + +2. **Rebuild Application:** + ```bash + npm run build + ``` + +3. **Start Your Local Account Server:** + - Ensure your local account server is running on the configured port (e.g., localhost:5000) + - Verify all authentication endpoints are properly configured + +4. **Test Desktop Authentication:** + - Desktop app will now use your local server for all authentication calls + - Verification codes and API key resolution will go through your local server + - Auto-verification will attempt to connect to your local account service + +**Note:** Unlike browser testing which requires proxy server configuration, desktop apps simply use the `account_url` directly from config.json. + +## Troubleshooting + +### Common Issues + +**1. "No savedUserProfile found" errors:** +- Check if Kernel Mode Trust is properly initialized +- Verify Tauri keychain access permissions +- Ensure credentials weren't cleared by system security policies + +**2. Verification code timeout:** +- Verification codes expire after 5 minutes +- User must restart login process if expired +- Check local Node.js server connectivity for auto-verification + +**3. Auto-verification fails:** +- **Safari Browser:** Auto-verification is blocked by Safari's security policies +- **Firewall:** May be blocking localhost communication +- **Local Server Issues:** Server may not be running properly +- **Solution:** Always fall back to manual verification code entry + +**4. API key validation failures:** +- Check network connectivity to account service +- Verify API key hasn't been invalidated server-side +- Confirm account service URL configuration + +### Development Tips + +1. **Monitor Kernel Mode Trust Access:** Ensure proper initialization and access patterns +2. **Test Auto-Verification Flow:** + - Test in Chrome/Firefox for full functionality + - Test in Safari to ensure graceful fallback to manual entry + - Verify localhost server starts and responds correctly +3. **Browser Testing Strategy:** + - Chrome/Firefox: Expect auto-verification to work + - Safari: Always expect manual verification flow + - Test user experience in both scenarios +4. **Validate Credential Storage:** Check system keychain directly if available +5. **Test Multi-Window Sync:** Verify login state propagates across application windows +6. **Security Testing:** Test phishing protection by attempting malicious URL scenarios + +## API Error Handling + +### Error Codes +```javascript +const ERR_RETRY_LATER = "retry_later"; // Network/temporary errors +const ERR_INVALID = "invalid"; // API key/verification code invalid +``` + +### Response Handling +```javascript +const resolveResponse = await _resolveAPIKey(apiKey, validationCode); +if(resolveResponse.userDetails) { + // Success: use userDetails +} else if(resolveResponse.err === ERR_INVALID) { + // Invalid credentials: force re-authentication + await _resetAccountLogin(); +} else if(resolveResponse.err === ERR_RETRY_LATER) { + // Temporary error: retry later +} +``` + +--- + +For desktop implementation details, see the source code in `src/services/login-desktop.js`. For browser authentication, see `src/services/login-browser.js` and `readme-login-browser-no_dist.md`. + +For deeper understanding of the Kernel Mode Trust security architecture and secure credential storage implementation, refer to the Kernel Mode Trust source files (out of scope for this document). \ No newline at end of file