security(auth): document and harden passkey account recovery guidance

Author: aalmada

docs/guides/authentication-guide.md

@@ -327,6 +327,32 @@ The application supports WebAuthn/FIDO2 for passwordless login. This flow is ful
 
 See [Passkey Guide](passkey-guide.md) for implementation details.
 
+### Passkey Account Recovery
+
+The API enforces a hard invariant: an account must always keep at least one sign-in factor available (password or passkey).
+
+Supported recovery flows:
+
+1. **User is still signed in on a trusted device**
+    - Add a password using `POST /account/add-password`.
+    - Register a replacement passkey.
+    - Remove the old passkey only after a replacement factor exists.
+
+2. **User has another passkey**
+    - Sign in with the backup passkey.
+    - Register any needed replacement passkey.
+    - Remove the old passkey only after confirming another factor is available.
+
+3. **User lost all passkeys and has no password**
+    - Self-service recovery is not available.
+    - Admin-assisted recovery is required.
+    - There is currently no dedicated admin API endpoint for passkey re-enrollment recovery.
+    - Operations/support must perform manual recovery and keep the account locked until the user re-enrolls at least one authentication factor.
+
+For safety, two endpoint guards return actionable RFC 7807 responses:
+- `POST /account/remove-password` is blocked when the user has zero passkeys.
+- `DELETE /account/passkeys/{id}` is blocked when deleting the last passkey on an account with no password.
+
 ## State Management & Re-Authentication
 
 ### In-Memory Token Storage

src/BookStore.ApiService/Endpoints/JwtAuthenticationEndpoints.cs

@@ -536,7 +536,14 @@ static async Task<IResult> RemovePasswordAsync(
         var passkeys = await passkeyStore.GetPasskeysAsync(appUser, cancellationToken);
         if (passkeys.Count == 0)
         {
-            return Result.Failure(Error.Validation(ErrorCodes.Auth.InvalidRequest, "You must have at least one passkey registered to remove your password.")).ToProblemDetails();
+            return Results.Problem(
+                statusCode: StatusCodes.Status400BadRequest,
+                title: "Cannot Remove Password Without a Passkey",
+                detail: "To keep account recovery available, register at least one passkey before removing your password. If you cannot register a passkey right now, keep your password and contact an administrator for recovery assistance.",
+                extensions: new Dictionary<string, object?>
+                {
+                    { "error", ErrorCodes.Auth.InvalidRequest }
+                });
         }
 
         var result = await userManager.RemovePasswordAsync(appUser);

src/BookStore.ApiService/Endpoints/PasskeyEndpoints.cs

@@ -476,47 +476,70 @@ public static IEndpointRouteBuilder MapPasskeyEndpoints(this IEndpointRouteBuild
             HybridCache cache,
             ITenantContext tenantContext,
             IUserStore<ApplicationUser> userStore,
-            CancellationToken cancellationToken) =>
+            CancellationToken cancellationToken) => await DeletePasskeyAsync(
+                id,
+                context.User,
+                userManager,
+                cache,
+                tenantContext,
+                userStore,
+                cancellationToken)).RequireAuthorization().RequireRateLimiting("AuthPolicy");
+
+        return endpoints;
+    }
+
+    static async Task<IResult> DeletePasskeyAsync(
+        string id,
+        ClaimsPrincipal principal,
+        UserManager<ApplicationUser> userManager,
+        HybridCache cache,
+        ITenantContext tenantContext,
+        IUserStore<ApplicationUser> userStore,
+        CancellationToken cancellationToken)
+    {
+        var user = await userManager.GetUserAsync(principal);
+        if (user is null)
         {
-            var user = await userManager.GetUserAsync(context.User);
-            if (user is null)
-            {
-                return Result.Failure(Error.Unauthorized(ErrorCodes.Auth.InvalidToken, "User not found.")).ToProblemDetails();
-            }
+            return Result.Failure(Error.Unauthorized(ErrorCodes.Auth.InvalidToken, "User not found.")).ToProblemDetails();
+        }
 
-            try
+        try
+        {
+            var credentialId = Base64UrlTextEncoder.Decode(id);
+            if (userStore is IUserPasskeyStore<ApplicationUser> passkeyStore)
             {
-                var credentialId = Base64UrlTextEncoder.Decode(id);
-                if (userStore is IUserPasskeyStore<ApplicationUser> passkeyStore)
+                // Prevent deleting last passkey if user has no password.
+                var passkeys = await passkeyStore.GetPasskeysAsync(user, cancellationToken);
+                if (passkeys.Count <= 1)
                 {
-                    // Prevent deleting last passkey if user has no password
-                    var passkeys = await passkeyStore.GetPasskeysAsync(user, cancellationToken);
-                    if (passkeys.Count <= 1)
+                    var hasPassword = await userManager.HasPasswordAsync(user);
+                    if (!hasPassword)
                     {
-                        var hasPassword = await userManager.HasPasswordAsync(user);
-                        if (!hasPassword)
-                        {
-                            return Result.Failure(Error.Validation(ErrorCodes.Passkey.LastPasskey, "Cannot delete your only passkey. You would be locked out of your account. Set a password first.")).ToProblemDetails();
-                        }
+                        return Results.Problem(
+                            statusCode: StatusCodes.Status400BadRequest,
+                            title: "Cannot Remove Your Last Passkey",
+                            detail: "This account has no password. Add a password while signed in, then register a replacement passkey before removing this one. If you have already lost access to all factors, contact an administrator for account recovery and re-enrollment.",
+                            extensions: new Dictionary<string, object?>
+                            {
+                                { "error", ErrorCodes.Passkey.LastPasskey }
+                            });
                     }
-
-                    await passkeyStore.RemovePasskeyAsync(user, credentialId, cancellationToken);
-                    // UpdateSecurityStampAsync persists the passkey removal AND rotates the
-                    // security stamp, which immediately invalidates any existing JWTs.
-                    _ = await userManager.UpdateSecurityStampAsync(user);
-                    await SecurityStampCache.InvalidateAsync(cache, tenantContext.TenantId, user.Id, cancellationToken);
-                    return Results.Ok(new { Message = "Passkey deleted." });
                 }
 
-                return Result.Failure(Error.Validation(ErrorCodes.Passkey.StoreNotAvailable, "Passkey store not available.")).ToProblemDetails();
-            }
-            catch (FormatException)
-            {
-                return Result.Failure(Error.Validation(ErrorCodes.Passkey.InvalidFormat, "Invalid passkey ID format.")).ToProblemDetails();
+                await passkeyStore.RemovePasskeyAsync(user, credentialId, cancellationToken);
+                // UpdateSecurityStampAsync persists the passkey removal AND rotates the
+                // security stamp, which immediately invalidates any existing JWTs.
+                _ = await userManager.UpdateSecurityStampAsync(user);
+                await SecurityStampCache.InvalidateAsync(cache, tenantContext.TenantId, user.Id, cancellationToken);
+                return Results.Ok(new { Message = "Passkey deleted." });
             }
-        }).RequireAuthorization().RequireRateLimiting("AuthPolicy");
 
-        return endpoints;
+            return Result.Failure(Error.Validation(ErrorCodes.Passkey.StoreNotAvailable, "Passkey store not available.")).ToProblemDetails();
+        }
+        catch (FormatException)
+        {
+            return Result.Failure(Error.Validation(ErrorCodes.Passkey.InvalidFormat, "Invalid passkey ID format.")).ToProblemDetails();
+        }
     }
 
     /// <summary>