Refactor Bewit token extraction; unify extraction options, update middleware integration, and enhance configuration support in appsettings.json

Co-authored-by: Copilot <copilot@github.com>

Author: glucaci

README.md

@@ -298,9 +298,64 @@ public static async Task<NominationDto> AssignNomineeAsync(
 ### Setup
 
 ```csharp
-app.UseBewitTokenHeaderExtraction();
+app.UseBewitTokenExtraction();
 ```
 
+## HTTP Endpoint Integration
+
+```bash
+dotnet add package Bewit.Http
+```
+
+Protect minimal API or middleware-based endpoints:
+```csharp
+app.UseBewitEndpointAuthorization<MyPayload>();
+```
+
+The middleware validates the token from the configured header or query parameter and makes the payload available via `GetBewitPayload<T>()`.
+
+## Token Extraction
+
+All extensions (HotChocolate, Http, Mvc) read the bewit token from the same configurable sources: an HTTP **header** and/or a **query parameter**. Header takes precedence when both are present.
+
+Defaults match the v6.x behavior:
+- Header: `bewitToken`
+- Query parameter: `bewit`
+
+### Code configuration
+```csharp
+services.AddBewit(bewit =>
+{
+    bewit.ConfigureTokenExtraction(o =>
+    {
+        o.HeaderName = "X-Custom-Token";
+        o.QueryParamName = "token";
+    });
+
+    bewit.AddPayload<string>();
+});
+```
+
+### appsettings.json
+```json
+{
+  "Bewit:TokenExtraction": {
+    "HeaderName": "X-Custom-Token",
+    "QueryParamName": "token"
+  }
+}
+```
+
+```csharp
+services.AddBewit(bewit =>
+{
+    bewit.BindTokenExtractionConfiguration("Bewit:TokenExtraction");
+    bewit.AddPayload<string>();
+});
+```
+
+Both can be combined — `BindTokenExtractionConfiguration` loads from appsettings first, then `ConfigureTokenExtraction` overrides specific values (standard .NET options layering).
+
 ## MVC Integration
 
 ```bash
@@ -325,9 +380,9 @@ public IActionResult Download(string id) { ... }
 | `Bewit.Extensions.Mvc` | MVC filters and parameter binding |
 | `Bewit.Http` | Minimal API endpoint authorization |
 
-## Migration from v1.x
+## Migration
 
-See [Migration Guide](docs/migration-guide.md).
+See [Migration Guide v7](docs/migration-guide-v7.md).
 
 ## Community
 

docs/migration-guide-v7.md

@@ -16,6 +16,8 @@
 | MongoDB Driver | 2.x | 3.0+ |
 | HttpContextAccessor | Manual `services.AddHttpContextAccessor()` | Auto-registered by `AddBewit()` |
 | Startup validation | None | `ServerControlled` without nonce repo fails at startup |
+| Token extraction | Hardcoded header/query per extension | Unified `BewitTokenExtractionOptions` with header + query fallback |
+| HotChocolate setup | `UseBewitTokenHeaderExtraction()` | `UseBewitTokenExtraction()` |
 
 ## DI Registration Migration
 
@@ -245,3 +247,55 @@ services.AddBewit(bewit =>
 | `PayloadBuilder.UseSlidingWindow(TimeSpan)` | `ConfigureOptions(o => o.SlidingWindow = ...)` |
 | `PayloadBuilder.WithTokenDuration(TimeSpan)` | `ConfigureOptions(o => o.TokenDuration = ...)` |
 | `UseMongoPersistence(config, ...)` | `UseMongoDb(...)` on `BewitBuilder` or `PayloadBuilder<T>` |
+| `BewitTokenConstants` | `BewitTokenExtractionOptions` (configurable via options pattern) |
+| `UseBewitTokenHeaderExtraction()` | `UseBewitTokenExtraction()` |
+
+## Token Extraction Migration
+
+In v6.x, the HotChocolate extension used a hardcoded `bewitToken` header and the Http extension used a hardcoded `bewit` query parameter. These were not configurable.
+
+In v7.0, all extensions (HotChocolate, Http, Mvc) use `BewitTokenExtractionOptions` — a shared, configurable options class that follows the standard .NET options pattern.
+
+### Before (v6.x)
+```csharp
+// HotChocolate — header only, hardcoded name
+app.UseBewitTokenHeaderExtraction();
+
+// Http — query param only, hardcoded name
+app.UseBewitEndpointAuthorization<T>();
+
+// Mvc — query param only, hardcoded name
+[BewitUrlAuthorization]
+```
+
+### After (v7.0)
+```csharp
+// HotChocolate — reads header first, then query param
+app.UseBewitTokenExtraction();
+
+// Http — reads header first, then query param
+app.UseBewitEndpointAuthorization<T>();
+
+// Mvc — reads header first, then query param
+[BewitUrlAuthorization]
+```
+
+All three now check **header first, then fall back to query parameter**. Default names are unchanged (`bewitToken` header, `bewit` query param), so existing consumers work without config changes.
+
+### Custom token extraction
+```csharp
+services.AddBewit(bewit =>
+{
+    bewit.ConfigureTokenExtraction(o =>
+    {
+        o.HeaderName = "X-Custom-Token";
+        o.QueryParamName = "token";
+    });
+    // or from appsettings.json:
+    bewit.BindTokenExtractionConfiguration("Bewit:TokenExtraction");
+
+    bewit.AddPayload<string>();
+});
+```
+
+`BewitTokenExtractionOptions` supports full .NET options layering: `Bind` → `Configure` → `PostConfigure`, with `ValidateDataAnnotations` and `ValidateOnStart`.

src/Core/BewitBuilder.cs

@@ -14,6 +14,8 @@ public sealed class BewitBuilder
 
     internal Action<BewitTokenExtractionOptions>? TokenExtractionAction { get; private set; }
 
+    internal string? TokenExtractionConfigSection { get; private set; }
+
     internal List<Action<IServiceCollection>> PayloadRegistrations { get; } = [];
 
     internal BewitBuilder(IServiceCollection services)
@@ -65,4 +67,11 @@ public BewitBuilder ConfigureTokenExtraction(
 
         return this;
     }
+
+    public BewitBuilder BindTokenExtractionConfiguration(string sectionPath)
+    {
+        TokenExtractionConfigSection = sectionPath;
+
+        return this;
+    }
 }

src/Core/BewitServiceCollectionExtensions.cs

@@ -15,17 +15,24 @@ public static IServiceCollection AddBewit(
         services.TryAddSingleton<IVariablesProvider, VariablesProvider>();
         services.AddHttpContextAccessor();
 
-        if (builder.TokenExtractionAction is not null)
+        var optionsBuilder = services
+            .AddOptions<BewitTokenExtractionOptions>();
+
+        if (builder.TokenExtractionConfigSection is not null)
         {
-            services.Configure(builder.TokenExtractionAction);
+            optionsBuilder.BindConfiguration(
+                builder.TokenExtractionConfigSection);
         }
-        else
+
+        if (builder.TokenExtractionAction is not null)
         {
-            services.TryAddSingleton(
-                Microsoft.Extensions.Options.Options.Create(
-                    new BewitTokenExtractionOptions()));
+            optionsBuilder.Configure(builder.TokenExtractionAction);
         }
 
+        optionsBuilder
+            .ValidateDataAnnotations()
+            .ValidateOnStart();
+
         foreach (Action<IServiceCollection> registration in builder.PayloadRegistrations)
         {
             registration(services);

src/Core/BewitTokenExtractionOptions.cs

@@ -1,10 +1,14 @@
+using System.ComponentModel.DataAnnotations;
+
 namespace Bewit;
 
 public sealed class BewitTokenExtractionOptions
 {
+    [Required]
     public string HeaderName { get; set; } = "bewitToken";
 
+    [Required]
     public string QueryParamName { get; set; } = "bewit";
 
-    internal string ContextKey { get; set; } = "bewitToken";
+    internal string ContextKey => HeaderName;
 }

src/Extensions.HotChocolate/BewitHotChocolateServiceCollectionExtensions.cs

@@ -10,11 +10,4 @@ public static IApplicationBuilder UseBewitTokenExtraction(
     {
         return app.UseMiddleware<BewitTokenExtractionMiddleware>();
     }
-
-    [Obsolete("Use UseBewitTokenExtraction instead.")]
-    public static IApplicationBuilder UseBewitTokenHeaderExtraction(
-        this IApplicationBuilder app)
-    {
-        return app.UseBewitTokenExtraction();
-    }
 }

src/Extensions.HotChocolate/BewitTokenConstants.cs

@@ -113,7 +113,7 @@ public async Task InvokeAsync_WithCustomHeaderName_ShouldReadFromCustomHeader()
 
         await middleware.InvokeAsync(context);
 
-        context.Items["bewitToken"].Should().Be("custom-header-token");
+        context.Items["X-My-Token"].Should().Be("custom-header-token");
     }
 
     [Fact]