feat: added OAuth 2.0 authentication with PKCE and automatic token refresh (#66)

* Initial plan

* Add OAuth 2.0 authentication types and core functionality

Co-authored-by: MathiasVDA <15101339+MathiasVDA@users.noreply.github.com>

* Add OAuth 2.0 styling, tests, and documentation

Co-authored-by: MathiasVDA <15101339+MathiasVDA@users.noreply.github.com>

* Add help link and OAuth2 provider examples (Azure, AWS, Keycloak)

Co-authored-by: MathiasVDA <15101339+MathiasVDA@users.noreply.github.com>

* Document OAuth2 redirect URI registration requirement

Co-authored-by: MathiasVDA <15101339+MathiasVDA@users.noreply.github.com>

* feat: added handling of id tokens

* chore: reset this bit to main

* Update packages/yasgui/src/Tab.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update docs/developer-guide.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update packages/yasgui/src/TabSettingsModal.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Fix OAuth2 race conditions, memory leaks, and improve UX

- Add unique flowId to prevent sessionStorage collisions across multiple OAuth flows
- Add flowCompleted flag to prevent race condition between polling and messageHandler
- Fix memory leaks by removing event listeners in all error paths
- Improve alert messages with specific instructions on accessing Settings
- Consolidate cleanup logic to prevent duplicate sessionStorage operations

Co-authored-by: MathiasVDA <15101339+MathiasVDA@users.noreply.github.com>

* Refactor: Extract closeModalAndRefresh helper to reduce duplication

Extract repeated pattern of closing auth modal and refreshing endpoints list into a helper function. This reduces code duplication across all authentication types (basic, bearer, apiKey, oauth2) and improves maintainability.

Co-authored-by: MathiasVDA <15101339+MathiasVDA@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: MathiasVDA <15101339+MathiasVDA@users.noreply.github.com>
Co-authored-by: Mathias Vanden Auweele <mathias@matdata.eu>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

docs/developer-guide.md

@@ -1014,6 +1014,7 @@ interface RequestConfig {
   basicAuth?: BasicAuthConfig | ((yasqe: Yasqe) => BasicAuthConfig | undefined);
   bearerAuth?: BearerAuthConfig | ((yasqe: Yasqe) => BearerAuthConfig | undefined);
   apiKeyAuth?: ApiKeyAuthConfig | ((yasqe: Yasqe) => ApiKeyAuthConfig | undefined);
+  oauth2Auth?: OAuth2AuthConfig | ((yasqe: Yasqe) => OAuth2AuthConfig | undefined);
 }
 
 interface BasicAuthConfig {
@@ -1029,6 +1030,11 @@ interface ApiKeyAuthConfig {
   headerName: string;
   apiKey: string;
 }
+
+interface OAuth2AuthConfig {
+  accessToken: string;
+  idToken?: string;
+}
 ```
 
 #### Request Configuration Example
@@ -1067,11 +1073,12 @@ YASGUI supports multiple authentication methods for SPARQL endpoints: Basic Auth
 
 #### Authentication Types
 
-YASGUI supports three authentication types:
+YASGUI supports four authentication types:
 
 1. **Basic Authentication**: Username and password sent as HTTP Basic Auth
 2. **Bearer Token**: Token sent in the `Authorization: Bearer <token>` header
 3. **API Key**: Custom header with an API key (e.g., `X-API-Key: <key>`)
+4. **OAuth 2.0**: Industry-standard OAuth 2.0 with automatic token refresh
 
 #### Basic Authentication
 
@@ -1159,6 +1166,24 @@ yasgui.persistentConfig.addOrUpdateEndpoint("https://api.example.com/sparql", {
   }
 });
 
+// Add or update an endpoint with OAuth 2.0
+yasgui.persistentConfig.addOrUpdateEndpoint("https://oauth.example.com/sparql", {
+  label: "OAuth Protected Endpoint",
+  showAsButton: true,
+  authentication: {
+    type: 'oauth2',
+    clientId: 'your-client-id',
+    authorizationEndpoint: 'https://auth.example.com/oauth/authorize',
+    tokenEndpoint: 'https://auth.example.com/oauth/token',
+    redirectUri: 'https://yourapp.com/oauth2-callback', // optional
+    scope: 'read write', // optional
+    // The following are automatically populated after authentication:
+    // accessToken: '...',
+    // refreshToken: '...',
+    // tokenExpiry: 1234567890
+  }
+});
+
 // Get endpoint configuration
 const config = yasgui.persistentConfig.getEndpointConfig("https://example.com/sparql");
 
@@ -1171,6 +1196,72 @@ yasgui.persistentConfig.addOrUpdateEndpoint("https://example.com/sparql", {
 yasgui.persistentConfig.deleteEndpointConfig("https://example.com/sparql");
 ```
 
+#### OAuth 2.0 Provider Examples
+
+**⚠️ Important Prerequisite:**
+Before OAuth 2.0 authentication can work, the **OAuth administrator must register the redirect URI** (callback URL) in the OAuth provider's application configuration. YASGUI uses the current page URL as the redirect URI by default (e.g., `https://yasgui.example.com/`). This URL must be added to the list of allowed redirect URIs in your OAuth application settings.
+
+**Microsoft Azure (Entra ID)**
+
+```javascript
+yasgui.persistentConfig.addOrUpdateEndpoint("https://your-sparql-endpoint.com/sparql", {
+  label: "Azure Protected Endpoint",
+  authentication: {
+    type: 'oauth2',
+    clientId: 'your-azure-client-id',
+    authorizationEndpoint: 'https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize',
+    tokenEndpoint: 'https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token',
+    scope: 'api://your-app-id/.default', // or specific scopes like 'openid profile'
+    redirectUri: window.location.origin + window.location.pathname // optional
+  }
+});
+```
+
+**Redirect URI Registration:** In Azure AD app registration, add your YASGUI URL to "Redirect URIs" under Authentication settings.
+
+**AWS Cognito**
+
+```javascript
+yasgui.persistentConfig.addOrUpdateEndpoint("https://your-sparql-endpoint.com/sparql", {
+  label: "AWS Cognito Protected Endpoint",
+  authentication: {
+    type: 'oauth2',
+    clientId: 'your-cognito-app-client-id',
+    authorizationEndpoint: 'https://your-domain.auth.region.amazoncognito.com/oauth2/authorize',
+    tokenEndpoint: 'https://your-domain.auth.region.amazoncognito.com/oauth2/token',
+    scope: 'openid profile', // adjust based on your needs
+    redirectUri: window.location.origin + window.location.pathname // optional
+  }
+});
+```
+
+**Redirect URI Registration:** In Cognito app client settings, add your YASGUI URL to "Allowed callback URLs".
+
+**Keycloak**
+
+```javascript
+yasgui.persistentConfig.addOrUpdateEndpoint("https://your-sparql-endpoint.com/sparql", {
+  label: "Keycloak Protected Endpoint",
+  authentication: {
+    type: 'oauth2',
+    clientId: 'your-keycloak-client-id',
+    authorizationEndpoint: 'https://your-keycloak-domain.com/realms/{realm-name}/protocol/openid-connect/auth',
+    tokenEndpoint: 'https://your-keycloak-domain.com/realms/{realm-name}/protocol/openid-connect/token',
+    scope: 'openid profile', // adjust based on your client configuration
+    redirectUri: window.location.origin + window.location.pathname // optional
+  }
+});
+```
+
+**Redirect URI Registration:** In Keycloak client configuration, add your YASGUI URL to "Valid Redirect URIs".
+
+**Important Notes:**
+- Replace placeholders like `{tenant-id}`, `{realm-name}`, `region`, etc. with your actual values
+- **The OAuth administrator must register the redirect URI** in the OAuth provider before authentication will work
+- For Azure, the client must be registered in Azure AD with public client flow enabled
+- For AWS Cognito, the app client should have "Authorization code grant" flow enabled
+- For Keycloak, the client should have "Standard Flow" enabled and "Access Type" set to "public"
+
 #### Dynamic Authentication
 
 Use a function to dynamically provide credentials:

docs/user-guide.md

@@ -709,23 +709,53 @@ The endpoints table shows:
 
 **Configuring Authentication:**
 
-YASGUI supports HTTP Basic Authentication for endpoints that require username and password credentials.
+YASGUI supports multiple authentication methods for endpoints that require credentials.
 
 1. **Find your endpoint** in the SPARQL Endpoints table
 2. **Click "Configure"** in the Authentication column
-3. **Select authentication type** (currently HTTP Basic Authentication)
-4. **Enter credentials**:
-   - Username: Your endpoint username
-   - Password: Your endpoint password
-5. **Click "Save"** to apply
+3. **Select authentication type**:
+   - **HTTP Basic Authentication**: Username and password
+   - **Bearer Token**: Pre-configured access token
+   - **API Key**: Custom header with API key
+   - **OAuth 2.0**: Industry-standard OAuth 2.0 authorization
+4. **Enter credentials** based on your selected type (see below)
+5. **Click "Save"** (or "Save & Authenticate" for OAuth 2.0) to apply
+
+**Authentication Types:**
+
+*HTTP Basic Authentication:*
+- Username: Your endpoint username
+- Password: Your endpoint password
+- Use case: Simple username/password authentication
+
+*Bearer Token:*
+- Token: Your pre-configured bearer token
+- Use case: When you have a pre-generated access token
+
+*API Key (Custom Header):*
+- Header Name: The HTTP header name (e.g., X-API-Key)
+- API Key: Your API key value
+- Use case: Endpoints using custom header-based authentication
+
+*OAuth 2.0:*
+- Client ID: Your OAuth application's client ID
+- Authorization Endpoint: The OAuth provider's authorization URL
+- Token Endpoint: The OAuth provider's token exchange URL
+- Redirect URI: Callback URL (optional, defaults to current page)
+- Scope: Space-separated OAuth scopes (optional)
+- Use case: Secure, industry-standard authorization with automatic token refresh
+- **Process**: Click "Save & Authenticate" to open OAuth login window
+- **⚠️ Important**: The redirect URI must be registered with your OAuth provider by the OAuth administrator before authentication will work
 
 **Security Considerations:**
 
 ⚠️ **Important Security Notes:**
 
-- **Credentials are stored in browser localStorage**: Your username and password are stored locally in your browser
+- **Credentials are stored in browser localStorage**: Your authentication credentials are stored locally in your browser
 - **Only use with HTTPS endpoints**: Never send credentials to HTTP endpoints as they will be transmitted in plain text
 - **Be cautious on shared computers**: Clear your browser data when using YASGUI on shared or public computers
+- **OAuth 2.0 tokens**: Access tokens are automatically refreshed when expired (if refresh token is available)
+- **Token security**: OAuth 2.0 uses secure PKCE flow (Proof Key for Code Exchange) for enhanced security
 
 **How Authentication Works:**
 
@@ -735,10 +765,57 @@ Authentication is stored per-endpoint, which means:
 - Credentials persist across browser sessions (stored in localStorage)
 
 When authentication is configured:
+
+For **Basic Authentication**:
 1. YASGUI encodes your credentials using Base64 encoding
 2. Adds an `Authorization` header with the format: `Basic <encoded-credentials>`
 3. Sends this header with every SPARQL query request to that endpoint
 
+For **Bearer Token**:
+1. Uses the provided token as-is
+2. Adds an `Authorization` header with the format: `Bearer <token>`
+3. Sends this header with every SPARQL query request to that endpoint
+
+For **API Key**:
+1. Uses the specified custom header name and API key value
+2. Adds a custom header with the format: `<Header-Name>: <api-key>`
+3. Sends this header with every SPARQL query request to that endpoint
+
+For **OAuth 2.0**:
+1. Opens a popup window for OAuth provider authentication
+2. Uses Authorization Code flow with PKCE for secure token exchange
+3. Stores access token and refresh token
+4. Automatically checks token expiration before each query
+5. Automatically refreshes expired tokens using refresh token (if available)
+6. Adds an `Authorization` header with the format: `Bearer <access-token>`
+7. If token refresh fails, prompts user to re-authenticate
+
+**OAuth 2.0 Provider Examples:**
+
+**⚠️ Important Prerequisite:**
+Before using OAuth 2.0, the OAuth administrator must register the redirect URI (callback URL) in the OAuth provider's configuration. By default, YASGUI uses the current page URL as the redirect URI. For example, if YASGUI is hosted at `https://yasgui.example.com/`, this URL must be added to the allowed redirect URIs in your OAuth application settings.
+
+*Microsoft Azure (Entra ID):*
+- Authorization Endpoint: `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize`
+- Token Endpoint: `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
+- Scope: `api://your-app-id/.default` or `openid profile`
+- Note: Your app must be registered in Azure AD with public client flow enabled
+- **Redirect URI Registration**: Add your YASGUI URL to "Redirect URIs" in Azure AD app registration
+
+*AWS Cognito:*
+- Authorization Endpoint: `https://your-domain.auth.region.amazoncognito.com/oauth2/authorize`
+- Token Endpoint: `https://your-domain.auth.region.amazoncognito.com/oauth2/token`
+- Scope: `openid profile` (adjust as needed)
+- Note: Enable "Authorization code grant" flow in your app client settings
+- **Redirect URI Registration**: Add your YASGUI URL to "Allowed callback URLs" in Cognito app client settings
+
+*Keycloak:*
+- Authorization Endpoint: `https://your-keycloak-domain.com/realms/{realm-name}/protocol/openid-connect/auth`
+- Token Endpoint: `https://your-keycloak-domain.com/realms/{realm-name}/protocol/openid-connect/token`
+- Scope: `openid profile` (adjust based on client configuration)
+- Note: Client should have "Standard Flow" enabled and "Access Type" set to "public"
+- **Redirect URI Registration**: Add your YASGUI URL to "Valid Redirect URIs" in Keycloak client configuration
+
 ### Query History and Persistence
 
 YASGUI automatically saves your work locally.

packages/yasgui/src/ConfigExportImport.ts

@@ -307,6 +307,7 @@ export function parseFromTurtle(turtle: string): Partial<PersistedJson> {
             basicAuth: undefined,
             bearerAuth: undefined,
             apiKeyAuth: undefined,
+            oauth2Auth: undefined,
           },
           yasr: {
             settings: {},