@genesislcap/foundation-auth 14.408.0 → 14.409.0

package/README.md

@@ -1,243 +1,25 @@
-# Foundation Auth
+# @genesislcap/foundation-auth
 
-[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/)
-[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/)
+Documentation for this package is published on the Genesis docs site:
 
-`foundation-auth` is a fully featured authentication micro frontend that is http and cookies based. It allows your
-application to provide a more efficient and secure authentication experience, and enables functionality like popout
-windows. The package differs from `foundation-login` which authenticated over websockets and is now considered
-deprecated.
-
-`foundation-auth` provides several exports to promote reuse and extensibility at various levels. These include but are
-not limited to:
-
-* `ZeroAuth`: A preconfigured version of the micro frontend built with the zero design system and zero components.
-* `configure`: A customisation hook for the base micro frontend that integrates it with your design system of choice.
-* `AuthStore`: An auth based [foundation-store](https://www.npmjs.com/package/@genesislcap/foundation-store).
-* `AuthMachine`: An auth based [foundation-state-machine](https://www.npmjs.com/package/@genesislcap/foundation-state-machine) covering the various auth workflows.
-* `AuthMessageMapper`: The auth message dto to entity [mapper](./src/mapper/README.md).
-* `AuthRouting`: A routing utility, which you can call `navigateTo(...)` to navigate to internal routes.
-* Various UI components / route screens, some of which are lazy loaded on-demand to optimise the experience.
-
-For applications that do not or cannot use the DI system, we export utility functions to get each from the DI container.
-For example, `getAuthStore`, `getAuthMachine`, `getAuthRouting` etc.
-
-Many of these are available as [subpath exports](https://nodejs.org/api/packages.html#subpath-exports) and should be
-imported from these to optimise bundling and overall efficiency.
-
-```ts
-import { configure } from '@genesislcap/foundation-auth/configure';
-import { AuthRouting } from '@genesislcap/foundation-auth/routing';
-// note zero is on the root export
-import { ZeroAuth } from '@genesislcap/foundation-auth';
-```
-
-In most cases, developers simply import the `ZeroAuth` micro frontend, or use the `configure` export
-token to tailor the micro frontend to their specific needs in their router config. However, developers can also use the
-exports provided to build their own authentication frontends or workflows. A set of pre-defined custom events are used
-to interact with the `AuthStore` and `AuthMachine`, and developers can provide custom implementations of parts of the
-machine's workflow.
-
-## Basic setup instructions
-These examples are based on a host application using [FAST](https://www.fast.design/) and the
-[FASTRouter](https://www.npmjs.com/package/@microsoft/fast-router). However, setup in the frontend and router of your
-choice should be quite similar. 
-
-## Environment variables
-`foundation-auth` uses the following environment variables. The `.env` file below shows the built-in defaults used with `API_HOST`.
-
-```dotenv
-# There should be nothing sensitive here!
-
-# HTTP
-GENX_LOGIN_URL=/sm/event-login-auth
-GENX_LOGIN_REFRESH_URL=/sm/event-login-auth
-GENX_LOGIN_DETAILS_URL=/sm/event-login-details
-GENX_LOGOUT_URL=/sm/event-logout
-GENX_CHANGE_PASSWORD_URL=/sm/event-change-user-password
-GENX_FORGOT_PASSWORD_URL=/sm/event-self-service-password-reset
-GENX_RESET_PASSWORD_URL=/sm/event-password-reset-action
-
-# SSO (type and id will be replaced on runtime idp selection)
-GENX_SSO_LIST_URL=/sm/sso/list
-GENX_SSO_LOGIN_URL=/sm/{type}/login?idp={id}
-```
-
-If you are happy with these defaults then you have nothing more to do.
-
-Here is an example of loading environment variables contained in a `.env` file into a webpack build, but how you set
-environment variables at an app level is really up to you.
-
-```js
-const { resolveDefineConfig } = require('@genesislcap/build-kit'); // < npm install @genesislcap/build-kit --save
-const { config } = require('dotenv'); // < npm install dotenv --save
-const { DefinePlugin } = require('webpack');
-
-config(); // < loads the .env vars
-
-module.exports = {
-  ...
-  plugins: [
-    new DefinePlugin(resolveDefineConfig(['GENX_*'])), // < code replacement should include 'API_HOST' if set, ie. ['GENX_*', 'API_HOST', ...]
-  ],
-}
-```
-
-### Set up a route to host the micro frontend
-Here we are lazy loading the micro frontend when the route is accessed.
-```ts
-{
-  title: 'Authenticate',
-  name: 'auth',
-  path: 'auth', // < at what path should the micro frontend be accessed. Could be an empty string, ie. on the website root.
-  element: async () => {
-    const { configure } = await import('@genesislcap/foundation-auth/config');
-    return configure({
-      omitRoutes: ['request-account'],
-      hostPath: 'auth', // < important to match the route path
-      logo: myLogo,
-      background: myBG,
-      postLoginRedirect: () => {
-        // You could inspect the user here and route them based on various conditions.
-        Route.path.push('my-dashboard');
-      },
-    });
-  },
-  childRouters: true,
-  settings: { public: true },
-  layout: authLayout,
-}
-```
-
-### Checking the user authentication status during routing
-Here in our `FASTRouter`'s `NavigationContributor`, we check the user status as part of the routing flow.
-
-```ts
-import { User } from '@genesislcap/foundation-user';
-...
-@User private user: User;
-...
-this.contributors.push({
-  navigate: async (phase) => {
-    const settings = phase.route.settings;
-    /**
-     * Don't block public routes or any routes when authenticated
-     */
-    if (settings?.public || this.user.isAuthenticated) {
-      return;
-    }
-    /**
-     * Otherwise route them to auth
-     */
-    phase.cancel(() => {
-      this.user.trackPath(); // < Track the user's path to return to it post login if required
-      Route.name.replace(phase.router, 'auth');
-    });
-  },
-});
-```
-
-### Establishing a Websocket Connection
-Creating an actual websocket connection to the Genesis backend is beyond the scope of `foundation-auth`. Post login you
-can import the `API_HOST` from `@genesislcap/foundation-utils` and connect to the Genesis backend. Below uses `connect`
-from the DI container.
-
-```ts
-import { API_HOST } from '@genesislcap/foundation-utils';
-...
-@Connect private connect: Connect,
-...
-this.connect.connect(API_HOST);
-```
-
-### Logging out
-You can logout easily by navigating to the logout route. To help, you can access the `AuthRouting` singleton via the DI
-container from anywhere in your app, such as a header's logout button, and call `navigateTo`.
-```ts
-import { AuthRouting } from '@genesislcap/foundation-auth/routing';
-...
-@AuthRouting private authRouting: AuthRouting;
-...
-this.authRouting.navigateTo('logout');
-```
-
-...or via a utility if your app is not using decorators or the DI container.
-
-```ts
-import { getAuthRouting } from '@genesislcap/foundation-auth/routing';
-...
-private authRouting = getAuthRouting();
-...
-this.authRouting.navigateTo('logout');
-```
-
-You can use `AuthRouting` to navigate to other routes, like change password etc., without needing to know the full
-path the micro frontend is hosted on.
-
-If you have trouble logging out using the routing utility, you can try using your host app's router directly.
-
-The following example is Angular based, where the developer has put the micro frontend on the `auth` path. There's logic
-within the micro frontend that will automatically navigate itself to the logout route if the login screen is loaded
-while the user is already logged in. Logging out is as easy as moving back to that route.
-
-```ts
-import { Router } from '@angular/router';
-
-export class AppComponent {
-  constructor(private router: Router) {}
-  /**
-   * Note the developer has put the micro frontend of the `auth` path.
-   */
-  onLogout() {
-    /**
-     * Navigate back to the micro frontend and it will take care of the logout.
-     */
-    this.router.navigateByUrl('auth');
-    /**
-     * Alternatively, you can navigate to the internal logout route.
-     * this.router.navigateByUrl('auth/logout');
-     */
-  }
-}
-```
-
-See the [AuthRouting API Docs](./docs/api/foundation-auth.authrouting.md) for more information.
-
-## [API Docs](./docs/api/index.md)
-
-## Troubleshooting
-
-* We're using `foundation-login`, do we have to move to `foundation-auth`?
-  * *`foundation-login` authenticated over websockets and is now considered deprecated, but it will still work for the time being. Moving is advised and should be pretty seamless.*
-* We're using `configure` but are not seeing our changes reflected?
-  * *Ensure you're importing `configure` from the `/config` subpath and not the root of the package.*
-  * *Ensure you're not importing anything from the root of the package elsewhere in your application.*
-* The `Forgot Password?`, `Change Password` and `Request Account` links don't seem to do anything.
-  * *If you're hosting the micro frontend on anything other than the top level root path `''`, for example: `path: 'auth'`, then ensure the `hostPath` property in the `configure` matches.*
+**Docs: [Login](https://docs.genesis.global/docs/develop/client-capabilities/login/)**
 
 ## Installation
 
-To enable this module in your application, follow the steps below.
-
-1. Add `@genesislcap/foundation-auth` as a dependency in your `package.json` file. Whenever you change the dependencies of your project, ensure you run the `$ npm run bootstrap` command again. You can find more information in the [package.json basics](https://learn.genesis.global/secure/web/basics/package-json-basics/) page.
+Add the package to your `package.json` dependencies. After changing dependencies, run `npm run bootstrap` (or your project's equivalent). See [package.json basics](https://learn.genesis.global/secure/web/basics/package-json-basics/) for more information.
 
 ```json
 {
-  ...
   "dependencies": {
-    ...
     "@genesislcap/foundation-auth": "latest"
-    ...
-  },
-  ...
+  }
 }
 ```
 
-## [API Docs](./docs/api/index.md)
-
 ## License
 
 Note: this project provides front-end dependencies and uses licensed components listed in the next section; thus, licenses for those components are required during development. Contact [Genesis Global](https://genesis.global/contact-us/) for more details.
 
 ### Licensed components
+
 Genesis low-code platform

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-auth",
   "description": "Genesis Foundation Auth",
-  "version": "14.408.0",
+  "version": "14.409.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/foundation-auth.d.ts",
@@ -129,25 +129,25 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.408.0",
-    "@genesislcap/genx": "14.408.0",
-    "@genesislcap/rollup-builder": "14.408.0",
-    "@genesislcap/ts-builder": "14.408.0",
-    "@genesislcap/uvu-playwright-builder": "14.408.0",
-    "@genesislcap/vite-builder": "14.408.0",
-    "@genesislcap/webpack-builder": "14.408.0"
+    "@genesislcap/foundation-testing": "14.409.0",
+    "@genesislcap/genx": "14.409.0",
+    "@genesislcap/rollup-builder": "14.409.0",
+    "@genesislcap/ts-builder": "14.409.0",
+    "@genesislcap/uvu-playwright-builder": "14.409.0",
+    "@genesislcap/vite-builder": "14.409.0",
+    "@genesislcap/webpack-builder": "14.409.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-comms": "14.408.0",
-    "@genesislcap/foundation-events": "14.408.0",
-    "@genesislcap/foundation-i18n": "14.408.0",
-    "@genesislcap/foundation-logger": "14.408.0",
-    "@genesislcap/foundation-state-machine": "14.408.0",
-    "@genesislcap/foundation-store": "14.408.0",
-    "@genesislcap/foundation-ui": "14.408.0",
-    "@genesislcap/foundation-user": "14.408.0",
-    "@genesislcap/foundation-utils": "14.408.0",
-    "@genesislcap/foundation-zero": "14.408.0",
+    "@genesislcap/foundation-comms": "14.409.0",
+    "@genesislcap/foundation-events": "14.409.0",
+    "@genesislcap/foundation-i18n": "14.409.0",
+    "@genesislcap/foundation-logger": "14.409.0",
+    "@genesislcap/foundation-state-machine": "14.409.0",
+    "@genesislcap/foundation-store": "14.409.0",
+    "@genesislcap/foundation-ui": "14.409.0",
+    "@genesislcap/foundation-user": "14.409.0",
+    "@genesislcap/foundation-utils": "14.409.0",
+    "@genesislcap/foundation-zero": "14.409.0",
     "@microsoft/fast-components": "2.30.6",
     "@microsoft/fast-element": "1.14.0",
     "@microsoft/fast-foundation": "2.50.0",
@@ -167,5 +167,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "26b08831fd001b4ee95c8a0d3364a18c0ec4005b"
+  "gitHead": "cbe0459d170f27c35a7de18cec415947aedf4da5"
 }

package/docs/api/foundation-auth.accepttermsparams.md

@@ -1,17 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-auth](./foundation-auth.md) &gt; [AcceptTermsParams](./foundation-auth.accepttermsparams.md)
-
-## AcceptTermsParams type
-
-
-**Signature:**
-
-```typescript
-export type AcceptTermsParams = {
-    username?: string;
-    orgUsername?: string;
-    termsAgreed?: boolean;
-    version?: string;
-};
-```

package/docs/api/foundation-auth.authconfig.background.md

@@ -1,30 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-auth](./foundation-auth.md) &gt; [AuthConfig](./foundation-auth.authconfig.md) &gt; [background](./foundation-auth.authconfig.background.md)
-
-## AuthConfig.background property
-
-Background styles.
-
-**Signature:**
-
-```typescript
-background: ComposableStyles | ComposableStyles[] | null;
-```
-
-## Remarks
-
-Providing `null` will hide the background. The format examples from [AuthConfig.logo](./foundation-auth.authconfig.logo.md) apply here too. See also [https://developer.mozilla.org/en-US/docs/Web/CSS/background](https://developer.mozilla.org/en-US/docs/Web/CSS/background) for more information.
-
-## Example
-
-Setting a custom background image
-
-```ts
-background: `
-    :host {
-        background-image: url(${customBGImport});
-    }
-`,
-```
-

package/docs/api/foundation-auth.authconfig.backgroundvideo.md

@@ -1,21 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-auth](./foundation-auth.md) &gt; [AuthConfig](./foundation-auth.authconfig.md) &gt; [backgroundVideo](./foundation-auth.authconfig.backgroundvideo.md)
-
-## AuthConfig.backgroundVideo property
-
-Background video.
-
-**Signature:**
-
-```typescript
-backgroundVideo: {
-        src: string;
-        type: 'video/ogg' | 'video/mp4' | 'video/webm';
-    } | null;
-```
-
-## Remarks
-
-Overlays any background image if set. Defaults to `null`<!-- -->.
-

package/docs/api/foundation-auth.authconfig.feedbackdelay.md

@@ -1,18 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-auth](./foundation-auth.md) &gt; [AuthConfig](./foundation-auth.authconfig.md) &gt; [feedbackDelay](./foundation-auth.authconfig.feedbackdelay.md)
-
-## AuthConfig.feedbackDelay property
-
-Feedback delay.
-
-**Signature:**
-
-```typescript
-feedbackDelay?: number;
-```
-
-## Remarks
-
-The amount of seconds to display user feedback messages, such as "check your inbox" etc. Defaults to 3 seconds.
-

package/docs/api/foundation-auth.authconfig.fields.md

@@ -1,18 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-auth](./foundation-auth.md) &gt; [AuthConfig](./foundation-auth.authconfig.md) &gt; [fields](./foundation-auth.authconfig.fields.md)
-
-## AuthConfig.fields property
-
-Map of configuration for each of the primary form fields.
-
-**Signature:**
-
-```typescript
-fields: FieldConfigMap;
-```
-
-## Remarks
-
-Use to drive inclusion / exclusion, tailor labels etc.
-

package/docs/api/foundation-auth.authconfig.hostpath.md

@@ -1,18 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-auth](./foundation-auth.md) &gt; [AuthConfig](./foundation-auth.authconfig.md) &gt; [hostPath](./foundation-auth.authconfig.hostpath.md)
-
-## AuthConfig.hostPath property
-
-The `path` of the micro frontend as defined in the parent / host route.
-
-**Signature:**
-
-```typescript
-hostPath: string;
-```
-
-## Remarks
-
-Used to help resolve internal route links. Defaults to an empty string.
-

package/docs/api/foundation-auth.authconfig.localizationresources.md

@@ -1,36 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-auth](./foundation-auth.md) &gt; [AuthConfig](./foundation-auth.authconfig.md) &gt; [localizationResources](./foundation-auth.authconfig.localizationresources.md)
-
-## AuthConfig.localizationResources property
-
-I18n resources.
-
-**Signature:**
-
-```typescript
-localizationResources?: I18nextConfig['resources'];
-```
-
-## Remarks
-
-This property holds the localization resources needed for internationalization of the application. It should follow the structure defined by the I18nextConfig interface, which includes translations grouped by locale and namespace. Each locale can contain multiple namespaces, and each namespace includes key-value pairs for translation strings.
-
-## Example
-
-
-```ts
-resources: {
-  en: {
-    'foundation-auth': {
-      key: 'Hello World'
-    }
-  },
-  es: {
-    'foundation-auth': {
-      key: 'Hola Mundo'
-    }
-  }
-}
-```
-

package/docs/api/foundation-auth.authconfig.logo.md

@@ -1,40 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-auth](./foundation-auth.md) &gt; [AuthConfig](./foundation-auth.authconfig.md) &gt; [logo](./foundation-auth.authconfig.logo.md)
-
-## AuthConfig.logo property
-
-Logo styles.
-
-**Signature:**
-
-```typescript
-logo: ComposableStyles | ComposableStyles[] | null;
-```
-
-## Remarks
-
-Providing `null` will hide the logo. Use content: url(...); to set source.
-
-## Example 1
-
-Setting a custom logo using a plain template literal
-
-```ts
-logo: `
-    content: url(${customLogoImport});
-`,
-```
-
-## Example 2
-
-Setting a custom logo using FASTElement's `css` helper or a pre-created ElementStyles instance when your host app is FAST based
-
-```ts
-logo: css`
-    content: url(${customLogoImport});
-`,
-...
-logo: LogoElementStyles,
-```
-

package/docs/api/foundation-auth.authconfig.logoalttext.md

@@ -1,13 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-auth](./foundation-auth.md) &gt; [AuthConfig](./foundation-auth.authconfig.md) &gt; [logoAltText](./foundation-auth.authconfig.logoalttext.md)
-
-## AuthConfig.logoAltText property
-
-Logo alt text.
-
-**Signature:**
-
-```typescript
-logoAltText: string;
-```