Apply suggestions from code review

Author: maartenba

src/content/docs/bff/architecture/index.md

@@ -22,22 +22,22 @@ functions:
 * Server-side Token Management
 * Blazor support with unified authentication state management across rendering modes.
 
-## Authentiation flow
+## Authentication Flow
 
-The following diagram shows how the BFF protects browser based applications.  
+The following diagram shows how the BFF protects browser-based applications:
 
 ![BFF Security Framework Architecture Overview](../images/bff_application_architecture.svg)
 
 
-* **Authentication flows**: The server handles the authentication flows. There are specific endpoints for login / logout. While the browser is involved with these authentication flows, because the user is redirected to and from the identity provider, the actual browser based application will never see the authentication tokens. These are exchanged for a code on the server only. 
-* **Cookies**: After successful authentication, a cookie is added. This cookie protects all subsequent calls to the apis. When using this type of authentication, **CSRF protection** is very important. 
-* **Access to apis**: The BFF can expose embedded apis (which are embedded in the BFF itself) or proxy calls to remote api's (which is more common in a microservice environment). While proxying, it will exchange the authentication cookie for an access token. 
-* **Session Management**: The BFF can manage the users session. This can either be cookie based session management or storage based session management. 
+* **Authentication flows**: The server handles the authentication flows. There are specific endpoints for login / logout. While the browser is involved with these authentication flows, because the user is redirected to and from the identity provider, the browser-based application will never see the authentication tokens. These are exchanged for a code on the server only. 
+* **Cookies**: After successful authentication, a cookie is added. This cookie protects all subsequent calls to the APIs. When using this type of authentication, **CSRF protection** is very important. 
+* **Access to APIs**: The BFF can expose embedded APIs (which are hosted by the BFF itself) or proxy calls to remote APIs (which is more common in a microservice environment). While proxying, it will exchange the authentication cookie for an access token. 
+* **Session Management**: The BFF can manage the users session. This can either be cookie-based session management or storage-based session management. 
 
 
 ## Internals
 Duende.BFF builds on widely used tools and frameworks, including ASP.NET Core's OpenID Connect and cookie authentication
-handlers, YARP, and Duende.AccessTokenManagement. Duende.BFF combines these tools and adds additional security and
+handlers, YARP, and [Duende.AccessTokenManagement](/accesstokenmanagement/index.mdx). Duende.BFF combines these tools and adds additional security and
 application features that are useful with a BFF architecture so that you can focus on providing application logic
 instead of security logic:
 
@@ -50,7 +50,7 @@ contributors to this library, we think it is a well implemented and flexible imp
 
 ### ASP.NET Cookie Handler
 
-Duende.BFF uses ASP.NET's Cookie handler for session management. The Cookie handler provides a claims-based identity to
+Duende.BFF uses ASP.NET's Cookie handler for session management. The cookie handler provides a claims-based identity to
 the application persisted in a digitally signed and encrypted cookie that is protected with modern cookie security
 features, including the Secure, HttpOnly and SameSite attributes. The handler also provides absolute and sliding session
 support, and has a flexible extensibility model, which Duende.BFF uses to

src/content/docs/bff/architecture/multi-frontend.md

@@ -29,7 +29,7 @@ The Duende BFF V4 library doesn't ship with an abstraction to store or read fron
 
 ## A Typical Example
 
-Consider an enterprise that hosts multiple browser based applications. Each of these applications is developed by a separate team and as such, has it's own deployment schedule. 
+Consider an enterprise that hosts multiple browser based applications. Each of these applications is developed by a separate team and as such, has its own deployment schedule. 
 
 There are some internal-facing applications that are exclusively used by internal employees. These internal employees are all present in Microsoft Entra ID, so these internal-facing applications should directly authenticate against Microsoft Entra ID. These applications also use several internal APIs, that due to the sensitivity, should not be accessible by external users. However, they also use some of the more common APIs. These apps are only accessible via an internal DNS name, such as `https://app1.internal.example.com`. 
 
@@ -60,9 +60,9 @@ After your application's logic is executed, there are two middlewares registered
 
 5. `MapRemoteRoutesMiddleware` - This will handle any configured remote routes. Note, it will not handle plain YARP calls, only routes that are specifically added to a frontend.
 
-6. `ProxyIndexMiddleware` - If configured, this proxy the `index.html` to start the browser based app.  
+6. `ProxyIndexMiddleware` - If configured, this proxies the `index.html` to start the browser based app.  
 
-If you don't want this automatic mapping of BFF middleware, you can turn it off using `BffOptions.AutomaticallyRegisterBffMiddleware`. Please note then you're responsible for manually adding the middlewares:
+If you don't want this automatic mapping of BFF middleware, you can turn it off using `BffOptions.AutomaticallyRegisterBffMiddleware`. When doing so, you'll need to manually register and add the middlewares:
 
 ```csharp
 var app = builder.Build();
@@ -71,11 +71,11 @@ app.UseBffFrontendSelection();
 app.UseBffPathMapping();
 app.UseBffOpenIdCallbacks();
 
-// Todo: your custom middleware goes here:
+// TODO: your custom middleware goes here
 app.UseRouting(); 
 app.UseBff();
 
-// Only add this if you want to proxy to remote api's. 
+// NOTE: Only add this if you want to proxy remote APIs. 
 app.UseBffRemoteRoutes();
 
 app.MapBffManagementEndpoints();
@@ -84,17 +84,17 @@ app.UseBffIndexPages();
 app.Run();
 ```
 
-## Authentication architecture
+## Authentication Architecture
 
-When you use multiple frontends, you can't rely on [manual authentication configuration](../fundamentals/session/handlers.mdx#manually-configuring-authentication). This is because each frontend requires it's own scheme, and potentially it's own OpenID Connect and Cookie configuration. 
+When you use multiple frontends, you can't rely on [manual authentication configuration](../fundamentals/session/handlers.mdx#manually-configuring-authentication). This is because each frontend requires its own scheme, and potentially its own OpenID Connect and Cookie configuration. 
 
 The BFF registers a dynamic authentication scheme, which automatically configures the OpenID Connect and Cookie Scheme's on behalf of the frontends. It does this using a custom `AuthenticationSchemeProvider` called `BffAuthenticationSchemeProvider` to return appropriate authentication schemes for each frontend. 
 
 The BFF will register two schemes:
-* 'duende-bff-oidc'. 
-* 'duende-bff-cookie'. 
+* `duende-bff-oidc`
+* `duende-bff-cookie`
 
 Then, if there are no default authentication schemes registered, it will register 'duende_bff_cookie' schemes as the `AuthenticationOptions.DefaultScheme`, and 'duende_bff_oidc' as the `AuthenticationOptions.DefaultAuthenticateScheme` and `AuthenticationOptions.DefaultSignOutScheme`. This will ensure that calls to `Authenticate()` or `Signout()` will use the appropriate schemes. 
 
-If you're using multiple frontends, then the BFF will create dynamic schemes with the following signature: 'duende_bff_oidc_[frontendname]' and 'duende_bff_cookie_[frontendname]'. This ensures that every frontend can use it's own OpenID Connect and Cookie settings. 
+If you're using multiple frontends, then the BFF will create dynamic schemes with the following signature: `duende_bff_oidc_[frontendname]` and `duende_bff_cookie_[frontendname]`. This ensures that every frontend can use its own OpenID Connect and Cookie settings. 
 

src/content/docs/bff/extensibility/http-forwarder.md

@@ -17,7 +17,8 @@ You can customize the HTTP forwarder behavior in two ways
 * provide a customized HTTP client for outgoing calls
 * provide custom request/response transformation
 
-## Custom HTTP clients
+## Custom HTTP Clients
+
 By default, Duende.BFF will create and cache an HTTP client per configured route or local path.
 
 This invoker is set up like this:
@@ -32,12 +33,12 @@ var client = new HttpMessageInvoker(new SocketsHttpHandler
 });
 ```
 
-If you want to customize the HTTP client you can either implement the *IForwarderHttpClientFactory* interface, e.g.:
+If you want to customize the HTTP client you can implement the `IForwarderHttpClientFactory` interface, e.g.:
 
 ```cs
 public class MyInvokerFactory : IForwarderHttpClientFactory
 {
-    public public HttpMessageInvoker CreateClient(ForwarderHttpClientContext context)
+    public HttpMessageInvoker CreateClient(ForwarderHttpClientContext context)
     {
         return Clients.GetOrAdd(localPath, (key) =>
         {
@@ -62,46 +63,44 @@ public class MyInvokerFactory : IForwarderHttpClientFactory
 services.AddSingleton<IForwarderHttpClientFactory, MyInvokerFactory>();
 ```
 
-## Custom transformations when using Direct Forwarding
+## Custom Transformations When Using Direct Forwarding
 
 The method MapRemoteBffApiEndpoint uses default transformations that:
 * removes the cookie header from the forwarded request
-* removes local path from from the forwarded request
+* removes local path from the forwarded request
 * Adds the access token to the original request
 
 If you wish to change or extend this behavior, you can do this for a single mapped endpoint
-or for all mapped api endpoints. 
+or for all mapped API endpoints. 
 
-### Changing the transformer for a single mapped endpoint
+### Changing The Transformer For A Single Mapped Endpoint
 
-This code block shows an example how you can extend the default transformers with an additional custom
+This code block shows an example how of you can extend the default transformers with an additional custom
 transform. 
 
 ```csharp
-
 app.MapRemoteBffApiEndpoint("/local", new Uri("https://target/"), context => {
 
     // If you want to extend the existing behavior, then you must call the default builder:
     DefaultBffYarpTransformerBuilders.DirectProxyWithAccessToken("/local", context);
 
-    //You can also add custom transformers, such as this one that adds an additional header
+    // You can also add custom transformers, such as this one that adds an additional header
     context.AddRequestHeader("custom", "with value");
 
 });
-
 ```
 
-The default transformbuilder performs these transforms:
+The default transform builder performs these transforms:
 
 ```csharp
 context.AddRequestHeaderRemove("Cookie");
 context.AddPathRemovePrefix(localPath);
 context.AddBffAccessToken(localPath);
 ```
 
-For more information, also see the [yarp documentation on transforms](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/yarp/transforms?view=aspnetcore-9.0)
+For more information, also see the [YARP documentation on transforms](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/yarp/transforms?view=aspnetcore-9.0)
 
-### Changing the default transformer. 
+### Changing The Default Transformer
 
 You can change the default transformer builder delegate by registering one in the services collection:
 
@@ -111,22 +110,21 @@ BffYarpTransformBuilder builder = (localPath, context) => {
     // If you want to extend the existing behavior, then you must call the default builder:
     DefaultBffYarpTransformerBuilders.DirectProxyWithAccessToken(localpath, context);
 
-   //You can also add custom transformers, such as this one that adds an additional header
+    // You can also add custom transformers, such as this one that adds an additional header
     context.AddResponseHeader("added-by-custom-default-transform", "some-value");
 
 };
 
 services.AddSingleton<BffYarpTransformBuilder>(builder);
 ```
 
-## Changing the Forwarder Request Config
+## Changing The Forwarder Request Configuration
 
-You an also modify the forwarder request config, either globally or per mapped path.
+You an also modify the forwarder request configuration, either globally or per mapped path.
 This can be useful if you want to tweak things like activity timeouts. 
 
 ```csharp
-
-// Register a forwarder config globally. 
+// Register a forwarder config globally: 
 services.AddSingleton(new ForwarderRequestConfig()
 {
     ActivityTimeout = TimeSpan.FromMilliseconds(100)
@@ -140,7 +138,6 @@ app.MapRemoteBffApiEndpoint("/local", new Uri("https://target/"),
         // but not too long that the test will take forever
         ActivityTimeout = TimeSpan.FromMilliseconds(100)
     });
-
 ```
 
 

src/content/docs/bff/extensibility/management/back-channel-logout.md

@@ -12,12 +12,12 @@ redirect_from:
   - /identityserver/v7/bff/extensibility/management/back-channel-logout/
 ---
 
-The back-channel logout endpoint has several extensibility points organized into two interfaces. The *IBackChannelLogoutEndpoint* is the top level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic or to change how it validates incoming requests. When the back-channel logout endpoint receives a valid request, it revokes sessions using the *ISessionRevocationService*. 
+The back-channel logout endpoint has several extensibility points organized into two interfaces. The `IBackChannelLogoutEndpoint` is the top-level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic or to change how it validates incoming requests. When the back-channel logout endpoint receives a valid request, it revokes sessions using the `ISessionRevocationService`. 
 
 ## Request Processing
-You can add custom logic to the endpoint by implementing the *IBackChannelLogoutEndpoint* .
+You can add custom logic to the endpoint by implementing the `IBackChannelLogoutEndpoint` .
 
-*ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
+`ProcessRequestAsync` is the top-level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
 
 ```csharp
 public class CustomizedBackChannelLogoutService : IBackChannelLogoutEndpoint
@@ -31,4 +31,4 @@ public class CustomizedBackChannelLogoutService : IBackChannelLogoutEndpoint
 
 
 ## Session Revocation
-The back-channel logout service will call the registered session revocation service to revoke the user session when it receives a valid logout token. To customize the revocation process, implement the *ISessionRevocationService*. 
+The back-channel logout service will call the registered session revocation service to revoke the user session when it receives a valid logout token. To customize the revocation process, implement the `ISessionRevocationService`. 

src/content/docs/bff/extensibility/management/diagnostics.md

@@ -12,10 +12,10 @@ redirect_from:
   - /identityserver/v7/bff/extensibility/management/diagnostics/
 ---
 
-The BFF diagnostics endpoint can be customized by implementing the *IDiagnosticsEndpoint*.
+The BFF diagnostics endpoint can be customized by implementing the `IDiagnosticsEndpoint`.
 
 ## Request Processing
-*ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
+`ProcessRequestAsync` is the top-level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
 
 For example, you could take whatever actions you need before normal processing of the request like this:
 

src/content/docs/bff/extensibility/management/index.md

@@ -25,9 +25,9 @@ builder.Services.AddTransient<IBackchannelLogoutService, DefaultBackchannelLogou
 builder.Services.AddTransient<IDiagnosticsService, DefaultDiagnosticsService>();
 ```
 
-You can add your own implementation by overriding the default after calling *AddBff()*.
+You can add your own implementation by overriding the default after calling `AddBff()`.
 
-The management endpoint services all inherit from the *IBffEndpointEndpoint*, which provides a general-purpose mechanism to add custom logic to the endpoints. 
+The management endpoint services all inherit from the `IBffEndpointEndpoint`, which provides a general-purpose mechanism to add custom logic to the endpoints. 
 
 ```csharp
 public interface IBffEndpointService
@@ -36,6 +36,6 @@ public interface IBffEndpointService
 }
 ```
 
-None of the endpoint services contain additional members beyond *ProcessRequestAsync*.
+None of the endpoint services contain additional members beyond `ProcessRequestAsync`.
 
 You can customize the behavior of the endpoints either by implementing the appropriate interface or by extending the default implementation of that interface. In many cases, extending the default implementation is preferred, as this allows you to keep most of the default behavior by calling the base *ProcessRequestAsync* from your derived class. Several of the default endpoint service implementations also define virtual methods that can be overridden to customize their behavior with more granularity.

src/content/docs/bff/extensibility/management/login.md

@@ -12,10 +12,11 @@ redirect_from:
   - /identityserver/v7/bff/extensibility/management/login/
 ---
 
-The BFF login endpoint has extensibility points in two interfaces. The *ILoginEndpoint* is the top level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic. The *IReturnUrlValidator* ensures that the *returnUrl* parameter passed to the login endpoint is safe to use.
+The BFF login endpoint has extensibility points in two interfaces. The `ILoginEndpoint` is the top-level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic. The `IReturnUrlValidator` ensures that the `returnUrl` parameter passed to the login endpoint is safe to use.
 
 ## Request Processing
-*ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
+
+`ProcessRequestAsync` is the top-level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
 
 For example, you could take whatever actions you need before normal processing of the request like this:
 
@@ -29,4 +30,5 @@ public Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
 ```
 
 ## Return URL Validation
-To prevent open redirector attacks, the *returnUrl* parameter to the login endpoint must be validated. You can customize this validation by implementing the *IReturnUrlValidator* interface. The default implementation enforces that return urls are local.
+
+To prevent open redirector attacks, the `returnUrl` parameter to the login endpoint must be validated. You can customize this validation by implementing the `IReturnUrlValidator` interface. The default implementation enforces that return URLs are local.