legate 0.1.0

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

@@ -0,0 +1,169 @@
+# Legate::Auth::Schemes::HTTPBearer
+
+The `HTTPBearer` class implements the HTTP Bearer authentication scheme, which uses a bearer token to authenticate API requests. This is one of the simpler authentication schemes, used when you already have a bearer token. It is also available via the `HttpBearer` alias.
+
+## Overview
+
+The HTTP Bearer authentication scheme is specified in [RFC 6750](https://tools.ietf.org/html/rfc6750) and is a widely used method for API authentication. It works by including an access token in the `Authorization` header of HTTP requests with the prefix `Bearer`.
+
+## Class Methods
+
+### `new`
+
+Creates a new HTTP Bearer authentication scheme.
+
+**Parameters:**
+- None required
+
+**Examples:**
+
+```ruby
+# Create a basic HTTP Bearer scheme
+scheme = Legate::Auth::Schemes::HTTPBearer.new
+```
+
+## Instance Methods
+
+### `scheme_type`
+
+Returns the type of the authentication scheme.
+
+**Returns:**
+- Symbol: `:http_bearer`
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::HTTPBearer.new
+scheme.scheme_type  # => :http_bearer
+```
+
+### `apply_to_request`
+
+Applies bearer token authentication to a request by adding the token to the Authorization header.
+
+**Parameters:**
+- `request` (Hash): The request to authenticate
+- `credential` (Legate::Auth::ExchangedCredential): The exchanged credential containing the bearer token
+
+**Returns:**
+- Hash: The authenticated request with bearer token in the Authorization header
+
+**Examples:**
+
+```ruby
+# Create a bearer token credential and exchange it
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: 'my-bearer-token'
+)
+
+scheme = Legate::Auth::Schemes::HTTPBearer.new
+token = scheme.exchange_token(credential)
+
+# Apply to a request
+request = { headers: {} }
+authenticated = scheme.apply_to_request(request, token)
+puts authenticated[:headers]['Authorization']  # => "Bearer my-bearer-token"
+```
+
+### `exchange_token`
+
+Exchanges a credential for an authentication token. For HTTP Bearer, this simply wraps the bearer token in an ExchangedCredential.
+
+**Parameters:**
+- `credential` (Legate::Auth::Credential): The credential to exchange
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The exchanged token
+
+**Examples:**
+
+```ruby
+# Create a bearer token credential
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: 'my-bearer-token'
+)
+
+# Exchange for a token
+scheme = Legate::Auth::Schemes::HTTPBearer.new
+token = scheme.exchange_token(credential)
+
+# The token is a wrapped version of the bearer token
+puts token[:access_token]  # => "my-bearer-token"
+```
+
+### `to_h`
+
+Converts the scheme to a hash representation.
+
+**Returns:**
+- Hash: A hash representation of the scheme configuration
+
+## Usage Examples
+
+### Basic Authentication
+
+```ruby
+# Create an HTTP Bearer scheme
+scheme = Legate::Auth::Schemes::HTTPBearer.new
+
+# Create a credential with the bearer token
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: 'my-bearer-token'
+)
+
+# Exchange 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 my-bearer-token"
+```
+
+### With Token Manager
+
+```ruby
+# Create an HTTP Bearer scheme
+scheme = Legate::Auth::Schemes::HTTPBearer.new
+
+# Create a credential with the bearer token
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: 'my-bearer-token'
+)
+
+# 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 bearer token from environment
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: ENV['API_BEARER_TOKEN']
+)
+```
+
+## Security Considerations
+
+- Bearer tokens should be treated like passwords and kept secure
+- Always use HTTPS when transmitting bearer tokens
+- Implement proper token lifecycle management, including expiration and revocation
+- Consider using short-lived tokens to minimize the risk of token leakage
+
+## 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/oauth2.md

@@ -0,0 +1,343 @@
+# Legate::Auth::Schemes::OAuth2
+
+The `OAuth2` class implements the OAuth 2.0 authentication scheme, which is a widely adopted industry-standard protocol for authorization. This scheme handles the complex token exchange flows between your application, users, and OAuth 2.0 providers.
+
+## Overview
+
+OAuth 2.0 is an authorization framework that enables third-party applications to obtain limited access to a user's account on an HTTP service. It works by delegating user authentication to the service that hosts the user's account and authorizing third-party applications to access that account.
+
+## Class Methods
+
+### `new`
+
+Creates a new OAuth 2.0 authentication scheme.
+
+**Parameters:**
+- `authorization_url` (String, optional keyword): The authorization endpoint URL
+- `token_url` (String, optional keyword): The token endpoint URL
+- `scopes` (Array<String>, optional keyword): The OAuth scopes to request
+- `use_pkce` (Boolean, optional keyword): Whether to use PKCE (default: true)
+- `additional_params` (Hash, optional keyword): Additional parameters for the authorization request
+- `revocation_url` (String, optional keyword): The token revocation endpoint URL
+- `**kwargs` (Hash): Additional parameters for the authentication scheme
+
+**Examples:**
+
+```ruby
+# Create a basic OAuth2 scheme for authorization code flow
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://provider.com/oauth2/authorize',
+  token_url: 'https://provider.com/oauth2/token',
+  scopes: ['profile', 'email']
+)
+
+# Create an OAuth2 scheme with PKCE disabled
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://provider.com/oauth2/authorize',
+  token_url: 'https://provider.com/oauth2/token',
+  use_pkce: false
+)
+
+# Create an OAuth2 scheme for client credentials
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  token_url: 'https://provider.com/oauth2/token'
+)
+```
+
+## Instance Methods
+
+### `scheme_type`
+
+Returns the type of the authentication scheme.
+
+**Returns:**
+- Symbol: `:oauth2`
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::OAuth2.new
+scheme.scheme_type  # => :oauth2
+```
+
+### `validate!`
+
+Validates the scheme configuration. Raises an error if required fields (like `token_url`) are missing.
+
+**Raises:**
+- `Legate::Auth::SchemeValidationError`: If the scheme configuration is invalid (e.g. missing `authorization_url` or `token_url`)
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://provider.com/oauth2/authorize',
+  token_url: 'https://provider.com/oauth2/token'
+)
+scheme.validate!  # Passes validation
+```
+
+### `build_authorization_uri`
+
+Builds the authorization URL for the OAuth 2.0 flow.
+
+**Parameters:**
+- `config` (Legate::Auth::Config): The authentication configuration
+- `redirect_uri` (String, optional): The redirect URI for the callback
+- `state` (String, optional): The state parameter for CSRF protection
+
+**Returns:**
+- String: The authorization URL for the OAuth 2.0 flow
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://provider.com/oauth2/authorize',
+  token_url: 'https://provider.com/oauth2/token',
+  scopes: ['profile', 'email']
+)
+
+config = Legate::Auth::Config.new(scheme: scheme, credential: credential)
+auth_url = scheme.build_authorization_uri(
+  config,
+  'http://localhost:3000/oauth2/callback',
+  SecureRandom.hex(16)
+)
+```
+
+### `apply_to_request`
+
+Applies OAuth 2.0 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
+# Apply authentication to a request
+request = { headers: {} }
+authenticated = scheme.apply_to_request(request, exchanged_credential)
+puts authenticated[:headers]['Authorization']  # => "Bearer access-token"
+```
+
+### `exchange_token`
+
+Exchanges an authorization code or config for access and refresh tokens.
+
+**Parameters:**
+- `config` (Legate::Auth::Config): The authentication configuration (with response_uri set)
+- `credential` (Legate::Auth::Credential): The credential containing client information
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The exchanged tokens
+
+**Examples:**
+
+```ruby
+# Exchange authorization code for tokens
+token = scheme.exchange_token(config, credential)
+
+puts token[:access_token]   # => "access-token"
+puts token[:refresh_token]  # => "refresh-token" (if granted)
+puts token[:expires_in]     # => 3600 (seconds until expiration)
+```
+
+### `refresh_token`
+
+Refreshes an expired OAuth 2.0 access token using the refresh token.
+
+**Parameters:**
+- `exchanged_credential` (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)
+puts refreshed_token[:access_token]  # => "new-access-token"
+```
+
+### `client_credentials_token`
+
+Obtains a token using the client credentials grant type.
+
+**Parameters:**
+- `credential` (Legate::Auth::Credential): The credential containing client_id and client_secret
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The token
+
+**Examples:**
+
+```ruby
+token = scheme.client_credentials_token(credential)
+```
+
+### `password_token`
+
+Obtains a token using the resource owner password credentials grant type.
+
+**Parameters:**
+- `credential` (Legate::Auth::Credential): The credential containing client information
+- `username` (String): The resource owner's username
+- `password` (String): The resource owner's password
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The token
+
+**Examples:**
+
+```ruby
+token = scheme.password_token(credential, 'user@example.com', 'password')
+```
+
+### `to_h`
+
+Converts the scheme to a hash representation.
+
+**Returns:**
+- Hash: A hash representation of the scheme configuration
+
+## Usage Examples
+
+### Authorization Code Flow
+
+```ruby
+require 'securerandom'
+
+# Step 1: Create the OAuth2 scheme
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://provider.com/oauth2/authorize',
+  token_url: 'https://provider.com/oauth2/token',
+  scopes: ['profile', 'email']
+)
+
+# Step 2: Set up credential with client details
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: ENV['OAUTH_CLIENT_ID'],
+  client_secret: ENV['OAUTH_CLIENT_SECRET']
+)
+
+# Step 3: Create config and build authorization URI
+config = Legate::Auth::Config.new(scheme: scheme, credential: credential)
+state = SecureRandom.hex(16)
+auth_url = config.build_authorization_uri(
+  'http://localhost:3000/oauth2/callback',
+  state
+)
+
+# Step 4: Redirect user to auth_url
+# redirect_to auth_url
+
+# Step 5: Handle the callback
+config.response_uri = "http://localhost:3000/oauth2/callback?code=12345&state=#{state}"
+token = scheme.exchange_token(config, credential)
+
+# Step 6: Store tokens for future API calls
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_store.store('oauth2_token', token)
+```
+
+### Client Credentials Flow
+
+```ruby
+# Create an OAuth2 scheme for client credentials
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  token_url: 'https://provider.com/oauth2/token',
+  scopes: ['api:read', 'api:write']
+)
+
+# Create a credential with client details
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: ENV['API_CLIENT_ID'],
+  client_secret: ENV['API_CLIENT_SECRET']
+)
+
+# Get token via client credentials (no user interaction required)
+token = scheme.client_credentials_token(credential)
+```
+
+### Using with Token Manager
+
+```ruby
+# Create OAuth2 scheme and credential
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://provider.com/oauth2/authorize',
+  token_url: 'https://provider.com/oauth2/token'
+)
+
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: 'ENV:OAUTH_CLIENT_ID',
+  client_secret: 'ENV:OAUTH_CLIENT_SECRET'
+)
+
+# 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 (will auto-refresh if expired)
+token = token_manager.get_token(scheme, credential)
+```
+
+## Provider-Specific Configurations
+
+### Google
+
+```ruby
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://accounts.google.com/o/oauth2/auth',
+  token_url: 'https://oauth2.googleapis.com/token',
+  scopes: ['profile', 'email', 'https://www.googleapis.com/auth/calendar']
+)
+```
+
+### Microsoft Azure
+
+```ruby
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+  token_url: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+  scopes: ['User.Read', 'Calendars.Read']
+)
+```
+
+### GitHub
+
+```ruby
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://github.com/login/oauth/authorize',
+  token_url: 'https://github.com/login/oauth/access_token',
+  scopes: ['user', 'repo']
+)
+```
+
+## Security Considerations
+
+- Always use HTTPS for all OAuth 2.0 communications
+- Store client secrets securely and never expose them in client-side code
+- Implement state parameter validation to prevent CSRF attacks
+- Use PKCE extension for public clients to prevent authorization code interception
+- Store tokens securely; for at-rest encryption use the opt-in [`Legate::Auth::Encryption`](../encryption) module (TokenStore does not encrypt)
+- Implement proper token lifecycle management, including expiration and revocation
+- Request only the scopes that your application needs (principle of least privilege)
+
+> **SSRF protection:** When the scheme makes HTTP calls (e.g. to the token endpoint), the token URL is validated by `Legate::Auth::UrlGuard`, which blocks loopback, link-local, private, CGNAT (100.64.0.0/10), and `0.0.0.0/8` addresses. Set `LEGATE_ALLOW_PRIVATE_AUTH_URLS=1` to bypass this in development.
+
+## 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/oidc.md

@@ -0,0 +1,73 @@
+# Legate::Auth::Schemes::OpenIDConnect (OIDC)
+
+The `OpenIDConnect` class implements the OpenID Connect (OIDC) authentication scheme, which provides a layer of identity verification on top of OAuth 2.0 protocols. It handles the secure authentication and authorization flow between your application and OIDC providers.
+
+> **Note**: This class is also available via the `OIDC` alias for backward compatibility. Both `:oidc` and `:openid_connect` scheme types map to this same `OpenIDConnect` class.
+
+For full documentation including all methods, constructor parameters, and advanced usage examples, see the main [OpenIDConnect reference](./openid_connect).
+
+## Quick Start
+
+```ruby
+# Create a basic OIDC scheme
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  discovery_url: 'https://accounts.google.com/.well-known/openid-configuration',
+  scopes: ['openid', 'email', 'profile']
+)
+
+# Set up credential with client details
+credential = Legate::Auth::Credential.new(
+  auth_type: :oidc,
+  client_id: ENV['OIDC_CLIENT_ID'],
+  client_secret: ENV['OIDC_CLIENT_SECRET']
+)
+
+# Create config and build authorization URI
+config = Legate::Auth::Config.new(scheme: scheme, credential: credential)
+state = SecureRandom.hex(16)
+auth_url = config.build_authorization_uri(
+  'http://localhost:3000/auth/callback',
+  state
+)
+
+# After callback, exchange token
+config.response_uri = callback_uri
+token = scheme.exchange_token(config, credential)
+
+# Verify ID token
+claims = scheme.verify_id_token(token[:id_token])
+
+# Get user info
+user_info = scheme.get_userinfo(token[:access_token])
+```
+
+## Key Methods
+
+- `scheme_type` - Returns `:openid_connect`
+- `validate!` - Validates scheme configuration
+- `build_authorization_uri(config, redirect_uri, state)` - Builds the authorization URL
+- `apply_to_request(request, credential)` - Applies authentication to a request
+- `exchange_token(config, credential)` - Exchanges authorization code for tokens
+- `refresh_token(exchanged_credential, credential)` - Refreshes expired tokens
+- `verify_id_token(id_token, nonce, audience)` - Verifies an ID token
+- `get_userinfo(access_token)` - Gets user info from the userinfo endpoint
+- `discover_endpoints` - Discovers OIDC endpoints
+- `to_h` - Converts to hash
+
+## Using with Token Manager
+
+```ruby
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+# Get a token (will auto-refresh if expired)
+token = token_manager.get_token(scheme, credential)
+```
+
+## See Also
+
+- [Legate::Auth::Schemes::OpenIDConnect (full reference)](./openid_connect)
+- [Legate::Auth::Credential](../credential)
+- [Legate::Auth::ExchangedCredential](../exchanged_credential)
+- [Legate::Auth::Scheme](../scheme)
+- [Legate::Auth::TokenManager](../token_manager)