legate 0.1.0

data/public/docs/authentication/guides/api_key.md

@@ -0,0 +1,190 @@
+# API Key Authentication
+
+API Keys are one of the simplest forms of authentication, commonly used for server-to-server API access. The Legate Ruby library provides comprehensive support for API Key authentication in various formats.
+
+## Overview
+
+API Key authentication works by including a key in the request, typically in one of three locations:
+
+- **Header**: The API key is added as an HTTP header (most common)
+- **Query Parameter**: The API key is added to the URL query string
+- **Cookie**: The API key is included in a cookie
+
+## Basic Setup
+
+### Session Service and Token Store
+
+For enhanced functionality and token management, you can set up a session service and token store:
+
+```ruby
+# Create session service for token storage
+session_service = Legate::SessionService::InMemory.new
+
+# Create a basic token store for caching
+token_store = Legate::Auth::TokenStore.new(session_service)
+```
+
+### Creating an API Key Scheme
+
+```ruby
+# Create an API Key scheme
+scheme = Legate::Auth::Schemes::ApiKey.new
+```
+
+### Creating an API Key Credential
+
+```ruby
+# Direct API key value
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'your-api-key-value'
+)
+
+# API key from environment variable (recommended for security)
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: ENV['API_KEY']
+)
+
+# With custom location and name (e.g., for query parameter)
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: ENV['API_KEY'],
+  location: 'query',          # Options: 'header', 'query', 'cookie'
+  name: 'api_key'            # Parameter name in the chosen location
+)
+```
+
+## Usage Examples
+
+### Connection Helper Approach
+
+The most straightforward way to apply API key authentication is via the
+connection helper, which attaches the key to every request:
+
+```ruby
+# Create a credential with the API key
+scheme = Legate::Auth::Schemes::ApiKey.new
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: ENV['API_KEY'],
+  location: 'query',
+  name: 'api_key'
+)
+
+# Build an authenticated connection; the API key is applied automatically
+connection = Legate::Auth.create_connection('https://api.example.com',
+  scheme: scheme,
+  credential: credential
+)
+response = connection.get(path: '/api/endpoint')
+```
+
+Inside a tool, do the same within `perform_execution(params, context)` (see
+[`ToolContextExtension`](../api_reference/tool_context_extension)).
+
+### Middleware Approach
+
+For more direct HTTP client usage, you can use the Legate Auth middleware:
+
+```ruby
+# Create a connection with API key middleware
+connection = Legate::Auth.create_api_key_connection(
+  'https://api.example.com',
+  api_key: ENV['API_KEY'],
+  location: 'query',
+  name: 'api_key',
+  token_store: token_store  # Optional
+)
+
+# Make requests through the middleware
+response = connection.request(
+  method: :get,
+  path: '/api/endpoint',
+  query: { param: 'value' }
+)
+```
+
+### Manual Authentication Application
+
+For cases where you need more control, you can manually apply authentication:
+
+```ruby
+# Create a request hash
+request = {
+  method: :get,
+  path: '/api/endpoint',
+  query: { param: 'value' },
+  headers: {}
+}
+
+# Apply authentication manually
+request_with_auth = Legate::Auth::ToolIntegration.apply_authentication(
+  request,
+  scheme,
+  credential,
+  token_store  # Optional
+)
+
+# Use the authenticated request with your HTTP client
+connection = Excon.new('https://api.example.com')
+response = connection.request(request_with_auth)
+```
+
+### Direct HTTP Client Usage
+
+For the simplest cases, you can directly include the API key:
+
+```ruby
+# Create connection
+connection = Excon.new('https://api.example.com')
+
+# Include API key in query parameters
+response = connection.request(
+  method: :get,
+  path: '/api/endpoint',
+  query: {
+    api_key: ENV['API_KEY'],
+    param: 'value'
+  }
+)
+```
+
+## API Key Security Best Practices
+
+1. **Environment Variables**: Store API keys in environment variables
+2. **Token Store**: Use token store for caching and management when appropriate
+3. **Secure Transport**: Always use HTTPS for API requests
+4. **Key Rotation**: Update API keys periodically
+5. **Minimal Permissions**: Use keys with the minimum required access
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Failure**: Verify the API key location and name match the API requirements
+2. **Token Store Issues**: Ensure session service is properly initialized
+3. **Middleware Configuration**: Check connection parameters when using `create_api_key_connection`
+
+### Debugging Tips
+
+```ruby
+# Debug authentication application
+request = { headers: {}, query: {} }
+modified_request = scheme.apply_to_request(request, credential)
+puts "Modified request: #{modified_request.inspect}"
+
+# For verbose auth logging, run with LEGATE_LOG_LEVEL=DEBUG
+connection = Legate::Auth.create_api_key_connection(
+  'https://api.example.com',
+  api_key: ENV['API_KEY'],
+  location: 'query',
+  name: 'api_key'
+)
+```
+
+## Next Steps
+
+- [Authentication Overview](./overview): Return to the overview of authentication
+- [HTTP Bearer Authentication](./bearer): Learn about Bearer token authentication
+- [OAuth2 Authentication](./oauth2): Implement OAuth2 authentication flows 

data/public/docs/authentication/guides/bearer.md

@@ -0,0 +1,172 @@
+# HTTP Bearer Authentication
+
+## Overview
+
+HTTP Bearer authentication is a simple and widely used authentication scheme that involves sending a token, typically a JWT (JSON Web Token), in the `Authorization` header of HTTP requests. The Legate Ruby library provides built-in support for this authentication scheme through the `Legate::Auth::Schemes::HTTPBearer` class.
+
+## Key Concepts
+
+- **Bearer Token**: A security token that grants access to protected resources, which the bearer can use without proving possession of a cryptographic key
+- **Authorization Header**: HTTP header used to send the bearer token in the format `Authorization: Bearer <token>`
+- **Token Types**: Commonly a JWT, but can be any opaque string accepted by the API
+
+## Setting Up Bearer Authentication
+
+### Step 1: Create the Authentication Scheme
+
+```ruby
+# Create an HTTP Bearer scheme
+bearer_scheme = Legate::Auth::Schemes::HTTPBearer.new
+```
+
+### Step 2: Create the Credential
+
+```ruby
+# Option 1: Directly provide the token
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: 'your_bearer_token_here'
+)
+
+# Option 2: Read the token from an environment variable at runtime
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: ENV['API_BEARER_TOKEN']
+)
+
+# Option 3: Reference an environment variable with the ENV: prefix (resolved lazily)
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: 'ENV:API_BEARER_TOKEN'
+)
+```
+
+### Step 3: Attach Bearer Authentication to a Connection
+
+```ruby
+# Create an authenticated Excon connection using the helper
+connection = Legate::Auth.create_connection('https://api.example.com',
+  scheme: bearer_scheme,
+  credential: credential
+)
+
+# The Authorization header is applied automatically
+response = connection.get(path: '/protected-resource')
+```
+
+## Using Bearer Authentication in API Requests
+
+### Reading the token from a credential
+
+You can read the bearer token from a credential using the `[]` accessor
+(which resolves `ENV:` references):
+
+```ruby
+bearer_token = credential[:bearer_token]
+
+conn = Excon.new('https://api.example.com')
+response = conn.get(
+  path: '/protected-resource',
+  headers: { 'Authorization' => "Bearer #{bearer_token}" }
+)
+
+JSON.parse(response.body)
+```
+
+### Using the Excon Middleware
+
+You can also build the middleware explicitly and attach it via the connection helper:
+
+```ruby
+# Create middleware for Bearer authentication
+middleware = Legate::Auth.create_middleware(
+  scheme: bearer_scheme,
+  credential: credential
+)
+# (create_middleware returns a configured ExconMiddleware instance; the
+# connection helpers below wire it onto a connection for you.)
+```
+
+Or use the connection helper directly:
+
+```ruby
+# Create an authenticated connection directly
+connection = Legate::Auth.create_connection(
+  'https://api.example.com',
+  scheme: bearer_scheme,
+  credential: credential
+)
+
+# Make authenticated requests
+response = connection.get(path: '/protected-resource')
+```
+
+## Token Management
+
+Unlike OAuth2 or OIDC, HTTP Bearer authentication does not include built-in token refresh mechanisms. If your bearer token expires, you will need to obtain a new one externally and update your credential:
+
+```ruby
+# Update the bearer token on the credential
+credential[:bearer_token] = new_token
+
+# Or, if you reference it via 'ENV:API_BEARER_TOKEN', update the env var
+ENV['API_BEARER_TOKEN'] = new_token
+```
+
+## Security Considerations
+
+- Bearer tokens should be treated as sensitive information, similar to passwords
+- Use HTTPS for all requests to prevent token interception
+- Store tokens securely, preferably in environment variables rather than in code
+- Use short-lived tokens where possible to minimize risk of token compromise
+- Consider using OAuth2 or OIDC if you need more advanced features like token refresh and revocation
+
+## Complete Example
+
+Here's a complete example of using Bearer authentication with the Legate:
+
+```ruby
+require 'legate'
+require 'excon'
+
+# Create the scheme and credential
+bearer_scheme = Legate::Auth::Schemes::HTTPBearer.new
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: 'ENV:API_BEARER_TOKEN'
+)
+
+# Create a custom tool
+class UserProfileTool < Legate::Tool
+  tool_description 'Gets the current user profile'
+
+  def perform_execution(params, context)
+    # Create an authenticated connection
+    bearer_scheme = Legate::Auth::Schemes::HTTPBearer.new
+    credential = Legate::Auth::Credential.new(
+      auth_type: :http_bearer,
+      bearer_token: 'ENV:API_BEARER_TOKEN'
+    )
+
+    connection = Legate::Auth.create_connection(
+      'https://api.example.com',
+      scheme: bearer_scheme,
+      credential: credential
+    )
+
+    # Make the authenticated request
+    response = connection.get(path: '/user/profile')
+
+    # Check for authentication errors
+    if response.status == 401
+      { status: :error, error_message: 'Authentication failed. Bearer token may be invalid or expired.' }
+    else
+      { status: :success, result: JSON.parse(response.body) }
+    end
+  end
+end
+```
+
+## Related Topics
+- [Legate::Auth::Schemes::HTTPBearer API Reference](../api_reference/schemes/http_bearer)
+- [Excon Middleware for Authentication](../api_reference/excon_middleware) 

data/public/docs/authentication/guides/configuration.md

@@ -0,0 +1,255 @@
+# Authentication Configuration
+
+## Overview
+
+This guide explains how to configure authentication in your Legate Ruby applications. Proper configuration is essential for successfully authenticating with external APIs and services.
+
+## Configuration Components
+
+Authentication in the Legate Ruby library involves configuring three main components:
+
+1. **Authentication Scheme**: Defines how the API expects authentication (API Key, OAuth2, etc.)
+2. **Authentication Credential**: Contains the initial information needed for authentication
+3. **Tool Configuration**: Associates schemes and credentials with tools
+
+## Authentication Schemes
+
+Authentication schemes define the protocol and parameters for authenticating with an API.
+
+### Available Schemes
+
+```ruby
+# API Key scheme (no constructor arguments — the key's location and name
+# come from the credential at apply time)
+api_key_scheme = Legate::Auth::Schemes::ApiKey.new
+
+# HTTP Bearer scheme
+bearer_scheme = Legate::Auth::Schemes::HTTPBearer.new
+
+# OAuth2 scheme
+oauth2_scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://auth.example.com/authorize',
+  token_url: 'https://auth.example.com/token',
+  scopes: ['read', 'write']
+)
+
+# OpenID Connect scheme
+oidc_scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  discovery_url: 'https://auth.example.com/.well-known/openid-configuration',
+  scopes: ['openid', 'profile', 'email']
+)
+
+# Service Account scheme
+service_account_scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://auth.example.com/token'
+)
+
+# Google Service Account scheme
+google_service_account_scheme = Legate::Auth::Schemes::GoogleServiceAccount.new(
+  scopes: ['https://www.googleapis.com/auth/drive']
+)
+```
+
+### Scheme Properties
+
+Each scheme type has different configuration properties:
+
+#### ApiKey Scheme
+
+`ApiKey.new` takes **no constructor arguments**. The API key's location and name are read from the **credential** at apply time:
+
+| Credential attribute | Description | Default |
+|----------------------|-------------|---------|
+| `location` | Location of the API key (`'header'`, `'query'`, `'cookie'`) | `'header'` |
+| `name` | Header/parameter/cookie name | `'X-API-Key'` |
+
+#### HTTPBearer Scheme
+
+The HTTPBearer scheme doesn't require any additional configuration properties.
+
+#### OAuth2 Scheme (constructor keyword arguments)
+
+| Argument | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `authorization_url` | Authorization endpoint URL | None | Yes (for interactive flows) |
+| `token_url` | Token endpoint URL | None | Yes |
+| `scopes` | List/space-string of OAuth2 scopes | [] | No |
+| `use_pkce` | Whether to use PKCE | `true` | No |
+| `additional_params` | Extra params for the authorization request | None | No |
+| `revocation_url` | Token revocation endpoint URL | None | No |
+
+#### OpenIDConnect Scheme (constructor keyword arguments)
+
+Inherits all OAuth2 arguments, plus:
+
+| Argument | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `discovery_url` | OIDC discovery document URL | None | No (if endpoints given) |
+| `jwks_url` | JSON Web Key Set URL | None | No |
+| `userinfo_url` | UserInfo endpoint URL | None | No |
+| `issuer` | Expected issuer | None | No |
+
+#### ServiceAccount Scheme (constructor keyword arguments)
+
+| Argument | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `token_url` | Token endpoint URL | None | Yes |
+| `audience` | Service account token audience | None | No |
+| `scopes` | Requested scopes | [] | No |
+| `token_lifetime` | JWT lifetime in seconds | 3600 | No |
+
+#### GoogleServiceAccount Scheme (constructor keyword arguments)
+
+| Argument | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `scopes` | List of Google API scopes | None | No |
+| `token_url` | Token endpoint URL | 'https://oauth2.googleapis.com/token' | No |
+| `audience` | Service account token audience | token_url | No |
+| `token_lifetime` | JWT lifetime in seconds | 3600 | No |
+
+## Authentication Credentials
+
+Authentication credentials contain the initial information needed to start authentication.
+
+### Creating Credentials
+
+Every credential requires an `auth_type:`.
+
+```ruby
+# API Key credential
+api_key_credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: ENV['API_KEY']
+)
+
+# HTTP Bearer credential
+bearer_credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: ENV['BEARER_TOKEN']
+)
+
+# OAuth2 credential
+oauth2_credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: ENV['OAUTH2_CLIENT_ID'],
+  client_secret: ENV['OAUTH2_CLIENT_SECRET']
+)
+
+# Service Account credential (service_account_key is a raw JSON string)
+service_account_credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('service-account.json')
+)
+
+# Google Service Account credential
+google_service_account_credential = Legate::Auth::Credential.new(
+  auth_type: :google_service_account,
+  service_account_key: ENV['GOOGLE_SERVICE_ACCOUNT_JSON']  # raw JSON string
+)
+```
+
+### Environment Variable References
+
+The only mechanism for referencing environment variables is the `ENV:` prefix
+inside a string value. There are no `*_env` attributes.
+
+```ruby
+# Reference environment variables with the ENV: prefix
+oauth2_credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: 'ENV:OAUTH2_CLIENT_ID',
+  client_secret: 'ENV:OAUTH2_CLIENT_SECRET'
+)
+```
+
+### Common Credential Properties
+
+| Property | Description | Used With |
+|----------|-------------|-----------|
+| `auth_type` | Required: `:api_key`, `:http_bearer`, `:oauth2`, `:oidc`, `:service_account`, `:google_service_account`, `:basic` | All |
+| `api_key` | The API key value (use `'ENV:NAME'` to read from the environment) | API Key scheme |
+| `location` | API key location: `'header'`, `'query'`, or `'cookie'` | API Key scheme |
+| `name` | API key header/parameter/cookie name | API Key scheme |
+| `bearer_token` | The bearer token value | Bearer scheme |
+| `client_id` | OAuth2/OIDC client ID | OAuth2, OIDC schemes |
+| `client_secret` | OAuth2/OIDC client secret | OAuth2, OIDC schemes |
+| `service_account_key` | Service account JSON as a raw string (use `'ENV:NAME'` to read from the environment) | Service Account schemes |
+| `service_account_key_file` | Path to a file containing the service account JSON | Service Account schemes |
+
+## Using Authentication in Tools
+
+Within a `Legate::Tool`, use the authentication helpers added to the
+`ToolContext` (see [`ToolContextExtension`](../api_reference/tool_context_extension)):
+
+```ruby
+class MyApiTool < Legate::Tool
+  tool_description 'A tool that interacts with an authenticated API'
+
+  def perform_execution(params, context)
+    context.with_authentication do
+      connection = Legate::Auth.create_connection('https://api.example.com',
+        scheme: oauth2_scheme,
+        credential: oauth2_credential
+      )
+      response = connection.get(path: '/resource')
+      { status: :success, result: response.body }
+    end
+  end
+end
+```
+
+## Advanced Configuration
+
+### Token Store Configuration
+
+Configure the token store and manager (both take **positional** arguments):
+
+```ruby
+# Create a token store (positional session service)
+token_store = Legate::Auth::TokenStore.new(session_service)
+
+# Configure a token manager with the token store. Config is a positional Hash;
+# the key is refresh_buffer (seconds before expiry to refresh), not refresh_threshold.
+token_manager = Legate::Auth::TokenManager.new(token_store, {
+  refresh_buffer: 300 # Refresh tokens 5 minutes before expiration
+})
+```
+
+### HTTP Client Configuration
+
+The simplest way to attach authentication to an Excon connection is the
+connection helper, which wires up the middleware for you:
+
+```ruby
+# Create an authenticated connection directly
+connection = Legate::Auth.create_connection(
+  'https://api.example.com',
+  scheme: oauth2_scheme,
+  credential: oauth2_credential,
+  token_store: token_store,
+  max_retries: 3,
+  backoff_strategy: :exponential
+)
+```
+
+`Legate::Auth.create_middleware(scheme:, credential:, ...)` is also available
+if you need to build the middleware instance yourself.
+
+## Configuration Best Practices
+
+1. **Use Environment Variables for Sensitive Values**: Always use environment variables for sensitive credentials like API keys, client secrets, and tokens
+2. **Validate Configuration**: Verify your authentication configuration before making API requests
+3. **Use HTTPS**: Always use HTTPS URLs for authentication endpoints
+4. **Limit Scopes**: Request only the scopes your application needs
+5. **Secure Storage**: Tokens are cached as plaintext in scoped state; apply the opt-in `Legate::Auth::Encryption` module yourself if you need at-rest encryption
+6. **Token Lifecycle**: Configure an appropriate `refresh_buffer` on the `TokenManager`
+7. **Error Handling**: Implement proper error handling for authentication failures
+
+## Related Topics
+- [API Key Authentication](./api_key)
+- [HTTP Bearer Authentication](./bearer)
+- [OAuth2 Authentication](./oauth2)
+- [OpenID Connect](./oidc)
+- [Service Account Authentication](./service_account)
+- [Token Lifecycle Management](./token_lifecycle)
+- [Secure Credential Storage](./secure_storage)