chore: sync develop to main

.github/workflows/ci.yml

@@ -2,8 +2,22 @@ name: CI
 on:
   push:
     branches: [develop]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'tutorials/**'
+      - 'examples/**/README.md'
+      - 'LICENSE'
+      - '.gitignore'
   pull_request:
     branches: [develop, main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'tutorials/**'
+      - 'examples/**/README.md'
+      - 'LICENSE'
+      - '.gitignore'
   workflow_dispatch:
     inputs:
       triggered-by:
@@ -13,10 +27,5 @@ on:
 jobs:
   build:
     uses: fireflyframework/.github/.github/workflows/java-ci.yml@main
-    permissions:
-      packages: read
-      contents: read
-      actions: write
     with:
       java-version: '25'
-    secrets: inherit

README.md

@@ -1,159 +1,95 @@
-# Firefly Framework - IDP Library
+# Firefly Framework - Identity Provider (IDP)
 
 [![CI](https://github.com/fireflyframework/fireflyframework-idp/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-idp/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Java](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://openjdk.org)
+[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot)
 
-A small, provider-agnostic interface to standardize Identity Provider (IdP) operations across platforms such as Keycloak, AWS Cognito, Okta, Auth0, and others. It exposes a consistent, reactive API so your application code remains clean and portable, while concrete implementations translate calls into provider‑specific requests.
+> Identity provider abstraction layer defining contracts for user management, authentication, and token operations.
+
+---
 
 ## Table of Contents
-- [1. Overview](#1-overview)
-- [2. Features](#2-features)
-- [3. Technology Stack](#3-technology-stack)
-- [4. Installation](#4-installation)
-- [5. Quick Start](#5-quick-start)
-- [6. API Summary](#6-api-summary)
-- [7. Implementation Notes](#7-implementation-notes)
-- [8. Versioning](#8-versioning)
-- [9. Contributing](#9-contributing)
-- [10. License](#10-license)
-
-## 1. Overview
-This library defines a single adapter interface, `IdpAdapter`, and a set of DTOs to model common identity workflows:
-- User authentication (login/refresh/logout)
-- Token introspection and user info retrieval
-- User management (create user, change/reset password)
-- MFA (challenge and verification)
-- Session and role management
-
-By targeting this interface, you can swap identity providers without changing the application logic.
-
-## 2. Features
-- Unified interface for common IdP operations
-- Reactive return types using Reactor `Mono` for async/non-blocking flows
-- DTOs tailored to typical OAuth2/OIDC and MFA scenarios
-- Spring-friendly responses via `ResponseEntity`
-
-## 3. Technology Stack
-- Java 25 (default, Java 21+ compatible)
-- Reactor Core / Spring WebFlux (`Mono`, `ResponseEntity`)
-- Lombok for DTO boilerplate reduction
-- Maven build
-
-## 4. Installation
-Add the dependency to your Maven project. Replace the version as appropriate.
+
+- [Overview](#overview)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Overview
+
+Firefly Framework IDP defines the port (adapter) contracts for identity provider integration across the Firefly ecosystem. It provides the `IdpAdapter` interface with comprehensive user management, authentication, token, and role management operations that concrete providers must implement.
+
+The module includes DTOs for all IDP operations including user creation, login, logout, token refresh, MFA challenges, role management, scope management, and session introspection. It is designed as a pure contract library with no implementation, serving as the dependency for all IDP provider modules.
+
+Provider implementations (AWS Cognito, Keycloak, Internal DB) are published as separate modules that implement the `IdpAdapter` interface.
+
+## Features
+
+- `IdpAdapter` interface defining all identity provider operations
+- User management DTOs: create, update, change password
+- Authentication DTOs: login, logout, token response, refresh
+- MFA support: challenge response, verification
+- Role and scope management contracts
+- Session introspection and token validation
+- Provider-agnostic design enabling swappable IDP backends
+
+## Requirements
+
+- Java 21+
+- Spring Boot 3.x
+- Maven 3.9+
+
+## Installation
 
 ```xml
 <dependency>
     <groupId>org.fireflyframework</groupId>
     <artifactId>fireflyframework-idp</artifactId>
-    <version>1.0.0-SNAPSHOT</version>
+    <version>26.01.01</version>
 </dependency>
 ```
 
-If you are using Gradle (Kotlin DSL):
-```kotlin
-implementation("org.fireflyframework:fireflyframework-idp:1.0.0-SNAPSHOT")
-```
-
-Note: This module provides only the abstraction (interface + DTOs). You will need an implementation module for your chosen provider.
-
-## 5. Quick Start
-1) Implement the `IdpAdapter` for your target IdP (e.g., Keycloak):
+## Quick Start
 
 ```java
-public class KeycloakIdpAdapter implements IdpAdapter {
-    @Override
-    public Mono<ResponseEntity<TokenResponse>> login(LoginRequest request) {
-        // Call Keycloak token endpoint and map response
-        return Mono.empty();
-    }
-
-    @Override
-    public Mono<ResponseEntity<TokenResponse>> refresh(RefreshRequest request) { return Mono.empty(); }
+import org.fireflyframework.idp.adapter.IdpAdapter;
+import org.fireflyframework.idp.dtos.*;
 
-    @Override
-    public void logout(String accessToken) { /* call provider logout/revoke */ }
+@Service
+public class AuthService {
 
-    @Override
-    public Mono<ResponseEntity<IntrospectionResponse>> introspect(String accessToken) { return Mono.empty(); }
+    private final IdpAdapter idpAdapter;
 
-    @Override
-    public Mono<ResponseEntity<UserInfoResponse>> getUserInfo(String accessToken) { return Mono.empty(); }
-
-    @Override
-    public Mono<ResponseEntity<CreateUserResponse>> createUser(CreateUserRequest request) { return Mono.empty(); }
+    public Mono<TokenResponse> login(LoginRequest request) {
+        return idpAdapter.login(request);
+    }
 
-    @Override
-    public void changePassword(ChangePasswordRequest request) { }
+    public Mono<CreateUserResponse> register(CreateUserRequest request) {
+        return idpAdapter.createUser(request);
+    }
+}
+```
 
-    @Override
-    public void resetPassword(String username) { }
+## Configuration
 
-    @Override
-    public Mono<ResponseEntity<MfaChallengeResponse>> mfaChallenge(String username) { return Mono.empty(); }
+No configuration is required for the contracts module. Configuration is provided by the specific IDP provider implementation.
 
-    @Override
-    public void mfaVerify(MfaVerifyRequest request) { }
+## Documentation
 
-    @Override
-    public void revokeRefreshToken(String refreshToken) { }
+No additional documentation available for this project.
 
-    @Override
-    public Mono<ResponseEntity<List<SessionInfo>>> listSessions(String userId) { return Mono.empty(); }
+## Contributing
 
-    @Override
-    public void revokeSession(String sessionId) { }
+Contributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests.
 
-    @Override
-    public Mono<ResponseEntity<List<String>>> getRoles(String userId) { return Mono.empty(); }
-}
-```
+## License
 
-2) Inject and use your implementation wherever needed:
-```java
-Mono<ResponseEntity<TokenResponse>> result = idpAdapter.login(
-    LoginRequest.builder()
-        .username("alice")
-        .password("password123")
-        .clientId("my-client")
-        .scope("openid profile email")
-        .build()
-);
-```
+Copyright 2024-2026 Firefly Software Solutions Inc.
 
-## 6. API Summary
-The main entry point is `org.fireflyframework.idp.adapter.IdpAdapter`.
-
-Basic operations:
-- `Mono<ResponseEntity<TokenResponse>> login(LoginRequest request)`
-- `Mono<ResponseEntity<TokenResponse>> refresh(RefreshRequest request)`
-- `void logout(String accessToken)`
-- `Mono<ResponseEntity<IntrospectionResponse>> introspect(String accessToken)`
-- `Mono<ResponseEntity<UserInfoResponse>> getUserInfo(String accessToken)`
-- `Mono<ResponseEntity<CreateUserResponse>> createUser(CreateUserRequest request)`
-
-Advanced operations:
-- `void changePassword(ChangePasswordRequest request)`
-- `void resetPassword(String username)`
-- `Mono<ResponseEntity<MfaChallengeResponse>> mfaChallenge(String username)`
-- `void mfaVerify(MfaVerifyRequest request)`
-- `void revokeRefreshToken(String refreshToken)`
-- `Mono<ResponseEntity<List<SessionInfo>>> listSessions(String userId)`
-- `void revokeSession(String sessionId)`
-- `Mono<ResponseEntity<List<String>>> getRoles(String userId)`
-
-DTOs are located under `org.fireflyframework.idp.dtos` and cover requests and responses for the above methods.
-
-## 7. Implementation Notes
-- Error Handling: Return appropriate HTTP status codes in `ResponseEntity` (e.g., 401 for invalid credentials, 400 for invalid requests, 500 for unexpected provider errors). Wrap provider errors consistently.
-- Security: Never log secrets (passwords, client secrets, tokens). Consider encrypting at rest and masking logs.
-- Threading: Since the API is reactive, avoid blocking calls. If the provider SDK is blocking, delegate to bounded elastic schedulers or use non-blocking HTTP clients.
-- Portability: Keep provider-specific objects within your implementation; expose only the DTOs defined in this library.
-
-## 8. Versioning
-This project follows semantic versioning as much as possible during its evolution. Breaking changes in interfaces or DTOs will result in a major version increment.
-
-## 9. Contributing
-Contributions are welcome. Please open an issue to discuss proposed changes before submitting a PR. Ensure code compiles and includes documentation updates when necessary.
-
-## 10. License
-This project is licensed under the terms of the LICENSE file included in the repository.
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.