legate 0.1.0

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

@@ -0,0 +1,218 @@
+# Encryption Utilities
+
+## Overview
+
+The `Legate::Auth::Encryption` module provides utilities for securely encrypting sensitive authentication data, such as access tokens and refresh tokens. It provides class-level methods for encryption and decryption operations.
+
+Encryption is **opt-in**: it is not wired into `TokenStore` automatically (see [Integration with TokenStore](#integration-with-tokenstore) below). The module uses the [rbnacl](https://github.com/RubyCrypto/rbnacl) gem (libsodium SecretBox) for authenticated encryption. `rbnacl` is an **optional/development dependency** — the encryption methods lazily `require 'rbnacl'` and raise `LoadError` if it (or libsodium) is not installed. Add `gem 'rbnacl'` to your Gemfile and ensure libsodium is available to use this module.
+
+## Module Definition
+
+```ruby
+module Legate
+  module Auth
+    module Encryption
+      class << self
+        # Encryption class methods
+      end
+    end
+  end
+end
+```
+
+## Key Features
+
+- Secure encryption of sensitive authentication data
+- Authenticated encryption to prevent tampering
+- Base64 encoding for safe storage and transmission
+- Simple class-level interface for encryption and decryption
+- Key generation utility
+- Detection of already-encrypted data
+
+## Class Methods
+
+### `encrypt`
+
+Encrypts the provided data.
+
+**Parameters:**
+- `data` (String): The data to encrypt (coerced to a string)
+- `key` (String, optional): The Base64-encoded encryption key. When omitted (`nil`), the key is read from the `LEGATE_AUTH_ENCRYPTION_KEY` environment variable.
+
+**Returns:**
+- String: The encrypted data, prefixed with the `LGTAUTH` header followed by Base64-encoded ciphertext
+
+**Raises:**
+- `LoadError`: If the `rbnacl` gem is not available
+- `ArgumentError`: If no key is supplied and `LEGATE_AUTH_ENCRYPTION_KEY` is unset, or the key is not valid Base64
+
+**Examples:**
+
+```ruby
+# Encrypt using the key from LEGATE_AUTH_ENCRYPTION_KEY
+encrypted = Legate::Auth::Encryption.encrypt(sensitive_data)
+
+# Encrypt data with a specific (Base64-encoded) key
+encrypted = Legate::Auth::Encryption.encrypt(sensitive_data, my_key)
+```
+
+> There is no built-in default key. If neither an explicit key nor `LEGATE_AUTH_ENCRYPTION_KEY` is provided, an `ArgumentError` is raised.
+
+### `decrypt`
+
+Decrypts previously encrypted data.
+
+**Parameters:**
+- `encrypted_data` (String): The encrypted data (the `LGTAUTH`-prefixed string returned by `encrypt`)
+- `key` (String, optional): The Base64-encoded encryption key. When omitted (`nil`), the key is read from `LEGATE_AUTH_ENCRYPTION_KEY`.
+
+**Returns:**
+- String: The decrypted data
+
+**Raises:**
+- `LoadError`: If the `rbnacl` gem is not available
+- `ArgumentError`: If the data is not in the expected format, the key is missing/invalid, or decryption fails
+
+**Examples:**
+
+```ruby
+# Decrypt using the key from LEGATE_AUTH_ENCRYPTION_KEY
+decrypted = Legate::Auth::Encryption.decrypt(encrypted_data)
+
+# Decrypt data with a specific (Base64-encoded) key
+decrypted = Legate::Auth::Encryption.decrypt(encrypted_data, my_key)
+```
+
+### `generate_key`
+
+Generates a new random encryption key, suitable for use as the `key` argument or `LEGATE_AUTH_ENCRYPTION_KEY`.
+
+**Returns:**
+- String: A new random key, Base64-encoded
+
+**Raises:**
+- `LoadError`: If the `rbnacl` gem is not available
+
+**Examples:**
+
+```ruby
+key = Legate::Auth::Encryption.generate_key
+# => Base64-encoded string, e.g. "k7Qz...=="
+```
+
+### `encrypted?`
+
+Checks if the provided data appears to be encrypted.
+
+**Parameters:**
+- `data` (Object): The data to check
+
+**Returns:**
+- Boolean: `true` if the data appears to be encrypted
+
+**Examples:**
+
+```ruby
+if Legate::Auth::Encryption.encrypted?(data)
+  # Data is already encrypted
+else
+  # Data needs to be encrypted
+end
+```
+
+## Usage Examples
+
+### Encrypting Authentication Tokens
+
+```ruby
+# Encrypt authentication tokens
+tokens = {
+  access_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+  refresh_token: 'rtok_abc123...',
+  expires_at: Time.now.to_i + 3600
+}
+
+encrypted_tokens = Legate::Auth::Encryption.encrypt(tokens.to_json)
+```
+
+### Decrypting Authentication Tokens
+
+```ruby
+# Decrypt authentication tokens
+decrypted_json = Legate::Auth::Encryption.decrypt(encrypted_tokens)
+decrypted_tokens = JSON.parse(decrypted_json, symbolize_names: true)
+
+access_token = decrypted_tokens[:access_token]
+refresh_token = decrypted_tokens[:refresh_token]
+```
+
+### Using a Custom Key
+
+```ruby
+# Generate a key
+key = Legate::Auth::Encryption.generate_key
+
+# Encrypt with the key
+encrypted = Legate::Auth::Encryption.encrypt(data, key)
+
+# Decrypt with the same key
+decrypted = Legate::Auth::Encryption.decrypt(encrypted, key)
+```
+
+## Integration with TokenStore
+
+> **Note:** `Encryption` is **not** wired into `TokenStore`. `TokenStore#store` persists the plaintext result of `token.to_h` into scoped session state, and `TokenStore#get` reads it back as-is. There is no transparent encryption layer.
+
+If you need at-rest encryption, apply the `Encryption` module yourself — for example, encrypt the serialized token before persisting it through your own storage layer, and decrypt on read:
+
+```ruby
+# Opt-in: encrypt the serialized token yourself before persisting
+require 'json'
+
+key = ENV['LEGATE_AUTH_ENCRYPTION_KEY'] # or Legate::Auth::Encryption.generate_key
+ciphertext = Legate::Auth::Encryption.encrypt(token.to_h.to_json, key)
+# ...persist `ciphertext` wherever you control storage...
+
+# On read:
+plaintext = Legate::Auth::Encryption.decrypt(ciphertext, key)
+token = Legate::Auth::ExchangedCredential.from_h(JSON.parse(plaintext, symbolize_names: true))
+```
+
+## Key Management
+
+Best practices for key management include:
+
+1. **Environment Variables**: Store the Base64-encoded key in `LEGATE_AUTH_ENCRYPTION_KEY`
+2. **Secrets Manager**: Use a secrets manager to securely store and retrieve the key
+3. **Key Rotation**: Implement a key rotation strategy for enhanced security
+4. **Consistent Key**: Ensure the same key is used for encryption and decryption
+
+## Security Considerations
+
+- **Key Security**: Protect the encryption key and never hard-code it
+- **Secure Key Generation**: Use `generate_key` for cryptographically secure keys
+- **Token TTL**: Implement a time-to-live (TTL) for tokens to limit exposure
+- **Memory Handling**: Clear sensitive data from memory after use when possible
+
+## Error Handling
+
+Decryption failures (bad format, wrong key, tampered data) raise `ArgumentError`. A missing `rbnacl` gem raises `LoadError`. There is no dedicated `EncryptionError` class.
+
+```ruby
+begin
+  decrypted_data = Legate::Auth::Encryption.decrypt(encrypted_data)
+rescue LoadError => e
+  # rbnacl / libsodium not installed
+  log.error("Encryption unavailable: #{e.message}")
+  nil
+rescue ArgumentError => e
+  # Decryption failed: invalid format, key, or tampered data
+  log.error("Decryption failed: #{e.message}")
+  nil
+end
+```
+
+## Related Classes
+
+- [`Legate::Auth::TokenStore`](./token_store): Secure storage for authentication tokens
+- [`Legate::Auth::TokenManager`](./token_manager): Token lifecycle management

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

@@ -0,0 +1,271 @@
+# Legate::Auth::ExchangedCredential
+
+The `ExchangedCredential` class represents authentication tokens obtained through credential exchange (e.g., OAuth2 access tokens, service account tokens). It provides a consistent interface for handling different types of tokens and their associated metadata.
+
+## Overview
+
+After authenticating with an authentication scheme, a credential is exchanged for a token. The `ExchangedCredential` class encapsulates this token along with additional information like token type, expiration time, and refresh tokens.
+
+## Class Methods
+
+### `new`
+
+Creates a new exchanged credential (token) instance.
+
+**Parameters:**
+- `auth_type` (Symbol, required keyword): The type of authentication (e.g., `:oauth2`, `:service_account`)
+- `access_token` (String, required keyword): The access token
+- `refresh_token` (String, optional keyword): The refresh token (default: nil)
+- `token_type` (String, optional keyword): The type of token (default: 'Bearer')
+- `expires_in` (Integer, optional keyword): Seconds until expiration (default: nil)
+- `id_token` (String, optional keyword): The ID token for OIDC flows (default: nil)
+- `provider_id` (String, optional keyword): The provider identifier (default: nil)
+- `**attributes` (Hash): Additional attributes specific to the token type
+
+**Examples:**
+
+```ruby
+# Create an OAuth2 token
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'your-access-token',
+  refresh_token: 'your-refresh-token',
+  expires_in: 3600,
+  token_type: 'Bearer'
+)
+
+# Create a service account token
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :service_account,
+  access_token: 'your-access-token',
+  expires_in: 3600
+)
+
+# Create an OIDC token with id_token
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'your-access-token',
+  refresh_token: 'your-refresh-token',
+  id_token: 'jwt-id-token',
+  expires_in: 3600
+)
+```
+
+### `from_h`
+
+Creates an ExchangedCredential from a hash representation.
+
+**Parameters:**
+- `hash` (Hash): The hash to create the credential from
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: A new ExchangedCredential instance
+
+**Examples:**
+
+```ruby
+token = Legate::Auth::ExchangedCredential.from_h(saved_token_hash)
+```
+
+## Instance Methods
+
+### `[]` (accessor)
+
+Gets an attribute from the token.
+
+**Parameters:**
+- `name` (Symbol, String): The attribute name
+
+**Returns:**
+- Object: The attribute value, or nil if not present
+
+**Examples:**
+
+```ruby
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'your-access-token',
+  refresh_token: 'your-refresh-token'
+)
+
+access_token = token[:access_token]
+refresh_token = token[:refresh_token]
+```
+
+### `to_h`
+
+Converts the token to a hash.
+
+**Returns:**
+- Hash: A hash representation of the token
+
+**Examples:**
+
+```ruby
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'your-access-token',
+  refresh_token: 'your-refresh-token',
+  expires_in: 3600
+)
+
+token_hash = token.to_h
+# => {auth_type: :oauth2, access_token: "your-access-token", refresh_token: "your-refresh-token", ...}
+```
+
+### `with`
+
+Returns a new ExchangedCredential with updated attributes.
+
+**Parameters:**
+- `attrs` (Hash): The attributes to update
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: A new instance with the updated attributes
+
+**Examples:**
+
+```ruby
+new_token = token.with(access_token: 'new-access-token', expires_in: 7200)
+```
+
+### `expired?`
+
+Checks if the token is expired.
+
+**Parameters:**
+- `buffer_seconds` (Integer, optional): Buffer time in seconds before actual expiration (default: 30)
+
+**Returns:**
+- Boolean: `true` if the token is expired or will expire within the buffer time
+
+**Examples:**
+
+```ruby
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'your-access-token',
+  expires_in: 3600
+)
+
+# Check if expired (with default 30-second buffer)
+puts token.expired?
+# => false
+
+# Check if expires within the next 5 minutes
+puts token.expired?(300)
+# => false (if more than 5 minutes remaining)
+```
+
+### `refreshable?`
+
+Checks if the token can be refreshed (i.e., has a refresh token).
+
+**Returns:**
+- Boolean: `true` if the token has a refresh token and can be refreshed
+
+**Examples:**
+
+```ruby
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'your-access-token',
+  refresh_token: 'your-refresh-token'
+)
+
+puts token.refreshable?
+# => true
+
+token_without_refresh = Legate::Auth::ExchangedCredential.new(
+  auth_type: :api_key,
+  access_token: 'your-api-key'
+)
+
+puts token_without_refresh.refreshable?
+# => false
+```
+
+### `id_token_claims`
+
+Decodes and returns the claims from the ID token (for OIDC tokens).
+
+**Returns:**
+- Hash: The decoded ID token claims, or nil if no ID token is present
+
+**Examples:**
+
+```ruby
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'your-access-token',
+  id_token: 'jwt-id-token'
+)
+
+claims = token.id_token_claims
+puts claims['sub']    # => "user-id"
+puts claims['email']  # => "user@example.com"
+```
+
+## Common Token Attributes
+
+Different token types have different attributes, but some common ones include:
+
+| Attribute | Description | Token Types |
+|-----------|-------------|------------|
+| `access_token` | The access token used for authentication | All |
+| `refresh_token` | Token used to refresh the access token | OAuth2, OIDC |
+| `id_token` | JWT token containing user identity | OIDC |
+| `expires_in` | Seconds until the token expires | OAuth2, OIDC, Service Account |
+| `token_type` | Type of token (default: 'Bearer') | OAuth2, OIDC |
+| `provider_id` | The provider identifier | Any |
+
+## Working with Token Expiration
+
+Managing token expiration is a common task:
+
+```ruby
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'your-access-token',
+  expires_in: 3600
+)
+
+# Check if expired (30-second buffer by default)
+if token.expired?
+  # Token needs to be refreshed
+else
+  # Token is still valid
+end
+
+# Check if expiring soon (within 5 minutes)
+if token.expired?(300)
+  # Token will expire soon, consider refreshing
+end
+```
+
+## Secure Token Storage
+
+ExchangedCredential objects contain sensitive information and should be handled securely:
+
+1. Never log the full token
+2. Store tokens securely — note that `TokenStore` does not encrypt them; apply the opt-in [`Legate::Auth::Encryption`](./encryption) module yourself if at-rest encryption is required
+3. Implement proper token lifecycle management
+
+```ruby
+# Example of secure logging
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'your-access-token',
+  refresh_token: 'your-refresh-token'
+)
+
+# Log safely (truncate sensitive values)
+logger.info "Token type: #{token[:auth_type]}, " \
+            "Access token: #{token[:access_token].to_s[0..5]}..."
+```
+
+## See Also
+
+- [Legate::Auth::Credential](./credential)
+- [Legate::Auth::Scheme](./scheme)
+- [Legate::Auth::TokenManager](./token_manager)

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

@@ -0,0 +1,175 @@
+# Excon Middleware for Authentication
+
+## Overview
+
+The `Legate::Auth::ExconMiddleware` provides automatic authentication header injection for HTTP requests made using the Excon HTTP client. This middleware simplifies authentication by seamlessly handling token lifecycle, automatic retries for authentication failures, and integrating with the Legate authentication system.
+
+> **Wiring:** You normally don't construct this middleware directly or pass scheme/credential as top-level `Excon.new` keyword arguments. Instead use the helper methods `Legate::Auth.create_connection(url, scheme:, credential:, ...)` or `Legate::Auth.create_middleware(scheme:, credential:, ...)`. When the middleware runs inside Excon's stack it operates as a "shell" instance and reads its configuration from `datum[:connection].data[:auth_middleware_config]`, which the helpers set up for you.
+
+## Class Definition
+
+```ruby
+module Legate
+  module Auth
+    class ExconMiddleware < Excon::Middleware::Base
+      # Implementation of Excon middleware for authentication
+    end
+  end
+end
+```
+
+## Key Features
+
+- Automatic injection of authentication headers based on scheme type
+- Token refresh handling for expired credentials
+- Configurable retry behavior for authentication failures
+- Integration with the Legate token lifecycle management
+- Support for all authentication schemes (API Key, Bearer, OAuth2, OIDC, Service Account)
+
+## Constructor
+
+### `initialize`
+
+Creates a new ExconMiddleware instance.
+
+**Parameters:**
+- `stack` (Object): The Excon middleware stack (positional argument)
+- `options` (Hash, optional): Configuration options (positional argument, default: {})
+
+**Options Keys:**
+- `:scheme` (Legate::Auth::Scheme): Authentication scheme to use
+- `:credential` (Legate::Auth::Credential): Initial authentication credential
+- `:token_store` (Legate::Auth::TokenStore): Store for caching tokens
+- `:token_manager` (Legate::Auth::TokenManager): Token lifecycle manager
+- `:auto_retry` (Boolean): Whether to automatically retry on auth failure
+- `:max_retries` (Integer): Maximum number of retry attempts for auth failures (default: 3)
+- `:backoff_strategy` (Symbol): Strategy for retry delay (`:none`, `:linear`, `:exponential`)
+- `:backoff_factor` (Float): Factor for backoff calculation
+- `:retry_non_idempotent` (Boolean): Whether to retry non-idempotent requests
+- `:retry_on` (Array): HTTP status codes or exceptions that trigger retries
+
+## Instance Methods
+
+### `request_call`
+
+Called before each request to inject authentication headers.
+
+**Parameters:**
+- `datum` (Hash): The Excon request datum
+
+**Returns:**
+- Hash: The modified request datum with authentication headers
+
+### `response_call`
+
+Called after each response to check for authentication failures and handle retries.
+
+**Parameters:**
+- `datum` (Hash): The Excon response datum
+
+**Returns:**
+- Hash: The response datum
+
+### `should_retry?`
+
+Determines if a request should be retried based on the response.
+
+**Parameters:**
+- `request_datum` (Hash): The original request datum
+- `response_details` (Hash): Details about the response
+
+**Returns:**
+- Boolean: `true` if the request should be retried
+
+## Usage
+
+### Basic Usage
+
+```ruby
+# Create a connection with authentication middleware via the helper
+connection = Legate::Auth.create_connection('https://api.example.com',
+  scheme: api_key_scheme,
+  credential: api_key_credential
+)
+
+# Make authenticated requests
+response = connection.get(path: '/protected-resource')
+```
+
+### With Token Store
+
+```ruby
+# Pass a token store/manager for caching and lifecycle management
+connection = Legate::Auth.create_connection('https://api.example.com',
+  scheme: oauth2_scheme,
+  credential: oauth2_credential,
+  token_store: token_store,
+  token_manager: token_manager
+)
+```
+
+### With Retry Configuration
+
+```ruby
+connection = Legate::Auth.create_connection('https://api.example.com',
+  scheme: scheme,
+  credential: credential,
+  auto_retry: true,
+  max_retries: 3,
+  backoff_strategy: :exponential,
+  backoff_factor: 2.0,
+  retry_on: [401, 403]
+)
+```
+
+These helpers add `ExconMiddleware` to the connection's middleware stack and store the configured middleware instance on `connection.data[:auth_middleware_config]`, where the shell middleware reads it at request time.
+
+## Example with OAuth2
+
+```ruby
+# Create OAuth2 scheme and credential
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  token_url: 'https://auth.example.com/token',
+  authorization_url: 'https://auth.example.com/authorize',
+  scopes: ['read', 'write']
+)
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: ENV['CLIENT_ID'],
+  client_secret: ENV['CLIENT_SECRET']
+)
+
+# Create connection with OAuth2 authentication
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+connection = Legate::Auth.create_connection('https://api.example.com',
+  scheme: scheme,
+  credential: credential,
+  token_store: token_store,
+  token_manager: token_manager
+)
+
+# Make authenticated request
+response = connection.get(path: '/user/profile')
+```
+
+## Middleware Stack Position
+
+For proper operation, the `ExconMiddleware` should be positioned after any middleware that modifies the request parameters and before middleware that actually makes the HTTP request.
+
+## Integration with Token Lifecycle
+
+The middleware automatically integrates with the Legate token lifecycle management:
+
+1. When a request is made, it checks for existing valid tokens
+2. If tokens are expired, it attempts to refresh them automatically
+3. If refresh fails or tokens are invalid, it triggers the appropriate authentication flow
+4. On successful authentication, it retries the original request
+
+## Related Classes
+
+- [`Legate::Auth::Scheme`](./scheme): Base class for authentication schemes
+- [`Legate::Auth::Credential`](./credential): Container for authentication credentials
+- [`Legate::Auth::TokenManager`](./token_manager): Manages token lifecycle
+- [`Legate::Auth::ToolContextExtension`](./tool_context_extension): Tool context integration

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

@@ -0,0 +1,30 @@
+# Authentication API Reference
+
+This section provides comprehensive documentation for all authentication-related classes and methods in the Legate Ruby library.
+
+## Core Classes
+
+- [Legate::Auth::Scheme](./scheme) - Abstract base class for authentication schemes
+- [Legate::Auth::Credential](./credential) - Container for authentication credentials
+- [Legate::Auth::Config](./config) - Configuration for authentication flows
+- [Legate::Auth::ExchangedCredential](./exchanged_credential) - Container for exchanged credentials
+
+## Authentication Schemes
+
+- [Legate::Auth::Schemes::ApiKey](./schemes/api_key) - API Key authentication scheme
+- [Legate::Auth::Schemes::HTTPBearer](./schemes/http_bearer) - HTTP Bearer authentication scheme
+- [Legate::Auth::Schemes::OAuth2](./schemes/oauth2) - OAuth2 authentication scheme
+- [Legate::Auth::Schemes::OpenIDConnect](./schemes/openid_connect) - OpenID Connect authentication scheme
+- [Legate::Auth::Schemes::ServiceAccount](./schemes/service_account) - Service Account authentication scheme
+- [Legate::Auth::Schemes::GoogleServiceAccount](./schemes/google_service_account) - Google Service Account authentication scheme
+
+## Authentication Management
+
+- [Legate::Auth::TokenManager](./token_manager) - Token lifecycle management
+- [Legate::Auth::TokenStore](./token_store) - Secure token storage
+- [Legate::Auth::Encryption](./encryption) - Opt-in encryption utilities (not wired into TokenStore)
+
+## Integration
+
+- [Legate::Auth::ToolContextExtension](./tool_context_extension) - Tool context authentication extensions
+- [Legate::Auth::ExconMiddleware](./excon_middleware) - Middleware for Excon HTTP client