docs: update readmes to reflect implementation

Author: marcjazz

authly-actix/README.md

@@ -2,12 +2,13 @@
 
 Actix-web integration for [authly-rs](https://github.com/marcjazz/authly-rs).
 
-This crate provides Actix-web specific helpers and utilities to integrate the `authly` authentication framework into Actix applications.
+This crate provides Actix-web specific extractors and utilities to integrate the `authly` authentication framework into Actix applications.
 
 ## Features
 
-- Actix-web compatible extractors and middleware helpers.
-- Easy integration with `authly-flow` for OAuth2 and OIDC.
+- **Extractors**: Easily access validated sessions or JWT claims in your request handlers.
+- **OAuth2 Helpers**: Streamlined functions for initiating login, handling callbacks, and logging out.
+- **Session Management**: Integration with `authly-session` for server-side session storage.
 
 ## Usage
 
@@ -16,6 +17,116 @@ Add this to your `Cargo.toml`:
 ```toml
 [dependencies]
 authly-actix = "0.1.0"
+authly-session = "0.1.0"
+authly-token = "0.1.0"
+actix-web = "4"
+```
+
+### Extractors
+
+#### `AuthSession`
+
+Extracts a validated session from a cookie. Requires `Arc<dyn SessionStore>` and `SessionConfig` to be registered in `app_data`.
+
+```rust
+use authly_actix::AuthSession;
+use actix_web::{get, HttpResponse};
+
+#[get("/profile")]
+async fn profile(auth: AuthSession) -> HttpResponse {
+    let session = auth.0;
+    HttpResponse::Ok().json(session.identity)
+}
+```
+
+#### `AuthToken`
+
+Extracts and validates a JWT from the `Authorization: Bearer <token>` header. Requires `Arc<TokenManager>` to be registered in `app_data`.
+
+```rust
+use authly_actix::AuthToken;
+use actix_web::{get, HttpResponse};
+
+#[get("/api/data")]
+async fn protected_api(token: AuthToken) -> HttpResponse {
+    let claims = token.0;
+    HttpResponse::Ok().json(claims)
+}
+```
+
+### OAuth2 Helpers
+
+The crate provides helpers to manage the OAuth2 flow lifecycle.
+
+```rust
+use authly_actix::{initiate_oauth_login, handle_oauth_callback, logout, SessionConfig, OAuthCallbackParams};
+use actix_web::{web, HttpRequest, HttpResponse, get};
+use std::sync::Arc;
+
+// 1. Initiate Login
+#[get("/login")]
+async fn login(flow: web::Data<OAuth2Flow>, config: web::Data<SessionConfig>) -> HttpResponse {
+    initiate_oauth_login(&flow, &config, &["user:email"])
+}
+
+// 2. Handle Callback
+#[get("/callback")]
+async fn callback(
+    req: HttpRequest,
+    params: web::Query<OAuthCallbackParams>,
+    flow: web::Data<OAuth2Flow>,
+    store: web::Data<Arc<dyn SessionStore>>,
+    config: web::Data<SessionConfig>,
+) -> Result<HttpResponse, actix_web::Error> {
+    handle_oauth_callback(
+        req,
+        &flow,
+        params.into_inner(),
+        store.get_ref().clone(),
+        config.get_ref().clone(),
+        "/dashboard"
+    ).await
+}
+
+// 3. Logout
+#[get("/logout")]
+async fn sign_out(
+    req: HttpRequest,
+    store: web::Data<Arc<dyn SessionStore>>,
+    config: web::Data<SessionConfig>,
+) -> Result<HttpResponse, actix_web::Error> {
+    logout(req, store.get_ref().clone(), config.get_ref().clone(), "/").await
+}
+```
+
+### Setup
+
+To use the extractors and helpers, you must configure your Actix app with the necessary data:
+
+```rust
+use actix_web::{web, App, HttpServer};
+use authly_actix::SessionConfig;
+use authly_session::MemoryStore;
+use authly_token::TokenManager;
+use std::sync::Arc;
+
+#[actix_web::main]
+async fn main() -> std::io::Result<()> {
+    let session_store: Arc<dyn SessionStore> = Arc::new(MemoryStore::new());
+    let token_manager = Arc::new(TokenManager::new("your-secret".to_string()));
+    let session_config = SessionConfig::default();
+
+    HttpServer::new(move || {
+        App::new()
+            .app_data(web::Data::new(session_store.clone()))
+            .app_data(web::Data::new(token_manager.clone()))
+            .app_data(web::Data::new(session_config.clone()))
+            // ... routes
+    })
+    .bind("127.0.0.1:8080")?
+    .run()
+    .await
+}
 ```
 
 ## Part of authly-rs

authly-axum/README.md

@@ -6,9 +6,16 @@ This crate provides Axum-specific extractors and helpers to easily integrate the
 
 ## Features
 
-- Extractors for `AuthSession`.
-- Helpers for initiating OAuth logins and handling callbacks.
-- Session configuration with secure cookie defaults.
+- **Extractors**:
+  - `AuthSession`: Extracts a validated session from cookies.
+  - `AuthToken`: Extracts and validates a JWT from the `Authorization: Bearer` header.
+- **OAuth Helpers**:
+  - `initiate_oauth_login`: Generates authorization URLs and handles CSRF protection.
+  - `handle_oauth_callback`: Finalizes OAuth login and creates a server-side session.
+  - `handle_oauth_callback_jwt`: Finalizes OAuth login and returns a JWT.
+- **Session Management**:
+  - `logout`: Clears the session cookie and removes it from the store.
+  - `SessionConfig`: Customizable session settings (cookie name, secure, http_only, etc.).
 
 ## Usage
 
@@ -17,21 +24,62 @@ Add this to your `Cargo.toml`:
 ```toml
 [dependencies]
 authly-axum = "0.1.0"
+tower-cookies = "0.10" # Required for session support
 ```
 
-### Example
+### Example: Session-based Authentication
 
 ```rust
-use axum::{routing::get, Router};
-use authly_axum::{AuthSession, HasSessionStore};
+use axum::{routing::get, Router, extract::State};
+use authly_axum::{AuthSession, SessionConfig, initiate_oauth_login, handle_oauth_callback};
+use authly_session::SessionStore;
+use tower_cookies::CookieManagerLayer;
+use std::sync::Arc;
+
+#[derive(Clone)]
+struct AppState {
+    session_store: Arc<dyn SessionStore>,
+    session_config: SessionConfig,
+    // ... other state like OAuth flows
+}
+
+// Implement FromRef for the extractors to work
+impl axum::extract::FromRef<AppState> for Arc<dyn SessionStore> {
+    fn from_ref(state: &AppState) -> Self {
+        state.session_store.clone()
+    }
+}
+
+impl axum::extract::FromRef<AppState> for SessionConfig {
+    fn from_ref(state: &AppState) -> Self {
+        state.session_config.clone()
+    }
+}
 
 async fn protected_handler(AuthSession(session): AuthSession) -> String {
     format!("Welcome back, {}!", session.identity.username.unwrap_or_default())
 }
 
-fn app() -> Router {
-    // ... setup state with SessionStore and OAuthProvider
-    Router::new().route("/protected", get(protected_handler))
+fn app(state: AppState) -> Router {
+    Router::new()
+        .route("/protected", get(protected_handler))
+        // The CookieManagerLayer is required for AuthSession and OAuth helpers
+        .layer(CookieManagerLayer::new())
+        .with_state(state)
+}
+```
+
+### Example: JWT-based Authentication
+
+```rust
+use authly_axum::AuthToken;
+use authly_token::TokenManager;
+use std::sync::Arc;
+
+// Ensure Arc<TokenManager> is available in your State via FromRef
+
+async fn api_handler(AuthToken(claims): AuthToken) -> String {
+    format!("Hello user with ID: {}", claims.sub)
 }
 ```
 

authly-core/README.md

@@ -6,11 +6,13 @@ This crate provides the foundational types and traits used across the `authly` f
 
 ## Features
 
-- `Identity` structure for unified user information.
-- `OAuthProvider` trait for implementing new OAuth2 providers.
-- `CredentialsProvider` trait for password-based auth.
-- `UserMapper` trait for mapping identities to local database users.
-- Standard `AuthError` types.
+- `Identity` structure for unified user information across different providers.
+- `OAuthToken` structure for standard OAuth2 token responses.
+- `OAuthProvider` trait for implementing OAuth2-compatible authentication providers.
+- `CredentialsProvider` trait for password-based or custom credential authentication.
+- `UserMapper` trait for mapping provider identities to local application users.
+- `pkce` module for Proof Key for Code Exchange support.
+- Standard `AuthError` enum for consistent error handling.
 
 ## Usage
 
@@ -21,6 +23,60 @@ Add this to your `Cargo.toml`:
 authly-core = "0.1.0"
 ```
 
+### Core Traits
+
+#### OAuthProvider
+
+The `OAuthProvider` trait defines the interface for OAuth2 providers. It includes methods for generating authorization URLs and exchanging codes for identities.
+
+```rust
+#[async_trait]
+pub trait OAuthProvider: Send + Sync {
+    fn get_authorization_url(
+        &self,
+        state: &str,
+        scopes: &[&str],
+        code_challenge: Option<&str>,
+    ) -> String;
+
+    async fn exchange_code_for_identity(
+        &self,
+        code: &str,
+        code_verifier: Option<&str>,
+    ) -> Result<(Identity, OAuthToken), AuthError>;
+    
+    // Optional methods for token management
+    async fn refresh_token(&self, refresh_token: &str) -> Result<OAuthToken, AuthError>;
+    async fn revoke_token(&self, token: &str) -> Result<(), AuthError>;
+}
+```
+
+#### CredentialsProvider
+
+The `CredentialsProvider` trait is used for non-OAuth authentication methods, such as email/password.
+
+```rust
+#[async_trait]
+pub trait CredentialsProvider: Send + Sync {
+    type Credentials;
+
+    async fn authenticate(&self, creds: Self::Credentials) -> Result<Identity, AuthError>;
+}
+```
+
+#### UserMapper
+
+The `UserMapper` trait allows you to bridge the gap between a provider's `Identity` and your application's local user model.
+
+```rust
+#[async_trait]
+pub trait UserMapper: Send + Sync {
+    type LocalUser: Send + Sync;
+
+    async fn map_user(&self, identity: &Identity) -> Result<Self::LocalUser, AuthError>;
+}
+```
+
 ## Part of authly-rs
 
 This crate is part of the [authly-rs](https://github.com/marcjazz/authly-rs) workspace. `authly` is a modular, framework-agnostic authentication orchestration system for Rust.

authly-flow/README.md

@@ -2,11 +2,13 @@
 
 High-level authentication flows for [authly-rs](https://github.com/marcjazz/authly-rs).
 
-This crate orchestrates authentication flows such as OAuth2 and credentials-based auth, providing a high-level API that is independent of web frameworks.
+This crate orchestrates authentication flows such as OAuth2, Device Flow, Client Credentials, and direct credentials-based auth, providing a high-level API that is independent of web frameworks.
 
 ## Features
 
 - `OAuth2Flow`: Orchestrates the Authorization Code flow (initiation and finalization).
+- `DeviceFlow`: Orchestrates the Device Authorization Flow (RFC 8628).
+- `ClientCredentialsFlow`: Orchestrates the Client Credentials Flow (RFC 6749 Section 4.4).
 - `CredentialsFlow`: Orchestrates direct credential-based authentication.
 - Support for `UserMapper` to integrate with local user databases.
 
@@ -19,7 +21,7 @@ Add this to your `Cargo.toml`:
 authly-flow = "0.1.0"
 ```
 
-### Example: OAuth2 Flow initiation
+### Example: OAuth2 Flow
 
 ```rust
 use authly_flow::OAuth2Flow;
@@ -29,8 +31,55 @@ use authly_providers_github::GitHubProvider;
 let provider = GitHubProvider::new(client_id, client_secret, callback_url);
 let flow = OAuth2Flow::new(provider);
 
-// Generate authorization URL
-let (auth_url, _csrf_state) = flow.initiate_auth(None);
+// 1. Initiate login: Generate authorization URL and CSRF state
+let (auth_url, csrf_state) = flow.initiate_login(&["user:email"], None);
+
+// ... redirect user to auth_url, then receive code and state in callback ...
+
+// 2. Finalize login: Exchange code for identity and tokens
+let (identity, token, local_user) = flow.finalize_login(
+    &code,
+    &received_state,
+    &expected_state,
+    None // PKCE verifier
+).await?;
+```
+
+### Example: Device Flow
+
+```rust
+use authly_flow::DeviceFlow;
+
+let flow = DeviceFlow::new(client_id, device_auth_url, token_url);
+
+// 1. Initiate device authorization
+let resp = flow.initiate_device_authorization(&["read", "write"]).await?;
+
+println!("Go to {} and enter code: {}", resp.verification_uri, resp.user_code);
+
+// 2. Poll for token
+let token = flow.poll_for_token(&resp.device_code, resp.interval).await?;
+```
+
+### Example: Client Credentials Flow
+
+```rust
+use authly_flow::ClientCredentialsFlow;
+
+let flow = ClientCredentialsFlow::new(client_id, client_secret, token_url);
+
+// Obtain an access token
+let token = flow.get_token(Some(&["api:read"])).await?;
+```
+
+### Example: Credentials Flow
+
+```rust
+use authly_flow::CredentialsFlow;
+// Assuming a provider that implements CredentialsProvider
+let flow = CredentialsFlow::new(my_credentials_provider);
+
+let (identity, local_user) = flow.authenticate(my_credentials).await?;
 ```
 
 ## Part of authly-rs