legate 0.1.0

data/public/docs/advanced/mcp_schema_conversion.md

@@ -0,0 +1,59 @@
+# MCP Schema Conversion Details
+
+This document details the automatic conversion processes between the different schema formats used by Legate, the Model Context Protocol (MCP), and the `fast-mcp` gem. Understanding this is helpful when defining tools or troubleshooting integration issues.
+
+## Formats
+
+*   **Legate Parameters:** Defined within a `Legate::Tool` subclass using the `parameter` DSL (with `tool_description` for the description). Internally these are stored as a Ruby hash like:
+    ```ruby
+    { 
+      param_name: { 
+        type: :symbol, # :string, :integer, :numeric, :boolean, :array, :hash 
+        required: boolean, 
+        description: string 
+      }, 
+      # ... 
+    }
+    ```
+*   **MCP JSON Schema:** Standard JSON Schema objects used in MCP `tools/list` (`inputSchema`) and `resources/list` (`schema`).
+    ```json
+    { 
+      "type": "object", 
+      "properties": { 
+        "param_name": { "type": "string", "description": "..." }
+      },
+      "required": ["param_name"]
+    }
+    ```
+*   **Dry::Schema:** Used by `fast-mcp` within the `arguments` block to define and validate tool parameters.
+    ```ruby
+    arguments do
+      required(:param_name).filled(:string).description("...")
+    end
+    ```
+
+## Conversion Flows
+
+### 1. MCP JSON Schema -> Legate Params
+
+*   **Where:** Done by `Legate::Mcp::ToolWrapper.from_mcp_schema` using `Legate::Mcp::Util::SchemaConverter.json_to_legate`.
+*   **Use Case:** When an Legate Agent connects to an external MCP server and discovers its tools (Client Mode).
+*   **Mapping (V1):** Basic types (`string`, `integer`, `number`, `boolean`) are mapped to corresponding Legate types (`:string`, `:integer`, `:numeric`, `:boolean`). `required` status and `description` are preserved.
+*   **Limitations (V1):** Complex types (`object`, `array`), constraints (`minLength`, `enum`, `format` etc.) are **ignored** during conversion. Only the basic type, requirement, and description are used.
+
+### 2. Legate Params -> Dry::Schema
+
+*   **Where:** Done by `Legate::Mcp::Server::LegateToolAdapter.wrap` using `Legate::Mcp::Util::SchemaConverter.legate_to_dry_schema`.
+*   **Use Case:** When exposing an `Legate::Tool` via `fast-mcp` (Server Mode).
+*   **Mapping (V1):** Basic Legate types (`:string`, `:integer`, `:numeric`, `:boolean`) are mapped to appropriate `Dry::Schema` calls (`filled(:string)`, `filled(:integer)`, `filled(Dry::Types['coercible.float'])`, `filled(:bool)`). `:required` status maps to `required()` or `optional()`.
+*   **Limitations (V1):** Legate types `:array`, `:hash`, `:object` receive basic mappings (`value(:array)`, `value(:hash)`) **without** nested schema validation. Parameter descriptions from Legate metadata are **not** added to the Dry::Schema block itself (they are set separately on the `fast-mcp` tool using `description` DSL by the adapter).
+
+### 3. Legate Params -> JSON for MCP Call (Client)
+
+*   **Where:** Inside `Legate::Mcp::ToolWrapper#perform_execution`.
+*   **Use Case:** When an Legate Agent executes an external MCP tool.
+*   **Mapping (V1):** Simple conversion of the Legate params hash (symbol keys) to a JSON hash (string keys). Assumes a flat structure.
+
+## Key Takeaway
+
+For V1, schema conversion primarily supports basic data types and required fields. Complex nested structures or validation rules defined in one system may not be fully enforced or represented when crossing the Legate <-> MCP boundary.

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

@@ -0,0 +1,210 @@
+# Legate::Auth::Config
+
+The `Config` class represents the configuration for interactive authentication flows. It includes all the necessary information to initiate, track, and complete an authentication process that requires user interaction.
+
+## Overview
+
+In interactive authentication flows like OAuth2 or OpenID Connect, the user needs to be redirected to an authentication provider to authenticate and grant permissions. The `Config` class encapsulates all the details needed for this interaction, including the scheme, credential, redirect URI, and callback handling.
+
+## Class Methods
+
+### `new`
+
+Creates a new authentication configuration instance.
+
+**Parameters:**
+- `scheme` (Legate::Auth::Scheme): The authentication scheme to use
+- `credential` (Legate::Auth::Credential): The credential for the authentication flow
+- `auth_request_id` (String, optional): A unique identifier for this authentication request (default: nil)
+- `options` (Hash, optional): Additional configuration options (default: {})
+
+**Examples:**
+
+```ruby
+# Create a basic authentication configuration
+config = Legate::Auth::Config.new(
+  scheme: oauth2_scheme,
+  credential: oauth2_credential
+)
+
+# With an explicit request ID and options
+config = Legate::Auth::Config.new(
+  scheme: oauth2_scheme,
+  credential: oauth2_credential,
+  auth_request_id: 'req_123456',
+  options: { prompt: 'consent' }
+)
+```
+
+### `from_h`
+
+Creates a Config instance from a hash representation.
+
+**Parameters:**
+- `hash` (Hash): The hash to create the config from
+- `scheme` (Legate::Auth::Scheme, optional): The scheme to associate (default: nil)
+- `credential` (Legate::Auth::Credential, optional): The credential to associate (default: nil)
+
+**Returns:**
+- Legate::Auth::Config: A new Config instance
+
+**Examples:**
+
+```ruby
+config = Legate::Auth::Config.from_h(
+  saved_hash,
+  scheme: oauth2_scheme,
+  credential: oauth2_credential
+)
+```
+
+## Instance Attributes
+
+### Readers (read-only)
+
+- `scheme` - The authentication scheme
+- `credential` - The authentication credential
+- `auth_request_id` - The unique request identifier
+
+### Accessors (read/write)
+
+- `auth_uri` - The URI to redirect the user to for authentication
+- `redirect_uri` - The redirect URI for the callback
+- `state` - The state parameter for CSRF protection
+- `pkce` - PKCE parameters for the flow
+- `response_uri` - The response URI from the provider callback
+- `options` - Additional configuration options
+
+## Instance Methods
+
+### `build_authorization_uri`
+
+Builds the authorization URI for the authentication flow using the associated scheme.
+
+**Parameters:**
+- `redirect_uri` (String, optional): The redirect URI for the callback
+- `state` (String, optional): The state parameter for CSRF protection
+
+**Returns:**
+- String: The authorization URI
+
+**Examples:**
+
+```ruby
+config = Legate::Auth::Config.new(
+  scheme: oauth2_scheme,
+  credential: oauth2_credential
+)
+
+auth_uri = config.build_authorization_uri(
+  'https://app.example.com/callback',
+  SecureRandom.hex(16)
+)
+```
+
+### `to_h`
+
+Converts the configuration to a hash.
+
+**Parameters:**
+- `include_credentials` (Boolean, optional): Whether to include credential data (default: false)
+
+**Returns:**
+- Hash: A hash representation of the configuration
+
+**Examples:**
+
+```ruby
+config = Legate::Auth::Config.new(
+  scheme: oauth2_scheme,
+  credential: oauth2_credential,
+  auth_request_id: 'req_123456'
+)
+
+# Without credentials (safe for logging)
+puts config.to_h
+
+# With credentials included
+puts config.to_h(include_credentials: true)
+```
+
+### `validate_response!`
+
+Validates an authentication response against this request configuration (matching request ID, presence of a response URI, and state).
+
+**Parameters:**
+- `response_config` (Legate::Auth::Config): The response configuration to validate against this request
+
+**Returns:**
+- Boolean: `true` if the response is valid
+
+**Raises:**
+- `Legate::Auth::ConfigurationError`: If the response is invalid (ID mismatch, missing response URI, or state mismatch)
+
+**Examples:**
+
+```ruby
+# Validate a response Config against the original request Config
+config.validate_response!(response_config)
+```
+
+## Usage in Authentication Flows
+
+The `Config` class is a key component in interactive authentication flows:
+
+1. **Creation**: A `Config` is created with the scheme and credential
+2. **URI Generation**: The config builds the authorization URI via `build_authorization_uri`
+3. **User Redirection**: The application redirects the user to the `auth_uri`
+4. **Callback Handling**: When the user completes authentication, the provider redirects back with an authorization code or token
+5. **Request Matching**: The application matches the callback to the original request using the `auth_request_id`
+
+Here's an example of how it's used in a typical OAuth2 flow:
+
+```ruby
+# 1. Configure the OAuth2 scheme and credential
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://auth.example.com/authorize',
+  token_url: 'https://auth.example.com/token',
+  scopes: ['profile', 'email']
+)
+
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: ENV['CLIENT_ID'],
+  client_secret: ENV['CLIENT_SECRET']
+)
+
+# 2. Create a Config and build the authorization URI
+config = Legate::Auth::Config.new(
+  scheme: scheme,
+  credential: credential
+)
+
+auth_uri = config.build_authorization_uri(
+  'https://app.example.com/callback',
+  SecureRandom.hex(16)
+)
+
+# 3. In a web application, redirect the user to the auth URI
+# redirect_to auth_uri
+
+# 4. When the user is redirected back, set the response URI on the config
+config.response_uri = 'https://app.example.com/callback?code=12345&state=abc123'
+
+# 5. Exchange the authorization code for a token
+#    (exchange_token reads code/state from config.response_uri and verifies state)
+token = scheme.exchange_token(config, credential)
+```
+
+## Security Considerations
+
+- The `auth_request_id` should be cryptographically secure to prevent request forgery
+- State parameters should be validated on callback to prevent CSRF attacks
+- The `auth_uri` should always use HTTPS to protect the authentication process
+
+## See Also
+
+- [Legate::Auth::Scheme](./scheme)
+- [Legate::Auth::Schemes::OAuth2](./schemes/oauth2)
+- [Legate::Auth::Schemes::OpenIDConnect](./schemes/openid_connect)
+- [Legate::Auth::ExchangedCredential](./exchanged_credential)

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

@@ -0,0 +1,246 @@
+# Legate::Auth::Credential
+
+The `Credential` class represents authentication credentials required by different authentication schemes. It handles different types of credentials such as API keys, OAuth2 client credentials, service account keys, and HTTP Bearer tokens.
+
+## Overview
+
+A credential contains the initial authentication information needed to begin an authentication flow or to directly authenticate requests. It can handle different credential types and supports environment variable resolution for sensitive values.
+
+## Class Constants
+
+- `VALID_TYPES`: Valid credential types - `:api_key`, `:oauth2`, `:oidc`, `:service_account`, `:google_service_account`, `:http_bearer`, `:basic`
+- `ENV_PREFIX`: Prefix for environment variable references (`'ENV:'`)
+
+## Class Methods
+
+### `new`
+
+Creates a new credential instance.
+
+**Parameters:**
+- `auth_type` (Symbol): The type of authentication (:api_key, :oauth2, :oidc, :service_account, :http_bearer)
+- `kwargs` (Hash): Additional attributes for the specific auth type
+
+**Raises:**
+- `Legate::Auth::CredentialError`: If the credential is invalid
+
+**Examples:**
+
+```ruby
+# API Key credential
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'my-api-key'
+)
+
+# OAuth2 credential
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: 'my-client-id',
+  client_secret: 'my-client-secret'
+)
+
+# OAuth2 credential with environment variable
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: 'my-client-id',
+  client_secret: 'ENV:MY_CLIENT_SECRET'
+)
+
+# Service Account credential (service_account_key is a raw JSON string)
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('service-account.json')
+)
+
+# Service Account credential from a file path
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key_file: '/path/to/service-account.json'
+)
+
+# HTTP Bearer token
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: 'my-bearer-token'
+)
+```
+
+## Instance Methods
+
+### `[]`
+
+Gets an attribute value, optionally resolving environment variables.
+
+**Parameters:**
+- `name` (Symbol, String): The attribute name
+- `resolve_env` (Boolean, optional): Whether to resolve environment variables (default: true)
+
+**Returns:**
+- The attribute value, or nil if not present
+
+**Raises:**
+- `Legate::Auth::EnvironmentVariableNotFoundError`: If an environment variable is not found
+
+**Examples:**
+
+```ruby
+# Get a regular attribute
+client_id = credential[:client_id]
+
+# Get an attribute without resolving environment variables
+raw_value = credential[:client_secret, resolve_env: false]
+
+# Get an attribute with environment variable resolution (default)
+resolved_value = credential[:client_secret]
+```
+
+### `[]=`
+
+Sets an attribute value.
+
+**Parameters:**
+- `name` (Symbol, String): The attribute name
+- `value` (Object): The attribute value
+
+**Examples:**
+
+```ruby
+# Set an attribute
+credential[:client_id] = 'new-client-id'
+
+# Set an environment variable reference
+credential[:client_secret] = 'ENV:NEW_CLIENT_SECRET'
+```
+
+### `to_h`
+
+Converts the credential to a hash.
+
+**Parameters:**
+- `resolve_env` (Boolean, optional): Whether to resolve environment variables (default: false)
+
+**Returns:**
+- Hash: A hash representation of the credential
+
+**Examples:**
+
+```ruby
+# Get hash representation without resolving environment variables
+hash = credential.to_h
+
+# Get hash representation with environment variables resolved
+resolved_hash = credential.to_h(resolve_env: true)
+```
+
+### `has_attribute?`
+
+Checks if the credential has an attribute.
+
+**Parameters:**
+- `name` (Symbol, String): The attribute name
+
+**Returns:**
+- Boolean: True if the attribute exists
+
+**Examples:**
+
+```ruby
+# Check if an attribute exists
+if credential.has_attribute?(:client_id)
+  # Use the client_id
+end
+```
+
+## Required Attributes by Type
+
+Each credential type requires specific attributes:
+
+| Type | Required Attributes | Description |
+|------|---------------------|-------------|
+| `:api_key` | `:api_key` | The API key for authentication |
+| `:oauth2` | `:client_id` | The OAuth2 client ID |
+| `:oidc` | `:client_id` | The OpenID Connect client ID |
+| `:service_account` | `:service_account_key` or `:service_account_key_file` | The service account key or key file |
+| `:google_service_account` | `:service_account_key` or `:service_account_key_file` | The Google service account key or key file |
+| `:http_bearer` | `:bearer_token` | The Bearer token |
+
+## Environment Variable Resolution
+
+The Credential class supports referencing environment variables for sensitive values by prefixing the value with `ENV:`:
+
+```ruby
+# Reference an environment variable
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: 'my-client-id',
+  client_secret: 'ENV:MY_CLIENT_SECRET'
+)
+
+# When accessing the attribute, the environment variable is resolved
+secret = credential[:client_secret]  # Resolves to the value of ENV['MY_CLIENT_SECRET']
+```
+
+## Examples
+
+### API Key Authentication
+
+```ruby
+# Standard API key
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'my-api-key'
+)
+
+# API key from environment variable
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'ENV:API_KEY'
+)
+
+# API key with additional options
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: 'my-api-key',
+  location: 'header',          # Where to place the API key
+  name: 'X-Custom-API-Key'     # Name of the header or parameter
+)
+```
+
+### OAuth2 Authentication
+
+```ruby
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: 'ENV:OAUTH_CLIENT_ID',
+  client_secret: 'ENV:OAUTH_CLIENT_SECRET'
+)
+```
+
+### Service Account Authentication
+
+```ruby
+# service_account_key takes the raw JSON string (not a parsed Hash)
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('service-account.json')
+)
+
+# Or point at the file directly with service_account_key_file
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key_file: '/path/to/service-account.json'
+)
+```
+
+## Security Considerations
+
+- Always use environment variables (`ENV:` prefix) for sensitive values like client secrets and API keys
+- Never hardcode sensitive credentials in your code
+- The `resolve_env: false` option can be useful for logging to avoid exposing sensitive values
+
+## See Also
+
+- [Legate::Auth::Scheme](./scheme)
+- [Legate::Auth::ExchangedCredential](./exchanged_credential)
+- [Legate::Auth::TokenManager](./token_manager)