legate 0.1.0

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

@@ -0,0 +1,221 @@
+# Token Lifecycle Management
+
+## Overview
+
+The `Legate::Auth::TokenManager` is responsible for managing the lifecycle of authentication tokens, including token storage, expiration handling, and automatic refresh. It serves as a critical component in the Legate authentication system, ensuring that valid tokens are always available for API requests.
+
+## Class Definition
+
+```ruby
+module Legate
+  module Auth
+    class TokenManager
+      # Token lifecycle management implementation
+    end
+  end
+end
+```
+
+## Key Features
+
+- Caching of authentication tokens via the token store
+- Automatic token refresh before expiration
+- Token validation and expiration checking
+- Support for all token-based authentication schemes
+- Event callbacks for token lifecycle events
+- Integration with the Legate token store
+
+## Constructor
+
+### `new`
+
+Creates a new token manager instance.
+
+**Parameters:**
+- `token_store` (Legate::Auth::TokenStore): The token store for persisting tokens (positional argument)
+- `config` (Hash, optional): Configuration options (positional argument, default: {})
+
+**Examples:**
+
+```ruby
+# Create a token manager with a token store
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+# With configuration options
+token_manager = Legate::Auth::TokenManager.new(token_store, { refresh_buffer: 300 })
+```
+
+**Configuration keys** (with defaults):
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `refresh_buffer` | `60` | Seconds before expiration to trigger refresh |
+| `retry_max_attempts` | `3` | Maximum number of refresh retry attempts |
+| `retry_delay` | `2` | Initial delay between retries (seconds) |
+| `retry_backoff` | `1.5` | Backoff multiplier for subsequent retries |
+| `auto_refresh` | `true` | Whether to automatically refresh tokens |
+| `background_refresh` | `false` | Whether to refresh tokens in the background |
+
+## Instance Methods
+
+### `get_token`
+
+Retrieves a valid token for the given scheme and credential, refreshing if necessary.
+
+**Parameters:**
+- `scheme` (Legate::Auth::Scheme): The authentication scheme
+- `credential` (Legate::Auth::Credential): The credential to get a token for
+- `force_refresh` (Boolean, optional): Force a token refresh even if the current token is valid (default: false)
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: A valid token
+
+**Examples:**
+
+```ruby
+# Get a token (will auto-refresh if expired)
+token = token_manager.get_token(scheme, credential)
+
+# Force a fresh token
+token = token_manager.get_token(scheme, credential, force_refresh: true)
+```
+
+### `refresh_token`
+
+Refreshes a token using the scheme's refresh mechanism.
+
+**Parameters:**
+- `scheme` (Legate::Auth::Scheme): The authentication scheme
+- `credential` (Legate::Auth::Credential): The credential associated with the token
+- `token` (Legate::Auth::ExchangedCredential, optional): The token to refresh (default: nil)
+- `cache_key` (String, optional): The cache key for the token (default: nil)
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The refreshed token
+
+**Examples:**
+
+```ruby
+# Refresh a specific token
+refreshed = token_manager.refresh_token(scheme, credential, token)
+
+# Refresh with a cache key
+refreshed = token_manager.refresh_token(scheme, credential, token, 'my_cache_key')
+```
+
+### `invalidate_token`
+
+Invalidates a cached token, removing it from the store.
+
+**Parameters:**
+- `cache_key` (String): The cache key of the token to invalidate
+
+**Examples:**
+
+```ruby
+token_manager.invalidate_token('oauth2_client123')
+```
+
+### `revoke_token`
+
+Revokes a token using the scheme's revocation mechanism.
+
+**Parameters:**
+- `scheme` (Legate::Auth::Scheme): The authentication scheme
+- `credential` (Legate::Auth::Credential): The credential associated with the token
+- `token` (Legate::Auth::ExchangedCredential): The token to revoke
+
+**Examples:**
+
+```ruby
+token_manager.revoke_token(scheme, credential, token)
+```
+
+### `on`
+
+Registers an event callback for token lifecycle events.
+
+**Parameters:**
+- `event` (Symbol): The event to listen for. Valid events are `:before_expiry`, `:refresh_success`, `:refresh_failure`, and `:invalidated`. Any other event raises `ArgumentError`.
+- `&callback` (Block): The callback to invoke when the event occurs
+
+Each callback receives a **single Hash** argument with keys including `:event`, `:token`, `:scheme`, `:credential` (plus event-specific extras such as `:error` for `:refresh_failure` or `:cache_key` for `:invalidated`).
+
+**Examples:**
+
+```ruby
+# Listen for successful token refreshes
+token_manager.on(:refresh_success) do |data|
+  puts "Token refreshed for #{data[:scheme]&.scheme_type}"
+end
+
+# Listen for tokens approaching expiry
+token_manager.on(:before_expiry) do |data|
+  puts "Token approaching expiration"
+end
+
+# Listen for refresh failures
+token_manager.on(:refresh_failure) do |data|
+  puts "Refresh failed: #{data[:error]&.message}"
+end
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+# Create a token store and manager
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+# Get a token for an OAuth2 flow
+token = token_manager.get_token(oauth2_scheme, oauth2_credential)
+
+# Use the token
+puts token[:access_token]
+```
+
+### With Automatic Refresh
+
+```ruby
+# The token manager automatically refreshes expired tokens
+token = token_manager.get_token(scheme, credential)
+
+# If the token is expired and the scheme supports refresh,
+# it will be automatically refreshed before being returned
+```
+
+## Token Structure
+
+Tokens are stored as Legate::Auth::ExchangedCredential objects with attributes like:
+
+```ruby
+{
+  access_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+  refresh_token: 'rtok_abc123...',
+  id_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', # Optional, for OIDC
+  token_type: 'Bearer',
+  expires_in: 3600
+}
+```
+
+## Integration with Authentication Schemes
+
+The token manager integrates with authentication schemes to handle scheme-specific token operations:
+
+```ruby
+# OAuth2 token management
+token = token_manager.get_token(oauth2_scheme, oauth2_credential)
+
+# Service account token management
+token = token_manager.get_token(service_account_scheme, sa_credential)
+```
+
+## Related Classes
+
+- [`Legate::Auth::TokenStore`](./token_store): Secure storage for tokens
+- [`Legate::Auth::ExchangedCredential`](./exchanged_credential): Container for exchanged credentials
+- [`Legate::Auth::Schemes::OAuth2`](./schemes/oauth2): OAuth2 authentication scheme
+- [`Legate::Auth::ExconMiddleware`](./excon_middleware): HTTP client middleware

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

@@ -0,0 +1,146 @@
+# Token Store
+
+## Overview
+
+The `Legate::Auth::TokenStore` class caches authentication tokens in scoped session state (under the `auth` scope). It serves as the foundation for token management within the Legate authentication system.
+
+> **Note:** `TokenStore` does **not** encrypt tokens. `store` persists the plaintext result of `token.to_h` into scoped state, and `get` reads it back as-is. For at-rest encryption, use the opt-in [`Legate::Auth::Encryption`](./encryption) module yourself.
+
+## Class Definition
+
+```ruby
+module Legate
+  module Auth
+    class TokenStore
+      # Token store implementation
+    end
+  end
+end
+```
+
+## Key Features
+
+- Caching of authentication tokens in scoped session state
+- Automatic expiry check on retrieval (expired tokens are cleared and return `nil`)
+- Integration with Legate session service
+- Token retrieval by key
+- Support for multiple token sets
+
+## Constructor
+
+### `new`
+
+Creates a new token store instance.
+
+**Parameters:**
+- `session_service` (Legate::SessionService::Base): The session service for persisting token data (positional argument)
+
+**Examples:**
+
+```ruby
+# Create a token store with the session service
+token_store = Legate::Auth::TokenStore.new(session_service)
+```
+
+## Instance Methods
+
+### `store`
+
+Stores a token under the given key by serializing it with `token.to_h` and saving it to scoped state. Only `Legate::Auth::ExchangedCredential` instances are accepted; anything else returns `false`.
+
+**Parameters:**
+- `key` (String): The key to store the token under
+- `token` (Legate::Auth::ExchangedCredential): The token to store
+
+**Returns:**
+- Boolean: `true` if the token was stored, `false` otherwise
+
+**Examples:**
+
+```ruby
+token_store.store('oauth2_client123', exchanged_credential)
+```
+
+### `get`
+
+Retrieves the token stored under the specified key, deserializing it back into an `ExchangedCredential`. If the stored token is expired it is cleared and `nil` is returned.
+
+**Parameters:**
+- `key` (String): The key to retrieve the token for
+
+**Returns:**
+- Legate::Auth::ExchangedCredential, or nil if not found or expired
+
+**Examples:**
+
+```ruby
+token = token_store.get('oauth2_client123')
+```
+
+### `clear`
+
+Removes the token stored under the specified key.
+
+**Parameters:**
+- `key` (String): The key of the token to remove
+
+**Examples:**
+
+```ruby
+token_store.clear('oauth2_client123')
+```
+
+### `clear_all`
+
+Removes all tokens from the token store.
+
+**Examples:**
+
+```ruby
+token_store.clear_all
+```
+
+## Token Storage and At-Rest Encryption
+
+The token store persists tokens as plaintext `token.to_h` data in scoped session state. It does **not** encrypt them. The security of stored tokens therefore depends on the underlying session service (for example, in-memory storage in the default container deployment).
+
+If you need at-rest encryption, apply the opt-in [`Legate::Auth::Encryption`](./encryption) module in your own storage layer (it requires the `rbnacl` gem and a Base64 key in `LEGATE_AUTH_ENCRYPTION_KEY`).
+
+```ruby
+# Tokens are stored as-is (no automatic encryption)
+token_store.store('client123', token)
+
+# Retrieved as-is (expired tokens are cleared and return nil)
+token = token_store.get('client123')
+```
+
+## Integration with Session Service
+
+The token store integrates with the Legate session service to persist tokens across requests:
+
+```ruby
+# Create an in-memory session service
+session_service = Legate::SessionService::InMemory.new
+
+# Create a token store with the session service
+token_store = Legate::Auth::TokenStore.new(session_service)
+```
+
+## Usage with Token Manager
+
+The token store is typically used via the `TokenManager` rather than directly:
+
+```ruby
+# Create a token store and manager
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+# The token manager uses the store internally
+token = token_manager.get_token(scheme, credential)
+```
+
+## Related Classes
+
+- [`Legate::Auth::TokenManager`](./token_manager): Token lifecycle management
+- [`Legate::Auth::Encryption`](./encryption): Opt-in encryption utilities (not wired into TokenStore)
+- [`Legate::SessionService::Base`](../../core_concepts/legate_session_service): Base session service class

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

@@ -0,0 +1,166 @@
+# Tool Context Authentication Extensions
+
+## Overview
+
+The `Legate::Auth::ToolContextExtension` module extends the `Legate::ToolContext` class with authentication-specific functionality, allowing tools to easily access and manage authentication credentials. This extension is critical for tools that need to authenticate with external APIs.
+
+## Module Definition
+
+```ruby
+module Legate
+  module Auth
+    module ToolContextExtension
+      # Authentication extensions for ToolContext
+    end
+  end
+end
+```
+
+## Key Features
+
+- Access to authentication runners and token stores
+- Managed authentication sessions
+- Integration with interactive authentication flows
+- Support for all authentication schemes
+
+## Methods
+
+### `auth_runner`
+
+Returns the authentication runner for managing authentication flows.
+
+**Returns:**
+- The authentication runner instance
+
+**Examples:**
+
+```ruby
+# In a tool's implementation
+runner = context.auth_runner
+```
+
+### `get_token_store`
+
+Returns the token store for the current session.
+
+**Returns:**
+- Legate::Auth::TokenStore: The token store
+
+**Examples:**
+
+```ruby
+token_store = context.get_token_store
+```
+
+### `with_authentication`
+
+Wraps a block with authentication handling. If authentication is required, it will initiate the authentication flow and retry the block once authentication is complete.
+
+**Parameters:**
+- `&block` (Block): The block to execute with authentication
+
+**Examples:**
+
+```ruby
+# In a tool's implementation
+def perform_execution(params, context)
+  context.with_authentication do
+    # Make authenticated API calls here
+    # If auth fails, the flow will be initiated automatically
+    response = make_api_request(context)
+    { status: :success, result: response }
+  end
+end
+```
+
+### `auth_session`
+
+Creates an authentication session for the given scheme and credential.
+
+**Parameters:**
+- `scheme` (Legate::Auth::Scheme): The authentication scheme
+- `credential` (Legate::Auth::Credential): The credential to use
+- `**options` (Hash): Additional options for the authentication session
+
+**Returns:**
+- An authentication session object
+
+**Examples:**
+
+```ruby
+session = context.auth_session(oauth2_scheme, oauth2_credential)
+```
+
+### `handle_auth_response`
+
+Handles an authentication response from an interactive authentication flow (e.g., OAuth2 callback).
+
+**Parameters:**
+- `request_id` (String): The authentication request ID
+- `response` (Hash): The authentication response data
+
+**Examples:**
+
+```ruby
+# When the OAuth2 callback is received
+context.handle_auth_response('req_123456', {
+  code: params[:code],
+  state: params[:state]
+})
+```
+
+### `cancel_auth_flow`
+
+Cancels an in-progress authentication flow.
+
+**Parameters:**
+- `request_id` (String): The authentication request ID to cancel
+- `reason` (String, optional): The reason for cancellation (default: nil)
+
+**Examples:**
+
+```ruby
+# Cancel an authentication flow
+context.cancel_auth_flow('req_123456', 'User declined')
+```
+
+## Integration with Tool Implementation
+
+Here's a complete example of how to use the tool context extensions in a custom tool:
+
+```ruby
+class MyApiTool < Legate::Tool
+  def perform_execution(params, context)
+    context.with_authentication do
+      # Get a token store for caching
+      token_store = context.get_token_store
+
+      # Create an auth session
+      session = context.auth_session(
+        Legate::Auth::Schemes::OAuth2.new(
+          authorization_url: 'https://auth.example.com/authorize',
+          token_url: 'https://auth.example.com/token'
+        ),
+        Legate::Auth::Credential.new(
+          auth_type: :oauth2,
+          client_id: ENV['CLIENT_ID'],
+          client_secret: ENV['CLIENT_SECRET']
+        )
+      )
+
+      # Make authenticated API request
+      conn = Excon.new('https://api.example.com')
+      response = conn.get(path: '/data')
+
+      # Process response
+      { result: JSON.parse(response.body) }
+    end
+  end
+end
+```
+
+## Related Classes
+
+- [`Legate::Auth::Config`](./config): Authentication configuration
+- [`Legate::Auth::TokenManager`](./token_manager): Token lifecycle management
+- [`Legate::Auth::Scheme`](./scheme): Base class for authentication schemes