Feature: Client Credentials Flow Backend

Author: stimpy77

DEVPLAN.md

@@ -398,7 +398,7 @@ This document provides a detailed breakdown of tasks, components, features, test
 ### Feature: Client Credentials Flow Backend
 
 *   **Component:** Token Endpoint (Grant Type: `client_credentials`)
-    - [ ] Extend `POST /token` endpoint to handle `grant_type=client_credentials`.
+    - [x] Extend `POST /token` endpoint to handle `grant_type=client_credentials`.
         *   *Guidance:* 
             * Accepts parameters: `grant_type`, `client_id`, `client_secret`, `scope` (optional).
         *   *Guidance:* 
@@ -412,12 +412,13 @@ This document provides a detailed breakdown of tasks, components, features, test
         *   *Guidance:* 
             * Return access token in the response.
 *   **Test Case (Integration):**
-    - [ ] `POST /token` with `grant_type=client_credentials` and valid client credentials 
+    - [x] `POST /token` with `grant_type=client_credentials` and valid client credentials 
           returns an access token.
-    - [ ] Token represents the client (e.g., `sub` claim is `client_id`).
-    - [ ] Request fails if client credentials are invalid.
-    - [ ] Request fails if requested scopes are not allowed for the client.
-- [ ] **Update README.md** with details on `/token` endpoint for `client_credentials` grant type.
+    - [x] Token represents the client (e.g., `sub` claim is `client_id`).
+    - [x] Request fails if client credentials are invalid.
+    - [x] Request fails if requested scopes are not allowed for the client.
+    - [x] Client authentication works with both Basic Auth header and request body parameters.
+- [x] **Update README.md** with details on `/token` endpoint for `client_credentials` grant type.
 
 ---
 

LLMINDEX.md

@@ -44,6 +44,8 @@ things are or how they were supposed to work.
             *   Added automatic cleanup/expiry for authorization codes (`src/CoreIdent.Storage.EntityFrameworkCore/Services/AuthorizationCodeCleanupService.cs`).
             *   Ensured robust concurrency handling in `IAuthorizationCodeStore` implementations.
         *   **In Progress:** Client Credentials Flow, Discovery endpoints.
+        *   **Completed:** Client Credentials Flow (`grant_type=client_credentials` added to `/token` endpoint logic).
+        *   **Next:** Discovery endpoints.
     *   **Phase 4 (Future):** User Interaction & External Integrations (Consent, UI, MFA, Passwordless).
     *   **Phase 5 (Future):** Advanced Features & Polish (More Flows, Extensibility, Templates).
 *   **Reference:** `DEVPLAN.md`: Detailed breakdown of tasks for each phase.
@@ -112,6 +114,7 @@ This is the central library containing the core logic, interfaces, and models.
             *   Maps `GET /authorize` endpoint. Includes robust concurrency handling for code generation.
             *   Enhances `POST /token` endpoint to handle `grant_type=authorization_code` with PKCE validation.
             *   Token refresh endpoint (`POST /token/refresh`) implements token theft detection with configurable behavior.
+            *   Added `client_credentials` grant type handling to `/token` endpoint.
 
 ## 6. EF Core Storage Project Details: `src\CoreIdent.Storage.EntityFrameworkCore`
 
@@ -129,6 +132,8 @@ This is the central library containing the core logic, interfaces, and models.
         *   `AuthorizationCodeCleanupService.cs`: Background service that automatically removes expired authorization codes.
     *   `Extensions`: Contains DI extensions.
         *   `CoreIdentEntityFrameworkCoreExtensions.cs`: Contains `AddCoreIdentEntityFrameworkStores` extension to register EF Core stores (Scoped) with optional token and authorization code cleanup services.
+    *   **Next Steps:** Client Credentials Flow, Discovery endpoints
+    *   **Next Steps:** Discovery endpoints
 
 ## 6.5 Delegated User Store Adapter Project Details: `src\CoreIdent.Adapters.DelegatedUserStore`
 
@@ -145,7 +150,7 @@ This is the central library containing the core logic, interfaces, and models.
     *   `AuthorizationCodeFlowTests.cs`: Tests for the Authorization Code Flow with PKCE (including happy path and negative path tests).
     *   `RefreshTokenEndpointTests.cs`: Tests for the token refresh endpoint, including token theft detection scenarios.
 *   **`CoreIdent.TestHost`:** A helper project providing a shared `WebApplicationFactory` for integration tests.
-*   **Frameworks:** Uses `xUnit` as the test runner and `Shouldly` for assertions. Mocking is done using `Moq`.
+*   **Frameworks:** Uses `xUnit` (v3 - see [What's New](https://xunit.net/docs/getting-started/v3/whats-new) and [Migration Guide](https://xunit.net/docs/getting-started/v3/migration)) as the test runner and `Shouldly` for assertions. Mocking is done using `Moq`.
 
 ## 8. Documentation & Root Files
 
@@ -190,7 +195,10 @@ This is the central library containing the core logic, interfaces, and models.
             *   Enhanced `CoreIdentOptionsValidator` to validate token security configuration, ensuring consistent security behavior.
             *   Implemented secure hashing of refresh token handles using SHA-256 with user/client ID salting.
             *   Added support for storing both raw (legacy) and hashed token handles during migration period.
-    *   **Next Steps:** Client Credentials Flow, Discovery endpoints
+        *   **Completed:** Client Credentials Flow (`grant_type=client_credentials` added to `/token` endpoint logic).
+        *   **Next:** Discovery endpoints.
+    *   **Phase 4 (Future):** User Interaction & External Integrations (Consent, UI, MFA, Passwordless).
+    *   **Phase 5 (Future):** Advanced Features & Polish (More Flows, Extensibility, Templates).
 
 ## 10. Conclusion
 

README.md

@@ -53,7 +53,7 @@ Tired of wrestling with complex identity vendors or rolling your own auth from s
 
 **Where CoreIdent is heading (Future Phases):**
 
-*   **Full OAuth 2.0 / OIDC Server:** Implementing remaining standard flows (Client Credentials, Implicit, Hybrid) for web apps, SPAs, mobile apps, and APIs.
+*   **Full OAuth 2.0 / OIDC Server:** Implementing remaining standard flows (~~Client Credentials~~, Implicit, Hybrid) for web apps, SPAs, mobile apps, and APIs.
 *   **OIDC Compliance:** Discovery (`/.well-known/openid-configuration`), JWKS (`/.well-known/jwks.json`), ID Tokens.
 *   **User Interaction:** Consent screens, standard logout endpoints.
 *   **Extensible Provider Model:**
@@ -69,6 +69,11 @@ Tired of wrestling with complex identity vendors or rolling your own auth from s
     *   Secure token storage and management
     *   Offline authentication support
 *   **Tooling:** `dotnet new` templates, comprehensive documentation.
+*   **(In Progress)** Client Credentials Flow.
+*   **(Completed)** Client Credentials Flow (`/auth/token` grant type `client_credentials`).
+*   **(In Progress)** OIDC Discovery & JWKS Endpoints.
+
+For more details on these features, see the [Developer Training Guide](./docs/Developer_Training_Guide.md).
 
 **Is this a replacement for IdentityServer?**
 
@@ -431,8 +436,13 @@ app.UseHttpsRedirection();
 app.UseAuthentication(); // Must be called before UseAuthorization
 app.UseAuthorization();
 
-// Map CoreIdent endpoints (default prefix is /auth)
-app.MapCoreIdentEndpoints("/auth"); // Use basePath parameter to change, e.g., app.MapCoreIdentEndpoints(basePath: "/identity");
+// Map CoreIdent endpoints
+app.MapCoreIdentEndpoints(options =>
+{
+    // Example: Customize the base path or specific endpoints
+    // options.BasePath = "/identity";
+    // options.RegisterPath = "signup";
+});
 
 // Map your application's endpoints/controllers
 app.MapGet("/", () => "Hello World!");
@@ -447,9 +457,9 @@ app.Run();
 
 ### 4. Core Functionality Available Now (Phase 3 In Progress)
 
-With the setup above, the following CoreIdent endpoints are available (default prefix `/auth`):
+With the setup above, the following CoreIdent endpoints are available (default prefix `/auth`, configurable via `MapCoreIdentEndpoints`):
 
-*   `POST /auth/register`: Register a new user (requires non-delegated `IUserStore`, e.g., EF Core, or `CreateUserAsync` delegate).
+*   `POST /auth/register` (or configured path): Register a new user.
     *   **Request Body**: `{ "email": "user@example.com", "password": "YourPassword123!" }`
     *   **Response Status Codes**: `201 Created`, `400 Bad Request`, `409 Conflict`
     *   **Usage Example (curl)**:
@@ -459,7 +469,7 @@ With the setup above, the following CoreIdent endpoints are available (default p
           -d '{"email": "user@example.com", "password": "YourSecurePassword123!"}'
         ```
 
-*   `POST /auth/login`: Authenticates a user with email/password and issues JWT tokens.
+*   `POST /auth/login` (or configured path): Authenticates a user with email/password and issues JWT tokens.
     *   **Request Body**: `{ "email": "user@example.com", "password": "YourPassword123!" }`
     *   **Response Status Codes**: `200 OK`, `400 Bad Request`, `401 Unauthorized`, `500 Internal Server Error`
     *   **Response Body**:
@@ -480,22 +490,26 @@ With the setup above, the following CoreIdent endpoints are available (default p
           -d '{"email": "user@example.com", "password": "YourSecurePassword123!"}'
         ```
 
-*   `POST /auth/token/refresh`: Exchange a valid refresh token for new tokens (uses `IRefreshTokenStore`).
-    *   **Request Body**: `{ "refreshToken": "abcdef123456..." }`
-    *   **Response Body**: (Same as login)
+*   `POST /auth/token` (grant_type=refresh_token) (or configured path): Exchange a valid refresh token for new tokens.
+    *   **Request Body (form-urlencoded)**: `grant_type=refresh_token&refresh_token=abcdef123456...`
+    *   **Response Body**: (Same as login, potentially without refresh token depending on config/flow)
     *   **Security**: Implements refresh token rotation and **token theft detection** (family tracking & revocation) by default. You can opt-out via `CoreIdentOptions.TokenSecurity.EnableTokenFamilyTracking = false`.
 
 **OAuth 2.0 / OIDC Endpoints (Phase 3):**
 
-*   `GET /auth/authorize`: Initiates the Authorization Code flow. Validates the request, authenticates the user, and redirects back with an authorization code.
+*   `GET /auth/authorize` (or configured path): Initiates the Authorization Code flow.
     *   Required parameters: `client_id`, `redirect_uri`, `response_type=code`, `scope`
     *   Recommended parameters: `state`, `nonce`
     *   PKCE parameters: `code_challenge`, `code_challenge_method=S256`
     *   Example: `/auth/authorize?client_id=my-client&response_type=code&redirect_uri=https://my-app.com/callback&scope=openid%20profile&state=abc123&code_challenge=<challenge>&code_challenge_method=S256`
-*   `POST /auth/token` (grant_type=authorization_code): Exchanges an authorization code for tokens.
+*   `POST /auth/token` (grant_type=authorization_code) (or configured path): Exchanges an authorization code for tokens.
     *   Required parameters (form-encoded): `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier` (for PKCE)
-    *   Confidential clients also require authentication.
+    *   Confidential clients also require authentication (Basic Auth or request body).
     *   Returns: `{ "access_token": "...", "token_type": "Bearer", "expires_in": 900, "refresh_token": "...", "id_token": "..." }`
+*   `POST /auth/token` (grant_type=client_credentials) (or configured path): Issues an access token directly to a confidential client.
+    *   Required parameters (form-encoded): `grant_type=client_credentials`, `scope` (optional)
+    *   Requires client authentication (Basic Auth header OR `client_id`/`client_secret` in request body).
+    *   Returns: `{ "access_token": "...", "token_type": "Bearer", "expires_in": 900, "scope": "..." }` (No refresh token)
 
 **Storage:**
 *   **EF Core:** Provides persistence for users, refresh tokens, clients, scopes, **and authorization codes**. Requires `CoreIdent.Storage.EntityFrameworkCore` and DB migrations. **Expired authorization codes are cleaned up automatically by a background service.**
@@ -574,56 +588,4 @@ Contributions, feedback, and ideas are highly welcome! Please refer to the (upco
 
 ### Why does the DI registration order matter?
 **Order is critical** because:
-- `AddCoreIdent()` registers the core services and default (in-memory) stores.
-- `AddDbContext<YourDbContext>()` registers your EF Core context in the DI container.
-- `AddCoreIdentEntityFrameworkStores<YourDbContext>()` replaces the in-memory stores with EF Core-backed implementations, which depend on your DbContext being registered first.
-
-If you call `AddCoreIdentEntityFrameworkStores` before `AddDbContext`, the EF Core stores will not be able to resolve the context and will fail at runtime.
-
-### Common Issues & Solutions
-
-- **Error: "No service for type 'YourDbContext' has been registered."**
-  - **Solution:** Ensure you called `AddDbContext<YourDbContext>()` *before* `AddCoreIdentEntityFrameworkStores<YourDbContext>()`.
-
-- **Error: "Table 'Users'/'RefreshTokens' does not exist" or similar database errors**
-  - **Solution:** You likely have not run EF Core migrations. See the migration instructions below.
-
-- **Error: "Cannot access a disposed object" (when using SQLite in-memory for tests)**
-  - **Solution:** Ensure the SQLite connection remains open for the lifetime of your test host. See integration test examples for details.
-
-### EF Core Migration Process (Quick Reference)
-
-1. **Install EF Core CLI tools (if not already):**
-   ```bash
-   dotnet tool install --global dotnet-ef
-   ```
-2. **Add a migration:**
-   ```bash
-   dotnet ef migrations add InitialCoreIdentSchema --context YourApplicationDbContext --project src/CoreIdent.Storage.EntityFrameworkCore --startup-project src/YourWebAppProject -o Data/Migrations
-   ```
-   - Replace `YourApplicationDbContext` with your DbContext class name.
-   - Adjust `--project` and `--startup-project` paths as needed.
-3. **Apply the migration:**
-   ```bash
-   dotnet ef database update --context YourApplicationDbContext --project src/CoreIdent.Storage.EntityFrameworkCore --startup-project src/YourWebAppProject
-   ```
-
-**Official EF Core Migrations Documentation:**
-- [EF Core Migrations Guide (Microsoft Docs)](https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations/?tabs=dotnet-core-cli)
-
-### Sample Migration Output
-When you run `dotnet ef migrations add InitialCoreIdentSchema`, you should see output similar to:
-```
-Build started...
-Build succeeded.
-To undo this action, use 'ef migrations remove'
-Done. To undo this action, use 'ef migrations remove'
-```
-And after `dotnet ef database update`:
-```
-Build started...
-Build succeeded.
-Applying migration '20250413033857_InitialCoreIdentSchema'.
-Done.
-```
-If you see errors, double-check your DI registration order and that your DbContext is correctly configured and referenced.
+- `

RELEASE_NOTES.md

@@ -1,5 +1,8 @@
 # CoreIdent Release Notes
 
+## Version 0.3.4
+- **Client Credentials Flow:** Implemented `POST /token` (with `grant_type=client_credentials`) endpoint to support machine-to-machine authentication. Requires `IClientStore` implementation (e.g., EF Core). Validates client credentials and allowed scopes, issuing an access token representing the client.
+
 ## Version 0.3.3
 - Enhance `CoreIdentOptionsValidator` to include more comprehensive checks (e.g., valid Issuer URI, reasonable lifetimes).
 

nextfeature.instruction

@@ -0,0 +1,8 @@
+Review @Project_Overview.md @Technical_Plan.md @README.md @LLMINDEX.md @DEVPLAN.md 
+
+Then let's implement the next unimplemented feature in the DEVPLAN checklist.  
+- If you are going to create new files, do not presume the LLMINDEX.md is up-to-date, meaning always scan the project for similar looking files or for files that contain multiple classes that might have what you might be otherwise creating.
+- Always create unit or integration tests for every new feature.
+- Always run `dotnet test` and debug the tests before calling the feature completed
+- Clean up any lingering build warnings
+- The feature isn't done until the checklist item(s) in DEVPLAN.md is checked (edit the file)

src/CoreIdent.Core/Configuration/CoreIdentRouteOptions.cs

@@ -0,0 +1,93 @@
+using System;
+
+namespace CoreIdent.Core.Configuration;
+
+/// <summary>
+/// Configures the routes for CoreIdent endpoints.
+/// </summary>
+public class CoreIdentRouteOptions
+{
+    /// <summary>
+    /// The base path for all CoreIdent endpoints. Defaults to "/auth".
+    /// Must start with a '/'.
+    /// </summary>
+    public string BasePath { get; set; } = "/auth";
+
+    /// <summary>
+    /// Path for the user registration endpoint. Defaults to "register". Relative to BasePath.
+    /// </summary>
+    public string RegisterPath { get; set; } = "register";
+
+    /// <summary>
+    /// Path for the user login endpoint. Defaults to "login". Relative to BasePath.
+    /// </summary>
+    public string LoginPath { get; set; } = "login";
+
+    /// <summary>
+    /// Path for the token endpoint (issuance and refresh). Defaults to "token". Relative to BasePath.
+    /// </summary>
+    public string TokenPath { get; set; } = "token";
+
+    /// <summary>
+    /// Path for the token refresh specific endpoint (legacy/alternative). Defaults to "token/refresh". Relative to BasePath.
+    /// Note: The main /token endpoint is preferred for refresh grant_type.
+    /// </summary>
+    public string RefreshTokenPath { get; set; } = "token/refresh";
+
+    /// <summary>
+    /// Path for the OAuth/OIDC authorization endpoint. Defaults to "authorize". Relative to BasePath.
+    /// </summary>
+    public string AuthorizePath { get; set; } = "authorize";
+
+    /// <summary>
+    /// Path for the OIDC UserInfo endpoint. Defaults to "userinfo". Relative to BasePath.
+    /// </summary>
+    public string UserInfoPath { get; set; } = "userinfo"; // Not yet implemented
+
+    /// <summary>
+    /// Path for the OIDC Discovery configuration endpoint. Defaults to ".well-known/openid-configuration". Relative to the root, not BasePath.
+    /// </summary>
+    public string DiscoveryPath { get; set; } = ".well-known/openid-configuration"; // Not yet implemented
+
+    /// <summary>
+    /// Path for the OIDC JWKS endpoint. Defaults to ".well-known/jwks.json". Relative to the root, not BasePath.
+    /// </summary>
+    public string JwksPath { get; set; } = ".well-known/jwks.json"; // Not yet implemented
+
+    /// <summary>
+    /// Path for the consent endpoint. Defaults to "consent". Relative to BasePath.
+    /// </summary>
+    public string ConsentPath { get; set; } = "consent"; // Not yet implemented
+
+    /// <summary>
+    /// Path for the end session/logout endpoint. Defaults to "endsession". Relative to BasePath.
+    /// </summary>
+    public string EndSessionPath { get; set; } = "endsession"; // Not yet implemented
+
+    // Helper method to combine BasePath and relative path
+    internal string Combine(string relativePath)
+    {
+        if (string.IsNullOrWhiteSpace(relativePath))
+        {
+            throw new ArgumentException("Relative path cannot be null or whitespace.", nameof(relativePath));
+        }
+
+        // Handle paths that should be relative to root, not base path
+        if (relativePath.StartsWith(".well-known/"))
+        {
+             // Ensure it starts with exactly one '/'
+            return "/" + relativePath.TrimStart('/');
+        }
+
+        if (string.IsNullOrWhiteSpace(BasePath) || !BasePath.StartsWith("/"))
+        {
+            throw new InvalidOperationException($"{nameof(BasePath)} must be configured and start with a '/'. Current value: '{BasePath}'");
+        }
+
+        // Ensure BasePath ends with a single '/' and relativePath does not start with one
+        var basePathNormalized = BasePath.TrimEnd('/') + "/";
+        var relativePathNormalized = relativePath.TrimStart('/');
+
+        return basePathNormalized + relativePathNormalized;
+    }
+}