o42sdk 0.1.9

# OAuth42 Rust SDK (o42sdk)

Official Rust SDK for OAuth42, providing comprehensive OAuth2/OIDC client functionality with framework integrations for Actix-web and Axum.

## Features

- ✅ OAuth2 Authorization Code Flow with PKCE
- ✅ Token management and automatic refresh
- ✅ OIDC Discovery support
- ✅ Session management with pluggable stores
- ✅ Framework middleware for Actix-web and Axum
- ✅ Type-safe API with comprehensive error handling
- ✅ Example applications demonstrating best practices

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
o42sdk = { version = "0.1", features = ["actix"] }  # For Actix-web
# or
o42sdk = { version = "0.1", features = ["axum"] }   # For Axum
```

## Quick Start

### Basic Usage

```rust
use o42sdk::{OAuth42Client, Config};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client from environment variables
    let config = Config::from_env()?;
    let mut client = OAuth42Client::new(config)?;
    
    // Discover endpoints
    client.discover().await?;
    
    // Build authorization URL with PKCE
    let auth_url = client.authorize_url().await?
        .generate_state()
        .set_pkce_challenge()
        .add_scope("openid")
        .add_scope("profile")
        .add_scope("email")
        .build();
    
    // Redirect user to auth_url...
    
    Ok(())
}
```

### Actix-web Integration

```rust
use actix_web::{web, App, HttpServer};
use o42sdk::{OAuth42Client, OAuth42Auth, Config};
use std::sync::Arc;

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let config = Config::from_env().expect("Failed to load config");
    let client = Arc::new(OAuth42Client::new(config).expect("Failed to create client"));
    
    HttpServer::new(move || {
        App::new()
            .wrap(OAuth42Auth::new(client.clone()))
            .route("/protected", web::get(protected_handler))
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

async fn protected_handler(user: OAuth42User) -> impl Responder {
    format!("Hello, {}!", user.0.sub)
}
```

### Axum Integration

```rust
use axum::{Router, routing::get};
use o42sdk::{OAuth42Client, oauth42_auth, OAuth42User, Config};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let config = Config::from_env().expect("Failed to load config");
    let client = Arc::new(OAuth42Client::new(config).expect("Failed to create client"));
    
    let app = Router::new()
        .route("/protected", get(protected_handler))
        .layer(oauth42_auth(client));
    
    let listener = tokio::net::TcpListener::bind("127.0.0.1:8080")
        .await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

async fn protected_handler(OAuth42User(user): OAuth42User) -> String {
    format!("Hello, {}!", user.sub)
}
```

## Configuration

### Environment Variables

```bash
OAUTH42_CLIENT_ID=your-client-id
OAUTH42_CLIENT_SECRET=your-client-secret

# Issuer URL formats:
# Multi-tenant (subdomain): https://{tenant}.oauth42.com
# Single-tenant/Demo: https://oauth42.com
# Local development: https://localhost:8443
OAUTH42_ISSUER=https://acme.oauth42.com

OAUTH42_REDIRECT_URI=http://localhost:3000/callback
OAUTH42_SCOPES=openid profile email
OAUTH42_AUDIENCE=https://api.example.com  # Optional
```

### Programmatic Configuration

```rust
use o42sdk::Config;

let config = Config::builder()
    .client_id("your-client-id")
    .client_secret("your-client-secret")
    .issuer("https://acme.oauth42.com")?  // Tenant subdomain
    .redirect_uri("http://localhost:3000/callback")?
    .add_scope("openid")
    .add_scope("profile")
    .audience("https://api.example.com")
    .build()?;
```

## Example Applications

The SDK includes two complete example applications:

### o42client1 - Web Application (Actix-web)
- Server-side rendered templates
- Session-based authentication
- Login/logout flow with PKCE
- User dashboard

### o42client2 - API Service (Axum)  
- RESTful API with JWT validation
- Stateless authentication
- Protected endpoints
- Token introspection

## Running Examples

```bash
# Web application example
cd o42client1
cp .env.example .env  # Configure your OAuth42 settings
cargo run

# API service example  
cd o42client2
cp .env.example .env  # Configure your OAuth42 settings
cargo run
```

## Testing

```bash
# Run all tests
cargo test --all

# Unit tests only
cargo test --lib

# Integration tests (requires mock server)
cargo test --test '*'
```

## API Documentation

Key types and functions:

- `OAuth42Client` - Main client for OAuth2 operations
- `Config` - Client configuration
- `TokenResponse` - Access/refresh token response
- `UserInfo` - OpenID Connect user information
- `OAuth42Auth` - Actix-web middleware
- `oauth42_auth()` - Axum layer factory
- `OAuth42User` - Authenticated user extractor

## License

Copyright (c) 2024 OAuth42, Inc. All rights reserved.

This SDK is proprietary software provided by OAuth42, Inc. for use with OAuth42 services.
See LICENSE file for terms and conditions.