legate 0.1.0

data/public/docs/authentication/api_reference/scheme.md

@@ -0,0 +1,250 @@
+# Legate::Auth::Scheme
+
+The `Scheme` class serves as the abstract base class for all authentication schemes in the Legate Ruby library. It defines the interface and common functionality that all authentication schemes must implement.
+
+## Overview
+
+Authentication schemes represent different methods of authenticating API requests, such as API keys, OAuth2, OpenID Connect, or service accounts. The `Scheme` class provides a consistent interface for all these authentication methods, enabling the Legate to work with different authentication mechanisms in a unified way.
+
+## Class Methods
+
+### `new`
+
+Creates a new instance of the authentication scheme.
+
+**Parameters:**
+- `kwargs` (Hash): Parameters specific to the authentication scheme
+
+**Examples:**
+
+```ruby
+# This is an abstract class and shouldn't be instantiated directly
+# Instead, use one of the concrete implementations:
+scheme = Legate::Auth::Schemes::ApiKey.new
+```
+
+## Instance Methods
+
+### `scheme_type`
+
+Returns the type of the authentication scheme. This method must be implemented by concrete subclasses.
+
+**Returns:**
+- Symbol: The authentication scheme type (e.g., `:api_key`, `:oauth2`)
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::ApiKey.new
+scheme.scheme_type  # => :api_key
+```
+
+### `apply_to_request`
+
+Applies authentication to a request based on the provided credential. This method must be implemented by concrete subclasses.
+
+**Parameters:**
+- `request` (Hash): The request to authenticate
+- `credential` (Legate::Auth::ExchangedCredential): The credential to use for authentication
+
+**Returns:**
+- Hash: The modified request with authentication applied
+
+**Examples:**
+
+```ruby
+# This method is called internally by the Legate
+# The implementation depends on the specific scheme
+```
+
+### `supports_refresh?`
+
+Returns whether this scheme supports token refresh.
+
+**Returns:**
+- Boolean: `true` if the scheme supports token refresh
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::OAuth2.new(token_url: 'https://example.com/token')
+scheme.supports_refresh?  # => true (if refresh is supported)
+```
+
+### `exchange_token`
+
+Exchanges a credential for an authentication token. This method must be implemented by concrete subclasses that support token exchange.
+
+**Parameters:**
+- `credential` (Legate::Auth::Credential): The credential to exchange
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The exchanged token
+
+**Examples:**
+
+```ruby
+# This method is called internally by the Legate
+# The implementation depends on the specific scheme
+```
+
+### `refresh_token`
+
+Refreshes an expired token. This method must be implemented by concrete subclasses that support token refresh.
+
+**Parameters:**
+- `token` (Legate::Auth::ExchangedCredential): The token to refresh
+- `credential` (Legate::Auth::Credential): The original credential
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The refreshed token
+
+**Examples:**
+
+```ruby
+# This method is called internally by the Legate
+# The implementation depends on the specific scheme
+```
+
+### `revoke_token`
+
+Revokes a token. This method must be implemented by concrete subclasses that support token revocation.
+
+**Parameters:**
+- `token` (Legate::Auth::ExchangedCredential): The token to revoke
+- `credential` (Legate::Auth::Credential): The original credential
+
+**Examples:**
+
+```ruby
+# This method is called internally by the Legate
+# The implementation depends on the specific scheme
+```
+
+### `validate!`
+
+Validates the scheme configuration. Raises an error if the configuration is invalid.
+
+**Raises:**
+- `Legate::Auth::SchemeValidationError`: If the scheme configuration is invalid
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://example.com/authorize',
+  token_url: 'https://example.com/token'
+)
+scheme.validate!  # Raises if configuration is incomplete
+```
+
+### `build_authorization_uri`
+
+Builds an authorization URI for interactive authentication flows. This method must be implemented by concrete subclasses that support interactive authentication.
+
+**Parameters:**
+- `config` (Legate::Auth::Config): The authentication configuration
+- `redirect_uri` (String, optional): The redirect URI for the authentication flow
+- `state` (String, optional): The state parameter for CSRF protection
+
+**Returns:**
+- String: The authorization URI
+
+**Examples:**
+
+```ruby
+# This method is called internally by the Legate
+# The implementation depends on the specific scheme
+```
+
+### `authentication_error?`
+
+Checks if an HTTP response indicates an authentication error.
+
+**Parameters:**
+- `response` (Object): The HTTP response to check
+
+**Returns:**
+- Boolean: `true` if the response indicates an authentication error
+
+**Examples:**
+
+```ruby
+# This method is called internally by the Legate
+# Used by ExconMiddleware to detect auth failures for retry
+```
+
+### `to_h`
+
+Converts the scheme to a hash representation.
+
+**Returns:**
+- Hash: A hash representation of the scheme
+
+### `to_s`
+
+Returns a string representation of the scheme.
+
+**Returns:**
+- String: A string representation of the scheme
+
+## Authentication Flow Types
+
+The `Scheme` class supports different types of authentication flows:
+
+1. **Non-Interactive Authentication**:
+   - Direct authentication using API keys or bearer tokens
+   - No user interaction required
+   - Implemented by schemes like `ApiKey` and `HTTPBearer`
+
+2. **Token-Based Authentication**:
+   - Uses tokens for authentication
+   - May include token exchange, refresh, and revocation
+   - Implemented by schemes like `OAuth2`, `OpenIDConnect`, and `ServiceAccount`
+
+3. **Interactive Authentication**:
+   - Requires user interaction to complete authentication
+   - Uses `build_authorization_uri` for generating the auth URI
+   - Implemented by schemes like `OAuth2` and `OpenIDConnect`
+
+## Concrete Implementations
+
+The Legate Ruby library includes the following concrete implementations of `Scheme`:
+
+- [Legate::Auth::Schemes::ApiKey](./schemes/api_key): For API key authentication
+- [Legate::Auth::Schemes::HTTPBearer](./schemes/http_bearer): For HTTP Bearer token authentication
+- [Legate::Auth::Schemes::OAuth2](./schemes/oauth2): For OAuth2 authentication
+- [Legate::Auth::Schemes::OpenIDConnect](./schemes/openid_connect): For OpenID Connect authentication
+- [Legate::Auth::Schemes::ServiceAccount](./schemes/service_account): For service account authentication
+
+## Extension Points
+
+To create a custom authentication scheme, extend the `Scheme` class and implement the required methods:
+
+```ruby
+class CustomScheme < Legate::Auth::Scheme
+  def scheme_type
+    :custom
+  end
+
+  def apply_to_request(request, credential)
+    request[:headers] ||= {}
+    request[:headers]['Authorization'] = "Custom #{credential[:access_token]}"
+    request
+  end
+
+  def exchange_token(credential)
+    Legate::Auth::ExchangedCredential.new(
+      auth_type: :custom,
+      access_token: credential[:custom_token]
+    )
+  end
+end
+```
+
+## See Also
+
+- [Legate::Auth::Credential](./credential)
+- [Legate::Auth::ExchangedCredential](./exchanged_credential)
+- [Legate::Auth::Config](./config)
+- [Legate::Auth::TokenManager](./token_manager)

data/public/docs/authentication/api_reference/schemes/api_key.md

@@ -0,0 +1,175 @@
+# Legate::Auth::Schemes::ApiKey
+
+The `ApiKey` class implements API key authentication, one of the simplest and most common methods for authenticating API requests. This scheme handles the inclusion of API keys in requests via headers, query parameters, or other methods.
+
+## Overview
+
+API key authentication is a straightforward authentication method where a single secret key is included in API requests. The API key scheme in Legate Ruby provides flexible options for configuring how and where the API key is included in requests.
+
+## Class Methods
+
+### `new`
+
+Creates a new API key authentication scheme. The constructor takes **no arguments** — the API key's location (`header`, `query`, or `cookie`) and parameter/header name are read from the **credential** at apply time (via its `location:` and `name:` attributes), not from the scheme.
+
+**Examples:**
+
+```ruby
+# Create an API key scheme (no constructor arguments)
+scheme = Legate::Auth::Schemes::ApiKey.new
+
+# Location and name live on the credential, not the scheme:
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'my-api-key',
+  location: 'header',      # 'header' (default), 'query', or 'cookie'
+  name: 'X-API-Key'        # header/parameter/cookie name (default: 'X-API-Key')
+)
+```
+
+## Instance Methods
+
+### `scheme_type`
+
+Returns the type of the authentication scheme.
+
+**Returns:**
+- Symbol: `:api_key`
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::ApiKey.new
+scheme.scheme_type  # => :api_key
+```
+
+### `apply_to_request`
+
+Applies API key authentication to a request by adding the API key to the appropriate location.
+
+**Parameters:**
+- `request` (Hash): The request to authenticate
+- `credential` (Legate::Auth::ExchangedCredential): The exchanged credential containing the API key
+
+**Returns:**
+- Hash: The authenticated request with the API key in the specified location
+
+**Examples:**
+
+```ruby
+# Create an API key credential and exchange it
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'my-api-key'
+)
+
+scheme = Legate::Auth::Schemes::ApiKey.new
+token = scheme.exchange_token(credential)
+
+# Apply to a request
+request = { headers: {} }
+authenticated = scheme.apply_to_request(request, token)
+```
+
+### `exchange_token`
+
+Exchanges a credential for an authentication token. For API keys, this simply wraps the API key in an ExchangedCredential.
+
+**Parameters:**
+- `credential` (Legate::Auth::Credential): The credential to exchange
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The exchanged token
+
+**Examples:**
+
+```ruby
+# Create an API key credential
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'my-api-key'
+)
+
+# Exchange for a token
+scheme = Legate::Auth::Schemes::ApiKey.new
+token = scheme.exchange_token(credential)
+
+# The exchanged credential stores the key under :api_key (not :access_token)
+puts token[:api_key]        # => "my-api-key"
+puts token[:access_token]   # => nil
+```
+
+### `to_h`
+
+Converts the scheme to a hash representation.
+
+**Returns:**
+- Hash: A hash representation of the scheme configuration
+
+## Usage Examples
+
+### Basic API Key Authentication
+
+```ruby
+# Create an API key scheme
+scheme = Legate::Auth::Schemes::ApiKey.new
+
+# Create a credential with the API key
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'my-api-key'
+)
+
+# Exchange for a token
+token = scheme.exchange_token(credential)
+
+# Apply to a request
+request = { headers: {} }
+authenticated = scheme.apply_to_request(request, token)
+```
+
+### With Token Manager
+
+```ruby
+# Create an API key scheme
+scheme = Legate::Auth::Schemes::ApiKey.new
+
+# Create a credential with the API key
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'my-api-key'
+)
+
+# Use with token manager
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+# Get a token (this will create and store the ExchangedCredential)
+token = token_manager.get_token(scheme, credential)
+```
+
+### With Environment Variables
+
+```ruby
+# Create a credential with the API key from an environment variable
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'ENV:API_KEY'
+)
+```
+
+## Security Considerations
+
+- API keys are essentially long-term passwords and should be protected accordingly
+- Always use HTTPS for all API requests that include API keys
+- Restrict API key permissions to only what's necessary
+- Implement proper access controls for API keys
+- Rotate API keys regularly
+- Consider using more advanced authentication schemes (OAuth2, OIDC) for sensitive operations
+
+## See Also
+
+- [Legate::Auth::Credential](../credential)
+- [Legate::Auth::ExchangedCredential](../exchanged_credential)
+- [Legate::Auth::Scheme](../scheme)
+- [Legate::Auth::TokenManager](../token_manager)

data/public/docs/authentication/api_reference/schemes/google_service_account.md

@@ -0,0 +1,221 @@
+# Legate::Auth::Schemes::GoogleServiceAccount
+
+The `GoogleServiceAccount` class implements Google-specific service account authentication. It extends the base `ServiceAccount` class with Google Cloud-specific functionality for authenticating with Google APIs.
+
+## Overview
+
+Google Service Account authentication uses a key-based approach where a signed JWT (JSON Web Token) is exchanged for an access token from Google's authentication servers. This scheme is specifically optimized for Google Cloud APIs, handling the proper audience, token URLs, and other Google-specific configuration details.
+
+## Class Methods
+
+### `new`
+
+Creates a new Google Service Account authentication scheme.
+
+**Parameters:**
+- `scopes` (Array<String>, optional): The Google API scopes to request access for
+- `kwargs` (Hash, optional): Additional parameters for the authentication scheme (inherits ServiceAccount params)
+
+**Examples:**
+
+```ruby
+# Basic Google Service Account scheme with scopes
+scheme = Legate::Auth::Schemes::GoogleServiceAccount.new(
+  scopes: ['https://www.googleapis.com/auth/cloud-platform']
+)
+
+# With additional options
+scheme = Legate::Auth::Schemes::GoogleServiceAccount.new(
+  scopes: [
+    'https://www.googleapis.com/auth/cloud-platform',
+    'https://www.googleapis.com/auth/bigquery'
+  ],
+  token_lifetime: 3600
+)
+```
+
+## Instance Methods
+
+### `scheme_type`
+
+Returns the type of the authentication scheme.
+
+**Returns:**
+- Symbol: `:google_service_account`
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::GoogleServiceAccount.new
+scheme.scheme_type  # => :google_service_account
+```
+
+### `validate!`
+
+Validates the scheme configuration for Google service account authentication.
+
+**Raises:**
+- `Legate::Auth::SchemeValidationError`: If the scheme configuration is invalid
+
+### `apply_to_request`
+
+Applies Google service account authentication to a request by adding the access token to the Authorization header.
+
+**Parameters:**
+- `request` (Hash): The request to authenticate
+- `credential` (Legate::Auth::ExchangedCredential): The exchanged credential containing the access token
+
+**Returns:**
+- Hash: The authenticated request with access token in the Authorization header
+
+**Examples:**
+
+```ruby
+request = { headers: {} }
+authenticated = scheme.apply_to_request(request, exchanged_credential)
+puts authenticated[:headers]['Authorization']  # => "Bearer [access-token]"
+```
+
+### `exchange_token`
+
+Exchanges a Google service account credential for an access token by creating and signing a JWT and exchanging it with Google's token endpoint.
+
+**Parameters:**
+- `credential` (Legate::Auth::Credential): The credential containing the service account information
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The exchanged token
+
+**Examples:**
+
+```ruby
+# Create a service account credential
+credential = Legate::Auth::Credential.new(
+  auth_type: :google_service_account,
+  service_account_key: File.read('google-service-account.json')  # raw JSON string, not a parsed Hash
+)
+
+# Exchange for a token
+scheme = Legate::Auth::Schemes::GoogleServiceAccount.new(
+  scopes: ['https://www.googleapis.com/auth/cloud-platform']
+)
+token = scheme.exchange_token(credential)
+
+puts token[:access_token]  # => "[google-access-token]"
+```
+
+### `refresh_token`
+
+Refreshes an expired Google service account token by performing a new token exchange.
+
+**Parameters:**
+- `token` (Legate::Auth::ExchangedCredential): The token to refresh
+- `credential` (Legate::Auth::Credential): The original credential
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The refreshed token
+
+**Examples:**
+
+```ruby
+refreshed_token = scheme.refresh_token(expired_token, credential)
+```
+
+## Usage Examples
+
+### Basic Authentication Flow
+
+```ruby
+# Create a Google Service Account scheme
+scheme = Legate::Auth::Schemes::GoogleServiceAccount.new(
+  scopes: [
+    'https://www.googleapis.com/auth/cloud-platform',
+    'https://www.googleapis.com/auth/bigquery'
+  ]
+)
+
+# Create a credential from a service account key file
+credential = Legate::Auth::Credential.new(
+  auth_type: :google_service_account,
+  service_account_key: File.read('google-service-account.json')  # raw JSON string, not a parsed Hash
+)
+
+# Exchange the credential for a token
+token = scheme.exchange_token(credential)
+
+# Apply to a request
+request = { headers: {} }
+authenticated = scheme.apply_to_request(request, token)
+puts authenticated[:headers]['Authorization']  # => "Bearer [access-token]"
+```
+
+### With Token Manager
+
+```ruby
+# Create a Google Service Account scheme
+scheme = Legate::Auth::Schemes::GoogleServiceAccount.new(
+  scopes: ['https://www.googleapis.com/auth/cloud-platform']
+)
+
+# Create a credential from a service account key file
+credential = Legate::Auth::Credential.new(
+  auth_type: :google_service_account,
+  service_account_key: File.read('google-service-account.json')  # raw JSON string, not a parsed Hash
+)
+
+# Use with token manager for automatic token management
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+# Get a token (this will create, store, and refresh the token as needed)
+token = token_manager.get_token(scheme, credential)
+```
+
+### Using a Key File from Path
+
+```ruby
+# Point the credential at a service account key file on disk
+credential = Legate::Auth::Credential.new(
+  auth_type: :google_service_account,
+  service_account_key_file: '/path/to/google-service-account.json'
+)
+
+# Create the scheme and use as normal
+scheme = Legate::Auth::Schemes::GoogleServiceAccount.new(
+  scopes: ['https://www.googleapis.com/auth/cloud-platform']
+)
+
+# Exchange for a token
+token = scheme.exchange_token(credential)
+```
+
+> **Note:** Application Default Credentials (ADC) are not supported. Provide credentials explicitly via `service_account_key` (a raw JSON string) or `service_account_key_file` (a path).
+
+## Google API Scopes
+
+Common Google API scopes include:
+
+| API | Scope |
+|-----|-------|
+| Google Cloud Platform (all services) | `https://www.googleapis.com/auth/cloud-platform` |
+| BigQuery | `https://www.googleapis.com/auth/bigquery` |
+| Cloud Storage | `https://www.googleapis.com/auth/devstorage.read_write` |
+| Compute Engine | `https://www.googleapis.com/auth/compute` |
+| Google Drive | `https://www.googleapis.com/auth/drive` |
+| Gmail | `https://www.googleapis.com/auth/gmail.send` |
+| Google Sheets | `https://www.googleapis.com/auth/spreadsheets` |
+
+## Security Considerations
+
+- Store service account keys securely and restrict access
+- Grant service accounts the minimum necessary permissions
+- Regularly rotate service account keys (Google recommends every 90 days)
+- Monitor service account usage for suspicious activity
+- Consider using IAM Conditions to restrict service account usage based on source IP, time, etc.
+
+## See Also
+
+- [Legate::Auth::Schemes::ServiceAccount](./service_account)
+- [Legate::Auth::Credential](../credential)
+- [Legate::Auth::ExchangedCredential](../exchanged_credential)
+- [Legate::Auth::TokenManager](../token_manager)