improve exported type to include resolver and handlers for auth providers, add additional types to fix api-doc related warnings

Signed-off-by: Hasan Ozdemir <21654050+nodify-at@users.noreply.github.com>

plugins/auth-backend/api-report.md

@@ -47,6 +47,16 @@ export type AtlassianProviderOptions = {
   };
 };
 
+// @public
+export type AuthHandler<AuthResult> = (
+  input: AuthResult,
+) => Promise<AuthHandlerResult>;
+
+// @public
+export type AuthHandlerResult = {
+  profile: ProfileInfo;
+};
+
 // Warning: (ae-missing-release-tag) "AuthProviderFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -533,11 +543,6 @@ export type OAuthState = {
   origin?: string;
 };
 
-// Warning: (ae-missing-release-tag) "OidcAuthHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
-export type OidcAuthHandler = AuthHandler<OidcAuthResult>;
-
 // Warning: (ae-missing-release-tag) "OidcAuthResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -546,9 +551,9 @@ export type OidcAuthResult = {
   userinfo: UserinfoResponse;
 };
 
-// Warning: (ae-missing-release-tag) "OidcProviderOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+// Warning: (tsdoc-undefined-tag) The TSDoc tag "@BackstageSignInResult" is not defined in this configuration
 //
-// @public (undocumented)
+// @public
 export type OidcProviderOptions = {
   authHandler?: AuthHandler<OidcAuthResult>;
   signIn?: {
@@ -556,11 +561,6 @@ export type OidcProviderOptions = {
   };
 };
 
-// Warning: (ae-missing-release-tag) "OidcSignInResolver" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
-export type OidcSignInResolver = SignInResolver<OidcAuthResult>;
-
 // Warning: (ae-missing-release-tag) "oktaEmailSignInResolver" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -633,6 +633,22 @@ export type SamlProviderOptions = {
   };
 };
 
+// @public
+export type SignInInfo<AuthResult> = {
+  profile: ProfileInfo;
+  result: AuthResult;
+};
+
+// @public
+export type SignInResolver<AuthResult> = (
+  info: SignInInfo<AuthResult>,
+  context: {
+    tokenIssuer: TokenIssuer;
+    catalogIdentityClient: CatalogIdentityClient;
+    logger: Logger_2;
+  },
+) => Promise<BackstageSignInResult>;
+
 // Warning: (ae-missing-release-tag) "TokenIssuer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public
@@ -664,8 +680,6 @@ export type WebMessageResponse =
 // Warnings were encountered during analysis:
 //
 // src/identity/types.d.ts:31:9 - (ae-forgotten-export) The symbol "AnyJWK" needs to be exported by the entry point index.d.ts
-// src/providers/atlassian/provider.d.ts:37:5 - (ae-forgotten-export) The symbol "AuthHandler" needs to be exported by the entry point index.d.ts
-// src/providers/atlassian/provider.d.ts:42:9 - (ae-forgotten-export) The symbol "SignInResolver" needs to be exported by the entry point index.d.ts
 // src/providers/aws-alb/provider.d.ts:77:5 - (ae-forgotten-export) The symbol "AwsAlbResult" needs to be exported by the entry point index.d.ts
 // src/providers/github/provider.d.ts:71:58 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag
 // src/providers/github/provider.d.ts:71:90 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag

plugins/auth-backend/src/providers/index.ts

@@ -34,6 +34,10 @@ export type {
   AuthProviderRouteHandlers,
   AuthProviderFactoryOptions,
   AuthProviderFactory,
+  AuthHandler,
+  AuthHandlerResult,
+  SignInResolver,
+  SignInInfo,
 } from './types';
 
 // These types are needed for a postMessage from the login pop-up

plugins/auth-backend/src/providers/oidc/index.ts

@@ -13,10 +13,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export type {
-  OidcSignInResolver,
-  OidcAuthHandler,
-  OidcAuthResult,
-  OidcProviderOptions,
-} from './provider';
+export type { OidcAuthResult, OidcProviderOptions } from './provider';
 export { createOidcProvider } from './provider';

plugins/auth-backend/src/providers/oidc/provider.ts

@@ -61,16 +61,13 @@ export type OidcAuthResult = {
   userinfo: UserinfoResponse;
 };
 
-export type OidcSignInResolver = SignInResolver<OidcAuthResult>;
-export type OidcAuthHandler = AuthHandler<OidcAuthResult>;
-
 export type Options = OAuthProviderOptions & {
   metadataUrl: string;
   scope?: string;
   prompt?: string;
   tokenSignedResponseAlg?: string;
-  signInResolver?: OidcSignInResolver;
-  authHandler: OidcAuthHandler;
+  signInResolver?: SignInResolver<OidcAuthResult>;
+  authHandler: AuthHandler<OidcAuthResult>;
   tokenIssuer: TokenIssuer;
   catalogIdentityClient: CatalogIdentityClient;
   logger: Logger;
@@ -227,6 +224,18 @@ export const oAuth2DefaultSignInResolver: SignInResolver<OidcAuthResult> =
     return { id: userId, token };
   };
 
+/**
+ * OIDC provider callback options. An auth handler and a sign in resolver
+ * can be passed while creating a OIDC provider.
+ *
+ * authHandler : called after sign in was successful, a new object must be returned which includes a profile
+ * signInResolver: called after sign in was successful, expects to return a new @BackstageSignInResult
+ *
+ * Both options are optional. There is fallback for authHandler where the default handler expect an e-mail explicitly
+ * otherwise it throws an error
+ *
+ * @public
+ */
 export type OidcProviderOptions = {
   authHandler?: AuthHandler<OidcAuthResult>;
 

plugins/auth-backend/src/providers/types.ts

@@ -240,6 +240,10 @@ export type ProfileInfo = {
   picture?: string;
 };
 
+/**
+ * type of sign in information context, includes the profile information and authentication result which contains auth. related information
+ * @public
+ */
 export type SignInInfo<AuthResult> = {
   /**
    * The simple profile passed down for use in the frontend.
@@ -252,6 +256,11 @@ export type SignInInfo<AuthResult> = {
   result: AuthResult;
 };
 
+/**
+ * Sign in resolver type describes the function which handles the result of a successful authentication
+ * and must return a valid BackStageSignInResult
+ * @public
+ */
 export type SignInResolver<AuthResult> = (
   info: SignInInfo<AuthResult>,
   context: {
@@ -261,6 +270,10 @@ export type SignInResolver<AuthResult> = (
   },
 ) => Promise<BackstageSignInResult>;
 
+/**
+ * The return type of authentication handler which must contain a valid profile information
+ * @public
+ */
 export type AuthHandlerResult = { profile: ProfileInfo };
 
 /**
@@ -270,6 +283,8 @@ export type AuthHandlerResult = { profile: ProfileInfo };
  *
  * Throwing an error in the function will cause the authentication to fail, making it
  * possible to use this function as a way to limit access to a certain group of users.
+ *
+ * @public
  */
 export type AuthHandler<AuthResult> = (
   input: AuthResult,