Various updates

Author: maartenba

src/content/docs/accesstokenmanagement/advanced/client-assertions.mdx

@@ -9,14 +9,13 @@ redirect_from:
 ---
 import { Tabs, TabItem } from "@astrojs/starlight/components";
 
-If your token client is using a client assertion instead of a shared secret, you can provide the assertion in two ways
+If your token client is using a client assertion instead of a shared secret, you can provide the assertion in two ways:
 
-* use the request parameter mechanism to pass a client assertion to the management
-* implement the `IClientAssertionService` interface to centralize client assertion creation
+* Use the request parameter mechanism to pass a client assertion to the management
+* Implement the `IClientAssertionService` interface to centralize client assertion creation
 
 Here's a sample client assertion service using the Microsoft JWT library:
 
-
 {/* prettier-ignore */}
 <Tabs syncKey="atm">
   {/* prettier-ignore */}

src/content/docs/accesstokenmanagement/advanced/client-credentials.mdx

@@ -9,7 +9,8 @@ redirect_from:
 ---
 import { Tabs, TabItem } from "@astrojs/starlight/components";
 
-The most common way to use the access token management for [machine-to-machine communication](/accesstokenmanagement/workers) - however, you may want to customize certain aspects of it. Here's what you can do.
+The most common way to use the access token management for [machine-to-machine communication](/accesstokenmanagement/workers).
+However, you may want to customize certain aspects of it.
 
 ## Client Options
 

src/content/docs/accesstokenmanagement/advanced/dpop.md

@@ -8,13 +8,14 @@ redirect_from:
   - /foss/accesstokenmanagement/advanced/dpop/
 ---
 
-[DPoP](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) specifies how to bind an asymmetric key stored within a JSON Web Key (JWK) to an access token. This will make the access token bound to the key such that if the access token were to leak, it cannot be used without also having access to the private key of the corresponding JWK.
+[DPoP](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) specifies how to bind an asymmetric key stored within a JSON Web Key (JWK) to an access token. 
+This will make the access token bound to the key such that if the access token were to leak, it cannot be used without also having access to the private key of the corresponding JWK.
 
-The "Duende.AccessTokenManagement" library supports DPoP.
+The Duende.AccessTokenManagement library supports DPoP.
 
 ## DPoP Key
 
-The main piece that your hosting application needs to concern itself with is how to obtain (and manage) the DPoP key. This key (and signing algorithm) will be either an "RS", "PS", or "ES" style key, and needs to be in the form of a JSON Web Key (or JWK). Consult the specification for more details.
+The main piece that your hosting application needs to concern itself with is how to get (and manage) the DPoP key. This key (and signing algorithm) will be either an "RS", "PS", or "ES" style key, and needs to be in the form of a JSON Web Key (or JWK). Consult the specification for more details.
 
 The creation and management of this DPoP key is up to the policy of the client. For example is can be dynamically created when the client starts up, and can be periodically rotated. The main constraint is that it must be stored for as long as the client uses any access tokens (and possibly refresh tokens) that they are bound to, which this library will manage for you.
 
@@ -73,11 +74,11 @@ When using DPoP and `AddOpenIdConnectAccessTokenManagement`, this library will a
 
 ## Proof Tokens At The API
 
-Once the library has obtained a DPoP bound access token for the client, then if your application is using any of the `HttpClient` client factory helpers (e.g. `AddClientCredentialsHttpClient` or `AddUserAccessTokenHttpClient`) then those outbound HTTP requests will automatically include a DPoP proof token for the associated DPoP access token.
+Once the library has gotten a DPoP bound access token for the client, then if your application is using any of the `HttpClient` client factory helpers (e.g. `AddClientCredentialsHttpClient` or `AddUserAccessTokenHttpClient`) then those outbound HTTP requests will automatically include a DPoP proof token for the associated DPoP access token.
 
 ## Considerations
 
 A point to keep in mind when using DPoP and `AddOpenIdConnectAccessTokenManagement` is that the DPoP proof key is created per user session. 
 This proof key must be store somewhere, and the `AuthenticationProperties` used by both the OIDC and cookie handlers is what is used to store this key.
 This implies that the OIDC `state` parameter will increase in size, as well the resultant cookie that represents the user's session.
-The storage of each of these can be customized with the properties on the options `StateDataFormat` and `SessionStore` respectively.
+The storage for each of these can be customized with the properties on the options `StateDataFormat` and `SessionStore` respectively.

src/content/docs/accesstokenmanagement/blazor-server.md

@@ -19,7 +19,7 @@ This means:
 
 Fortunately, `Duende.AccessTokenManagement` provides a straightforward solution to these problems. Also see the [*BlazorServer* sample](https://github.com/DuendeSoftware/foss/tree/main/access-token-management/samples/BlazorServer) for source code of a full example.
 
-## Token storage
+## Token Storage
 
 Since the tokens cannot be managed in the authentication session, you need to store them somewhere else. The options include an in-memory data structure, a distributed cache like redis, or a database. Duende.AccessTokenManagement describes this store for tokens with the *IUserTokenStore* interface. In non-blazor scenarios, the default implementation that stores the tokens in the session is used. In your Blazor server application, you'll need to decide where you want to store the tokens and implement the store interface.
 

src/content/docs/accesstokenmanagement/index.mdx

@@ -12,17 +12,16 @@ import { CardGrid, LinkCard } from "@astrojs/starlight/components";
 
 The `Duende.AccessTokenManagement` library provides automatic access token management features for .NET worker and ASP.NET Core web applications:
 
-- automatic acquisition and lifetime management of client credentials based access tokens for machine-to-machine communication (using the `Duende.AccessTokenManagement` package)
-- automatic access token lifetime management using a refresh token for API calls on behalf of the currently logged-in user (using the `Duende.AccessTokenManagement.OpenIdConnect` package)
-- revocation of access tokens
+- Automatic acquisition and lifetime management of client credentials based access tokens for machine-to-machine communication (using the `Duende.AccessTokenManagement` package)
+- Automatic access token lifetime management using a refresh token for API calls on behalf of the currently logged-in user (using the `Duende.AccessTokenManagement.OpenIdConnect` package)
+- Revocation of access tokens
 
-:::note
-    Duende.AccessTokenManagement version 4 (currently in preview 2) brings significant improvements, but also several breaking
-    changes. Please see the [migration guide](/accesstokenmanagement/upgrading/atm-v3-to-v4/) and [release notes](https://github.com/DuendeSoftware/foss/releases/tag/atm-4.0.0-Preview.2).
+:::note[Duende.AccessTokenManagement version 4 preview]
+Duende.AccessTokenManagement version 4 (preview) brings significant improvements, but also several breaking
+changes. Please see the [migration guide](/accesstokenmanagement/upgrading/atm-v3-to-v4/) and [release notes](https://github.com/DuendeSoftware/foss/releases/tag/atm-4.0.0-Preview.2).
 :::
-    
 
-## Machine-to-machine token management
+## Machine-To-Machine Token Management
 
 To get started, install the NuGet Package:
 
@@ -45,7 +44,7 @@ See [Service Workers and Background Tasks](/accesstokenmanagement/workers.md) fo
     />
 </CardGrid>
 
-## User token management
+## User Token Management
 
 To get started, install the NuGet Package:
 
@@ -68,6 +67,7 @@ See [Web Applications](/accesstokenmanagement/web-apps.md) for more information
     />
 </CardGrid>
 
-## License and Feedback
+## License And Feedback
 
-**Duende.AccessTokenManagement** is released as open source under the Apache 2.0 license. Bug reports, feature requests and contributions are welcome. If you have an idea for a new feature or significant code change you'd like to propose, please start with a GitHub issue so that we can discuss it. Thanks in advance!
+**Duende.AccessTokenManagement** is released as open source under the Apache 2.0 license.
+Bug reports, feature requests and contributions are welcome via the [Duende community discussions](https://duende.link/community).

src/content/docs/accesstokenmanagement/upgrading/atm-v3-to-v4.mdx

@@ -1,15 +1,16 @@
 ---
 title: "Duende AccessTokenManagement v3.x to v4.0"
-description: Guide for upgrading Duende BFF Security Framework from version 3.x to version 4.0, including migration steps for custom implementations and breaking changes.
+description: Guide for upgrading Duende.AccessTokenManagement from version 3.x to version 4.0, including migration steps for custom implementations and breaking changes.
 sidebar:
   label: v3.x → v4.0
   order: 100
 ---
 
 ## Changes
-### Moving Towards HybridCache Implementation and Away from Distributed Cache
 
-Microsoft has recently released HybridCache. While this is only released as a .NET 9 DLL, these assemblies work fine in .NET 8. So, while we still support .NET 8 with ATM 4.0, we are moving towards using HybridCache.
+### Moving Towards HybridCache Implementation And Away from Distributed Cache
+
+Microsoft has recently released [HybridCache](https://learn.microsoft.com/en-us/aspnet/core/performance/caching/hybrid). While this is only released as a .NET 9 assembly, these assemblies work fine in .NET 8. So, while we still support .NET 8 with ATM 4.0, we are moving towards using HybridCache.
 
 HybridCache brings significant improvements for us. Because of the two-layered cache, we've found it significantly improves performance.  
 If you currently use a distributed cache, this should still work seamlessly.
@@ -31,9 +32,11 @@ The library has undergone extensive internal changes—so much so that it can be
 
 All internal implementation details are now marked as internal, reducing accidental coupling and clarifying the intended extension points. In V3, all classes were public and most public methods were marked as virtual. This meant you could override any class by inheriting from it and overriding a single method.
 
-While this was very convenient for our consumers, it made it very difficult for us to introduce changes to the library without making breaking changes.
+While this was very convenient for our consumers, it made it challenging to introduce changes to the library without making breaking changes.
 
-We still want to ensure our users' extensibility needs are met, but via more controlled mechanisms. If you find that you have an extensibility need that is not covered by the new model, please raise a discussion in our discussion board. If this is a scenario we want to support, we'll do our best to accommodate it.
+We still want to ensure our users' extensibility needs are met, but via more controlled mechanisms.
+If you find that you have an extensibility need not covered by the new model, please raise a discussion [in our discussion board](https://duende.link/community).
+If this is a scenario we want to support, we'll do our best to accommodate it.
 
 ### Explicit Extension Model
 
@@ -55,15 +58,15 @@ For example:
 
 ```csharp
 var scheme = Scheme.Parse("oidc");
-
 ```
 
 ### Renamed classes
-Several classes have been renamed, either to make their usage clearer or to drop the 'service' suffix, which only adds noise:
-
-AccessTokenHandler => AccessTokenRequestHandler
-ClientCredentialsTokenManagementService => IClientIClientCredentialsTokenManager
-IClientCredentialsTokenEndpointService => IClientCredentialsTokenEndpoint
-IUserTokenManagementService => IUserTokenManager
-ITokenRequestSynchronization => IUserTokenRequestConcurrencyControl
-IUserTokenEndpointService => IUserTokenEndpoint
+
+Several classes have been renamed, either to clarify their usage or to drop the `service` suffix, which only adds noise:
+
+* `AccessTokenHandler` is now `AccessTokenRequestHandler`
+* `ClientCredentialsTokenManagementService` is now `IClientIClientCredentialsTokenManager`
+* `IClientCredentialsTokenEndpointService` is now `IClientCredentialsTokenEndpoint`
+* `IUserTokenManagementService` is now `IUserTokenManager`
+* `ITokenRequestSynchronization` is now `IUserTokenRequestConcurrencyControl`
+* `IUserTokenEndpointService` is now `IUserTokenEndpoint`

src/content/docs/accesstokenmanagement/web-apps.md

@@ -16,32 +16,32 @@ While many of the details can be customized, by default the following is assumed
 
 * ASP.NET Core web application
 * cookie authentication handler for session management
-* OpenID Connect authentication handler for authentication and access token requests against an OpenID Connect compliant
-  token service
+* OpenID Connect authentication handler for authentication and access token requests against an OpenID Connect compliant token service
 * the token service returns a refresh token
 
-Using this library, you can either request `user access tokens` or `client credentials tokens`. User access tokens typically contain information about the currently logged in user, such as the `sub` claim. They are used to access services under the credentials of the currently logged in user. `Client credentials tokens` do not contain information about the currently logged in user and are typically used to do machine-to-machine calls. 
+Using this library, you can either request `user access tokens` or `client credentials tokens`. User access tokens typically contain information about the currently logged in user, such as the `sub` claim.
+They are used to access services under the credentials of the currently logged in user. `Client credentials tokens` do not contain information about the currently logged in user and are typically used to do machine-to-machine calls. 
 
-## Usage
-First, you'll need to add `Duende.AccessTokenManagement.OpenIdConnect` to your solution. 
+To get started, you'll need to add `Duende.AccessTokenManagement.OpenIdConnect` to your solution. 
 
 Then, there are two fundamental ways to interact with token management:
 1. **Automatic** <Badge text="recommended"/>: You request a http client from the IHTTPClientFactory. This http client automatically requests, optionally renews and attaches the access tokens on each request. 
 2. **Manually**  <Badge text="advanced"/>: You request an access token, which you can then use to (for example) authenticate with services. You are responsible for attaching the access token to requests. 
 
-### Adding AccessTokenManagement to your project
+Let's look at these steps in more detail.
 
+## Adding AccessTokenManagement To Your Project
 
 To use this library, start by adding the library to your .NET projects.
 
 ```bash
 dotnet add package Duende.AccessTokenManagement.OpenIdConnect
 ```
 
-By default, the token management library will use the ASP.NET Core default authentication scheme for token storage (this
-is typically the cookie handler and its authentication session), and the default challenge scheme for deriving token
-client configuration for refreshing tokens or requesting client credential tokens (this is typically the OpenID Connect
-handler pointing to your trusted authority).
+By default, the token management library will use the ASP.NET Core default authentication scheme for token storage.
+This is typically the cookie handler and its authentication session.
+It also used the default challenge scheme for deriving token client configuration for refreshing tokens or requesting
+client credential tokens (typically the OpenID Connect handler pointing to your trusted authority).
 
 ```csharp
 // Program.cs
@@ -100,10 +100,10 @@ builder.Services.AddAuthentication(options =>
 builder.Services.AddOpenIdConnectAccessTokenManagement();
 ```
 
-### Automatic via HTTP Client Factory
+## Automatic Via HTTP Client Factory
 
 Similar to the worker service support, you can register HTTP clients that automatically send the access token of the
-current user when making API calls. The message handler plumbing associated with those HTTP clients will try to make
+current user when making API calls. The message handler associated with those HTTP clients will try to make
 sure, the access token is always valid and not expired.
 
 ```csharp
@@ -148,7 +148,7 @@ builder.Services.AddHttpClient<MasterDataClient>(client =>
 
 
 Last but not least, if you registered clients with the factory, you can use them. They will try to make sure that a
-current access token is always sent along. If that is not possible, ultimately a 401 will be returned to the calling
+current access token is always sent along. If that is not possible, ultimately a `401` HTTP status code will be returned to the calling
 code.
 
 ```csharp
@@ -173,9 +173,9 @@ public async Task<IActionResult> CallApi([FromServices] InvoiceClient client)
 }
 ```
 
-### Manually request access tokens
+## Manually Request Access Tokens
 
-If you want to use access tokens in a different way or have more advanced needs which the automatic option doesn't cover, then you can also manually request user access tokens. 
+If you want to use access tokens differently or have more advanced needs which the automatic option doesn't cover, then you can also manually request user access tokens. 
 
 {/* prettier-ignore */}
 <Tabs syncKey="atm">