Commit

Author: Jian Shen

lib/msal-native-auth/doc/tech-design/Tech Design.md

@@ -15,14 +15,34 @@ import {
 } from "./NativeAuthActionOptions.js";
 
 export interface INativeAuthPublicClientApplication {
+    /*
+     * Gets the current account from the cache.
+     * @param getAccountOptions - Options for getting the current cached account
+     * @returns - A promise that resolves to GetAccountResult
+     */
     getCurrentAccount(
         getAccountOptions: GetAccountOptions
     ): Promise<GetAccountResult>;
 
+    /*
+     * Initiates the sign-in flow.
+     * @param signInOptions - Options for the sign-in flow
+     * @returns - A promise that resolves to SignInResult
+     */
     signIn(signInOptions: SignInOptions): Promise<SignInResult>;
 
+    /*
+     * Initiates the sign-up flow.
+     * @param signUpOptions - Options for the sign-up flow
+     * @returns - A promise that resolves to SignUpResult
+     */
     signUp(signUpOptions: SignUpOptions): Promise<SignUpResult>;
 
+    /*
+     * Initiates the reset password flow.
+     * @param resetPasswordOptions - Options for the reset password flow
+     * @returns - A promise that resolves to ResetPasswordStartResult
+     */
     resetPassword(
         resetPasswordOptions: ResetPasswordOptions
     ): Promise<ResetPasswordStartResult>;

lib/msal-native-auth/doc/tech-design/api-flow.png

@@ -26,12 +26,21 @@ export class NativeAuthPublicClientApplication
 {
     private readonly nativeAuthController: NativeAuthStandardController;
 
+    /*
+     * Creates a new instance of a PublicClientApplication with the given configuration.
+     * @param config - A configuration object for the PublicClientApplication instance
+     */
     static create(
         config: NativeAuthConfiguration
     ): NativeAuthPublicClientApplication {
         return new NativeAuthPublicClientApplication(config);
     }
 
+    /*
+     * Creates a new instance of a PublicClientApplication with the given configuration and controller.
+     * @param config - A configuration object for the PublicClientApplication instance
+     * @param controller - A controller object for the PublicClientApplication instance
+     */
     constructor(
         config: NativeAuthConfiguration,
         controller?: INativeAuthStardardController
@@ -45,6 +54,11 @@ export class NativeAuthPublicClientApplication
         this.nativeAuthController = nativeAuthController;
     }
 
+    /*
+     * Gets the current account from the cache.
+     * @param getAccountOptions - Options for getting the current cached account
+     * @returns - A promise that resolves to GetAccountResult
+     */
     getCurrentAccount(
         getAccountOptions: GetAccountOptions
     ): Promise<GetAccountResult> {
@@ -53,16 +67,31 @@ export class NativeAuthPublicClientApplication
         );
     }
 
+    /*
+     * Initiates the sign-in flow.
+     * @param signInOptions - Options for the sign-in flow
+     * @returns - A promise that resolves to SignInResult
+     */
     signIn(signInOptions: SignInOptions): Promise<SignInResult> {
         return this.nativeAuthController.signIn(signInOptions);
     }
 
+    /*
+     * Initiates the sign-up flow.
+     * @param signUpOptions - Options for the sign-up flow
+     * @returns - A promise that resolves to SignUpResult
+     */
     signUp(signUpOptions: SignUpOptions): Promise<SignUpResult> {
         throw new Error(
             `Method not implemented with parameter ${signUpOptions}`
         );
     }
 
+    /*
+     * Initiates the reset password flow.
+     * @param resetPasswordOptions - Options for the reset password flow
+     * @returns - A promise that resolves to ResetPasswordStartResult
+     */
     resetPassword(
         resetPasswordOptions: ResetPasswordOptions
     ): Promise<ResetPasswordStartResult> {

lib/msal-native-auth/doc/tech-design/msal-for-js-classes.png

@@ -17,7 +17,16 @@ import {
     TokenClaims,
 } from "@azure/msal-browser";
 
+/*
+ * Account information.
+ */
 export class AccountInfo {
+    /*
+     * Constructor
+     * @param account - Account data
+     * @param correlationId - Correlation id
+     * @param config - Configuration
+     */
     constructor(
         private readonly account: AccountData,
         private readonly correlationId: string,
@@ -36,18 +45,34 @@ export class AccountInfo {
         }
     }
 
+    /*
+     * Signs the current user out
+     * @returns The result of the operation.
+     */
     signOut(): Promise<SignOutResult> {
         throw new Error("Method not implemented.");
     }
 
+    /*
+     * Gets the account data.
+     * @returns The account data.
+     */
     getAccount(): AccountData {
         return this.account;
     }
 
+    /*
+     * Gets the account id-token.
+     * @returns The account id-token.
+     */
     getIdToken(): string | undefined {
         return this.account.idToken;
     }
 
+    /*
+     * Gets the token claims.
+     * @returns The token claims.
+     */
     getClaims():
         | (TokenClaims & {
               [key: string]:
@@ -62,6 +87,12 @@ export class AccountInfo {
         return this.account.idTokenClaims;
     }
 
+    /*
+     * Gets the access token from cache.
+     * @param forceRefresh - Force a token refresh
+     * @param scopes - The scopes to request
+     * @returns The result of the operation.
+     */
     getAccessToken(
         forceRefresh: boolean = false,
         scopes?: Array<string>

lib/msal-native-auth/doc/tech-design/native-auth-classes.png

@@ -12,7 +12,17 @@ import {
 } from "../result/ResetPasswordResult.js";
 import { HandlerBase } from "./HandlerBase.js";
 
+/*
+ * Base handler for reset password operation.
+ */
 abstract class ResetPasswordHandler extends HandlerBase {
+    /*
+     * Creates a new handler for reset password operation.
+     * @param correlationId - The correlationId for the request.
+     * @param continuationToken - The continuation token for the request.
+     * @param config - The configuration for the request.
+     * @param username - The username for the request.
+     */
     constructor(
         correlationId: string,
         continuationToken: string,
@@ -31,7 +41,15 @@ abstract class ResetPasswordHandler extends HandlerBase {
     }
 }
 
+/*
+ * Handler for reset password operations that require a code.
+ */
 export class ResetPasswordCodeRequiredHandler extends ResetPasswordHandler {
+    /*
+     * Submits a code for reset password.
+     * @param code - The code to submit.
+     * @returns The result of the operation.
+     */
     submitCode(code: string): Promise<ResetPasswordSubmitCodeResult> {
         if (!code) {
             return Promise.resolve(
@@ -44,12 +62,24 @@ export class ResetPasswordCodeRequiredHandler extends ResetPasswordHandler {
         throw new Error("Method not implemented.");
     }
 
+    /*
+     * Resends a code for reset password.
+     * @returns The result of the operation.
+     */
     resendCode(): Promise<ResetPasswordResendCodeResult> {
         throw new Error("Method not implemented.");
     }
 }
 
+/*
+ * Handler for reset password operations that require a password.
+ */
 export class ResetPasswordPasswordRequiredHandler extends ResetPasswordHandler {
+    /*
+     * Submits a password for reset password.
+     * @param password - The password to submit.
+     * @returns The result of the operation.
+     */
     sumbmitPassword(
         password: string
     ): Promise<ResetPasswordSubmitPasswordResult> {

lib/msal-native-auth/doc/tech-design/password-reset-seq.png

@@ -16,7 +16,18 @@ import {
 } from "../result/SignInResult.js";
 import { HandlerBase } from "./HandlerBase.js";
 
+/*
+ * Base handler for sign-in operations.
+ */
 abstract class SignInHandler extends HandlerBase {
+    /*
+     * Constructor for SignInHandler.
+     * @param signInClient - The client to use for sign-in operations.
+     * @param correlationId - The correlation ID for the request.
+     * @param continuationToken - The continuation token for the sign-in operation.
+     * @param config - The configuration for the client.
+     * @param scopes - The scopes to request during sign-in.
+     */
     constructor(
         protected signInClient: SigninClient,
         correlationId: string,
@@ -40,7 +51,15 @@ abstract class SignInHandler extends HandlerBase {
     }
 }
 
+/*
+ * Handler for sign-in operations that require a code.
+ */
 export class SignInCodeRequiredHandler extends SignInHandler {
+    /*
+     * Submits a code for sign-in.
+     * @param code - The code to submit.
+     * @returns The result of the operation.
+     */
     async submitCode(code: string): Promise<SignInSubmitCodeResult> {
         if (!code) {
             const result = SignInSubmitCodeResult.createWithError(
@@ -78,12 +97,24 @@ export class SignInCodeRequiredHandler extends SignInHandler {
         }
     }
 
+    /*
+     * Resends a code for sign-in.
+     * @returns The result of the operation.
+     */
     async resendCode(): Promise<SignInResendCodeResult> {
         throw new Error("Method not implemented.");
     }
 }
 
+/*
+ * Handler for sign-in operations that require a password.
+ */
 export class SignInPasswordRequiredHandler extends SignInHandler {
+    /*
+     * Submits a password for sign-in.
+     * @param password - The password to submit.
+     * @returns The result of the operation.
+     */
     async sumbmitPassword(
         password: string
     ): Promise<SignInSubmitPasswordResult> {
@@ -99,7 +130,17 @@ export class SignInPasswordRequiredHandler extends SignInHandler {
     }
 }
 
+/*
+ * Handler for sign-in operations that require a continuation token.
+ */
 export class SignInContinuationHandler extends HandlerBase {
+    /*
+     * Constructor for SignInContinuationHandler.
+     * @param correlationId - The correlation ID for the request.
+     * @param continuationToken - The continuation token for the sign-in operation.
+     * @param config - The configuration for the client.
+     * @param username - The username for the sign-in operation.
+     */
     constructor(
         correlationId: string,
         continuationToken: string,
@@ -121,6 +162,11 @@ export class SignInContinuationHandler extends HandlerBase {
         }
     }
 
+    /*
+     * Initiates the sign-in flow with continuation token.
+     * @param scopes - The scopes to request during sign-in.
+     * @returns The result of the operation.
+     */
     signIn(scopes?: Array<string>): Promise<SignInResult> {
         throw new Error(`Method not implemented with parameter: ${scopes}`);
     }

lib/msal-native-auth/doc/tech-design/signin-seq.png

@@ -14,7 +14,17 @@ import {
 } from "../result/SignUpResult.js";
 import { HandlerBase } from "./HandlerBase.js";
 
+/*
+ * Base handler for sign-up flow.
+ */
 abstract class SignUpHandler extends HandlerBase {
+    /*
+     * Creates a new SignUpHandler.
+     * @param correlationId - The correlation ID for the request.
+     * @param continuationToken - The continuation token for the request.
+     * @param config - The configuration for the request.
+     * @param username - The username for the request.
+     */
     constructor(
         correlationId: string,
         continuationToken: string,
@@ -33,7 +43,15 @@ abstract class SignUpHandler extends HandlerBase {
     }
 }
 
+/*
+ * Handler for sign-up operations that require a code.
+ */
 export class SignUpCodeRequiredHandler extends SignUpHandler {
+    /*
+     * Submits a code for sign-up.
+     * @param code - The code to submit.
+     * @returns The result of the operation.
+     */
     submitCode(code: string): Promise<SignUpSubmitCodeResult> {
         if (!code) {
             return Promise.resolve(
@@ -46,12 +64,24 @@ export class SignUpCodeRequiredHandler extends SignUpHandler {
         throw new Error("Method not implemented.");
     }
 
+    /*
+     * Resends a code for sign-up.
+     * @returns The result of the operation.
+     */
     resendCode(): Promise<SignUpResendCodeResult> {
         throw new Error("Method not implemented.");
     }
 }
 
+/*
+ * Handler for sign-up operations that require a password.
+ */
 export class SignUpPasswordRequiredHandler extends SignUpHandler {
+    /*
+     * Submits a password for sign-up.
+     * @param password - The password to submit.
+     * @returns The result of the operation.
+     */
     sumbmitPassword(password: string): Promise<SignUpSubmitPasswordResult> {
         if (!password) {
             return Promise.resolve(
@@ -65,7 +95,15 @@ export class SignUpPasswordRequiredHandler extends SignUpHandler {
     }
 }
 
+/*
+ * Handler for sign-up operations that require attributes.
+ */
 export class SignUpAttributesRequiredHandler extends SignUpHandler {
+    /*
+     * Submits attributes for sign-up.
+     * @param attributes - The attributes to submit.
+     * @returns The result of the operation.
+     */
     sumbmitAttributes(
         attributes: UserAccountAttributes
     ): Promise<SignUpSubmitAttributesResult> {

lib/msal-native-auth/doc/tech-design/signup-seq.png

@@ -6,4 +6,7 @@
 import { AuthenticationResult } from "@azure/msal-browser";
 import { ResultBase } from "./ResultBase.js";
 
+/*
+ * Result of getting an access token.
+ */
 export class GetAccessTokenResult extends ResultBase<AuthenticationResult> {}