Standardize on a common terminology

README.md

@@ -92,11 +92,11 @@ public async Task<IActionResult> GetRegisterToken(string alias)
 
 ### Verify user
 
-Define an action or an endpoint to verify a signin token:
+Define an action or an endpoint to verify an authentication token:
 
 ```csharp
 [HttpGet("/verify-signin")]
-public async Task<IActionResult> VerifySignInToken(string token)
+public async Task<IActionResult> VerifyAuthenticationToken(string token)
 {
     try
     {

examples/Passwordless.Example/PasswordlessController.cs

@@ -25,8 +25,6 @@ public PasswordlessController(IPasswordlessClient passwordlessClient)
     ///     signed in users to add a Key to their own account.
     ///     Please see: https://docs.passwordless.dev/guide/api.html#register-token
     /// </summary>
-    /// <param name="alias"></param>
-    /// <returns></returns>
     [HttpGet("/create-token")]
     public async Task<IActionResult> GetRegisterToken(string alias)
     {
@@ -59,13 +57,12 @@ public async Task<IActionResult> GetRegisterToken(string alias)
     ///     This is as easy as POST'ing it to together with your ApiSecret.
     ///     Please see: https://docs.passwordless.dev/guide/api.html#signin-verify
     /// </summary>
-    /// <param name="token"></param>
     [HttpGet("/verify-signin")]
-    public async Task<IActionResult> VerifySignInToken(string token)
+    public async Task<IActionResult> VerifyAuthenticationToken(string token)
     {
         try
         {
-            var verifiedUser = await _passwordlessClient.VerifyTokenAsync(token);
+            var verifiedUser = await _passwordlessClient.VerifyAuthenticationTokenAsync(token);
             return Ok(verifiedUser);
         }
         catch (PasswordlessApiException e)

src/Passwordless.AspNetCore/Services/Implementations/PasswordlessService.cs

@@ -261,7 +261,7 @@ public virtual async Task<IResult> LoginUserAsync(
     {
         try
         {
-            var verifiedUser = await PasswordlessClient.VerifyTokenAsync(loginRequest.Token, cancellationToken);
+            var verifiedUser = await PasswordlessClient.VerifyAuthenticationTokenAsync(loginRequest.Token, cancellationToken);
 
             _logger.LogDebug("Attempting to find user in store by id {UserId}.", verifiedUser.UserId);
             var user = await UserStore.FindByIdAsync(verifiedUser.UserId, cancellationToken);

src/Passwordless/Helpers/PasswordlessSerializerContext.cs

@@ -10,8 +10,8 @@ namespace Passwordless.Helpers;
     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)]
 [JsonSerializable(typeof(RegisterTokenResponse))]
 [JsonSerializable(typeof(RegisterOptions))]
-[JsonSerializable(typeof(SigninTokenResponse))]
-[JsonSerializable(typeof(SigninOptions))]
+[JsonSerializable(typeof(AuthenticationTokenResponse))]
+[JsonSerializable(typeof(AuthenticationOptions))]
 [JsonSerializable(typeof(VerifyTokenRequest))]
 [JsonSerializable(typeof(VerifiedUser))]
 [JsonSerializable(typeof(DeleteUserRequest))]

src/Passwordless/IPasswordlessClient.cs

@@ -11,41 +11,32 @@ namespace Passwordless;
 public interface IPasswordlessClient
 {
     /// <summary>
-    /// Creates a <see cref="RegisterTokenResponse" /> which will be used by your frontend to negotiate
-    /// the creation of a WebAuth credential.
+    /// Creates a register token which will be used by your frontend to negotiate the creation of a WebAuth credential.
     /// </summary>
-    /// <param name="options">The <see cref="RegisterOptions"/> that will be used to configure your token.</param>
-    /// <param name="cancellationToken"></param>
-    /// <returns>A task object representing the asynchronous operation containing the <see cref="RegisterTokenResponse" />.</returns>
-    /// <exception cref="PasswordlessApiException">An exception containing details about the reason for failure.</exception>
     Task<RegisterTokenResponse> CreateRegisterTokenAsync(
         RegisterOptions options,
         CancellationToken cancellationToken = default
     );
 
     /// <summary>
-    /// Creates a <see cref="SigninTokenResponse" /> which can be used to authenticate on behalf of a user.
+    /// Manually generates an authentication token for the specified user, side-stepping the usual authentication flow.
+    /// This approach can be used to implement a "magic link"-style login and other similar scenarios.
     /// </summary>
-    /// <param name="options">The <see cref="SigninOptions"/> that will be used to configure your token.</param>
-    /// <param name="cancellationToken"></param>
-    /// <returns>A task object representing the asynchronous operation containing the <see cref="SigninTokenResponse" />.</returns>
-    /// <exception cref="PasswordlessApiException">An exception containing details about the reason for failure.</exception>
-    Task<SigninTokenResponse> GenerateSigninTokenAsync(
-        SigninOptions options,
+    Task<AuthenticationTokenResponse> GenerateAuthenticationTokenAsync(
+        AuthenticationOptions options,
         CancellationToken cancellationToken = default
     );
 
     /// <summary>
-    /// Verifies that the given token is valid and returns information packed into it.
-    /// The token should have been generated via calling a <c>signInWith*</c> method from your frontend code.
-    /// If the token is not valid, an exception of type <see cref="PasswordlessApiException" /> will be thrown.
+    /// Verifies that the specified authentication token is valid and returns the information packed into it.
+    /// The token should have been generated by calling one of the <c>signInWith*</c> methods from your frontend,
+    /// or, in specific scenarios, by calling <see cref="GenerateAuthenticationTokenAsync" /> from the backend.
     /// </summary>
-    /// <param name="verifyToken">The token to verify.</param>
-    /// <param name="cancellationToken"></param>
-    /// <returns>A task object representing the asynchronous operation containing the <see cref="VerifiedUser" />.</returns>
-    /// <exception cref="PasswordlessApiException">An exception containing details about the reason for failure.</exception>
-    Task<VerifiedUser> VerifyTokenAsync(
-        string verifyToken,
+    /// <remarks>
+    /// If the token is not valid, an exception of type <see cref="PasswordlessApiException" /> will be thrown.
+    /// </remarks>
+    Task<VerifiedUser> VerifyAuthenticationTokenAsync(
+        string authenticationToken,
         CancellationToken cancellationToken = default
     );
 
@@ -57,81 +48,56 @@ Task<UsersCount> GetUsersCountAsync(
     );
 
     /// <summary>
-    /// List all the <see cref="PasswordlessUserSummary" /> for the account associated with your ApiSecret.
+    /// Lists all users in the app.
     /// </summary>
-    /// <param name="cancellationToken"></param>
-    /// <returns>A task object representing the asynchronous operation containing the <see cref="IReadOnlyList{PasswordlessUserSummary}" />.</returns>
-    /// <exception cref="PasswordlessApiException">An exception containing details about the reason for failure.</exception>
     Task<IReadOnlyList<PasswordlessUserSummary>> ListUsersAsync(
         CancellationToken cancellationToken = default
     );
 
     /// <summary>
-    /// Deletes a user.
+    /// Deletes the user with the specified ID.
     /// </summary>
-    /// <param name="userId">The id of the user that should be deleted.</param>
-    /// <param name="cancellationToken"></param>
-    /// <returns>A task object representing the asynchronous operation.</returns>
-    /// <exception cref="PasswordlessApiException">An exception containing details about the reason for failure.</exception>
     Task DeleteUserAsync(
         string userId,
         CancellationToken cancellationToken = default
     );
 
     /// <summary>
-    /// List all the <see cref="AliasPointer" /> for a given user.
+    /// Lists all aliases for the user with the specified ID.
     /// </summary>
-    /// <param name="userId">The userId of the user for which the aliases will be returned.</param>
-    /// <param name="cancellationToken"></param>
-    /// <returns>A task object representing the asynchronous operation containing the <see cref="IReadOnlyList{AliasPointer}" />.</returns>
-    /// <exception cref="PasswordlessApiException">An exception containing details about the reason for failure.</exception>
     Task<IReadOnlyList<AliasPointer>> ListAliasesAsync(
         string userId,
         CancellationToken cancellationToken = default
     );
 
     /// <summary>
-    /// Sets one or more aliases to an existing user and removes existing aliases that are not included in the request.
+    /// Sets one or more aliases for an existing user and removes existing aliases
+    /// that are not included in the request.
     /// </summary>
-    /// <param name="request"></param>
-    /// <param name="cancellationToken"></param>
-    /// <returns></returns>
     Task SetAliasAsync(
         SetAliasRequest request,
         CancellationToken cancellationToken = default
     );
 
     /// <summary>
-    /// List all the <see cref="Credential" /> for a given user.
+    /// Lists all credentials for the user with the specified ID.
     /// </summary>
-    /// <param name="userId">The userId of the user for which the credentials will be returned.</param>
-    /// <param name="cancellationToken"></param>
-    /// <returns>A task object representing the asynchronous operation containing the <see cref="IReadOnlyList{Credential}" />.</returns>
-    /// <exception cref="PasswordlessApiException">An exception containing details about the reason for failure.</exception>
     Task<IReadOnlyList<Credential>> ListCredentialsAsync(
         string userId,
         CancellationToken cancellationToken = default
     );
 
     /// <summary>
-    /// Attempts to delete a credential via the supplied id.
+    /// Attempts to delete a credential with the specified ID.
     /// </summary>
-    /// <param name="id">The id of a credential representing as a Base64 URL encoded <see cref="string" />.</param>
-    /// <param name="cancellationToken"></param>
-    /// <returns>A task object representing the asynchronous operation.</returns>
-    /// <exception cref="PasswordlessApiException">An exception containing details about the reason for failure.</exception>
     Task DeleteCredentialAsync(
         string id,
         CancellationToken cancellationToken = default
     );
 
     /// <summary>
-    /// Attempts to delete a credential via the supplied id.
+    /// Attempts to delete a credential with the specified ID.
     /// </summary>
-    /// <param name="id">The id of a credential representing as a Base64 URL encoded <see cref="T:byte[]" />.</param>
-    /// <param name="cancellationToken"></param>
-    /// <returns>A task object representing the asynchronous operation.</returns>
-    /// <exception cref="PasswordlessApiException">An exception containing details about the reason for failure.</exception>
     Task DeleteCredentialAsync(
         byte[] id,
         CancellationToken cancellationToken = default

src/Passwordless/Models/SigninOptions.cs → src/Passwordless/Models/AuthenticationOptions.cs

@@ -1,10 +1,10 @@
 namespace Passwordless.Models;
 
-public class SigninOptions
+public class AuthenticationOptions
 {
     public string UserId { get; }
 
-    public SigninOptions(string userId)
+    public AuthenticationOptions(string userId)
     {
         UserId = userId;
     }

src/Passwordless/Models/SigninTokenResponse.cs → src/Passwordless/Models/AuthenticationTokenResponse.cs

@@ -1,8 +1,8 @@
 namespace Passwordless.Models;
 
-public class SigninTokenResponse
+public class AuthenticationTokenResponse
 {
-    public SigninTokenResponse(string token)
+    public AuthenticationTokenResponse(string token)
     {
         Token = token;
     }

src/Passwordless/PasswordlessClient.cs

@@ -79,30 +79,30 @@ public async Task<RegisterTokenResponse> CreateRegisterTokenAsync(
     }
 
     /// <inheritdoc />
-    public async Task<SigninTokenResponse> GenerateSigninTokenAsync(
-        SigninOptions options,
+    public async Task<AuthenticationTokenResponse> GenerateAuthenticationTokenAsync(
+        AuthenticationOptions options,
         CancellationToken cancellationToken = default)
     {
         using var response = await _http.PostAsJsonAsync("signin/generate-token",
             options,
-            PasswordlessSerializerContext.Default.SigninOptions,
+            PasswordlessSerializerContext.Default.AuthenticationOptions,
             cancellationToken
         );
 
         response.EnsureSuccessStatusCode();
 
         return (await response.Content.ReadFromJsonAsync(
-            PasswordlessSerializerContext.Default.SigninTokenResponse,
+            PasswordlessSerializerContext.Default.AuthenticationTokenResponse,
             cancellationToken))!;
     }
 
     /// <inheritdoc />
-    public async Task<VerifiedUser> VerifyTokenAsync(
-        string verifyToken,
+    public async Task<VerifiedUser> VerifyAuthenticationTokenAsync(
+        string authenticationToken,
         CancellationToken cancellationToken = default)
     {
         using var response = await _http.PostAsJsonAsync("signin/verify",
-            new VerifyTokenRequest(verifyToken),
+            new VerifyTokenRequest(authenticationToken),
             PasswordlessSerializerContext.Default.VerifyTokenRequest,
             cancellationToken
         );

tests/Passwordless.AspNetCore.Tests/OldTests/PasswordlessServiceTests.cs

@@ -16,6 +16,7 @@
 using Passwordless.AspNetCore.Services.Implementations;
 using Passwordless.Models;
 using Xunit;
+using AuthenticationOptions = Microsoft.AspNetCore.Authentication.AuthenticationOptions;
 
 namespace Passwordless.AspNetCore.Tests.OldTests;
 
@@ -206,7 +207,7 @@ public async Task LoginUserAsync_UsesDefaultSchemeIfNoneSpecified()
         await _testUserStore.CreateAsync(user);
 
         _mockPasswordlessClient
-            .Setup(s => s.VerifyTokenAsync("test_token", default))
+            .Setup(s => s.VerifyAuthenticationTokenAsync("test_token", default))
             .ReturnsAsync(verifiedUser);
 
         _mockUserClaimsPrincipalFactory
@@ -248,7 +249,7 @@ public async Task LoginUserAsync_UsesOurOptionIfSpecified()
         await _testUserStore.CreateAsync(user);
 
         _mockPasswordlessClient
-            .Setup(s => s.VerifyTokenAsync("test_token", default))
+            .Setup(s => s.VerifyAuthenticationTokenAsync("test_token", default))
             .ReturnsAsync(verifiedUser);
 
         _mockUserClaimsPrincipalFactory
@@ -297,7 +298,7 @@ public async Task LoginUserAsync_TriesAuthenticationOptionsIfOursIsNull()
         await _testUserStore.CreateAsync(user);
 
         _mockPasswordlessClient
-            .Setup(s => s.VerifyTokenAsync("test_token", default))
+            .Setup(s => s.VerifyAuthenticationTokenAsync("test_token", default))
             .ReturnsAsync(verifiedUser);
 
         _mockUserClaimsPrincipalFactory
@@ -329,7 +330,7 @@ public async Task LoginUserAsync_UserDoesNotExist_ReturnsUnauthorized()
             _fixture.Create<Guid>(),
             _fixture.Create<string>());
         _mockPasswordlessClient
-            .Setup(s => s.VerifyTokenAsync("test_token", default))
+            .Setup(s => s.VerifyAuthenticationTokenAsync("test_token", default))
             .ReturnsAsync(verifiedUser);
 
         var sut = CreateSut();