@openedx/frontend-base 1.0.0-alpha.0

package/runtime/auth/interface.js

@@ -0,0 +1,309 @@
+/**
+ * #### Import members from **@openedx/frontend-base**
+ *
+ * Simplifies the process of making authenticated API requests to backend edX services by providing
+ * common authN/authZ client code that enables the login/logout flow and handles ensuring the
+ * presence of a valid [JWT cookie](https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/oauth_dispatch/docs/decisions/0009-jwt-in-session-cookie.rst).
+ *
+ * The `initialize` function performs much of the auth configuration for you.  If, however, you're
+ * not using the `initialize` function, an authenticated API client can be created via:
+ *
+ * ```
+ * import {
+ *   configureAuth,
+ *   fetchAuthenticatedUser,
+ *   getAuthenticatedHttpClient,
+ *   getSiteConfig,
+ *   getLoggingService
+ * } from '@openedx/frontend-base';
+ *
+ * configureAuth({
+ *   loggingService: getLoggingService(),
+ *   config: getSiteConfig(),
+ * });
+ *
+ * const authenticatedUser = await fetchAuthenticatedUser(); // validates and decodes JWT token
+ * const authenticatedHttpClient = getAuthenticatedHttpClient();
+ * const response = await getAuthenticatedHttpClient().get(`https://example.com/api/user/data/${authenticatedUser.username}`); // fetching from an authenticated API using user data
+ * ```
+ *
+ * As shown in this example, auth depends on the configuration document and logging.
+ *
+ * NOTE: The documentation for AxiosJwtAuthService is nearly the same as that for the top-level
+ * auth interface, except that it contains some Axios-specific details.
+ *
+ * @module Auth
+ */
+import PropTypes from 'prop-types';
+import { publish } from '../subscriptions';
+
+/**
+ * @constant
+ * @private
+ */
+export const AUTHENTICATED_USER_TOPIC = 'AUTHENTICATED_USER';
+
+/**
+ * Published when the authenticated user data changes.  This can happen when the authentication
+ * service determines that the user is authenticated or anonymous, as well as when we fetch
+ * additional user account data if the `hydrateAuthenticatedUser` flag has been set in the
+ * `initialize` function.
+ *
+ * @event
+ * @see {@link module:Initialization~initialize}
+ */
+export const AUTHENTICATED_USER_CHANGED = `${AUTHENTICATED_USER_TOPIC}.CHANGED`;
+
+const optionsShape = {
+  config: PropTypes.shape({
+    baseUrl: PropTypes.string.isRequired,
+    lmsBaseUrl: PropTypes.string.isRequired,
+    loginUrl: PropTypes.string.isRequired,
+    logoutUrl: PropTypes.string.isRequired,
+    refreshAccessTokenApiPath: PropTypes.string.isRequired,
+    accessTokenCookieName: PropTypes.string.isRequired,
+    csrfTokenApiPath: PropTypes.string.isRequired,
+  }).isRequired,
+  loggingService: PropTypes.shape({
+    logError: PropTypes.func.isRequired,
+    logInfo: PropTypes.func.isRequired,
+  }).isRequired,
+};
+
+const serviceShape = {
+  getAuthenticatedHttpClient: PropTypes.func.isRequired,
+  getHttpClient: PropTypes.func.isRequired,
+  getLoginRedirectUrl: PropTypes.func.isRequired,
+  redirectToLogin: PropTypes.func.isRequired,
+  getLogoutRedirectUrl: PropTypes.func.isRequired,
+  redirectToLogout: PropTypes.func.isRequired,
+  getAuthenticatedUser: PropTypes.func.isRequired,
+  setAuthenticatedUser: PropTypes.func.isRequired,
+  fetchAuthenticatedUser: PropTypes.func.isRequired,
+  ensureAuthenticatedUser: PropTypes.func.isRequired,
+  hydrateAuthenticatedUser: PropTypes.func.isRequired,
+};
+
+let service;
+
+/**
+ *
+ * @param {class} AuthService
+ * @param {*} options
+ * @returns {AuthService}
+ */
+export function configureAuth(AuthService, options) {
+  PropTypes.checkPropTypes(optionsShape, options, 'property', 'Auth');
+  service = new AuthService(options);
+  PropTypes.checkPropTypes(serviceShape, service, 'property', 'AuthService');
+  return service;
+}
+
+/**
+ *
+ *
+ * @returns {AuthService}
+ */
+export function getAuthService() {
+  if (!service) {
+    throw Error('You must first configure the auth service.');
+  }
+
+  return service;
+}
+
+/**
+ *
+ */
+export function resetAuthService() {
+  service = null;
+}
+
+/**
+ * Gets the authenticated HTTP client for the service.
+ *
+ * @param {Object} [options] Optional options for how to configure the authenticated HTTP client
+ * @param {boolean} [options.useCache] Whether to use front end caching for all requests made with the returned client
+ *
+ * @returns {HttpClient}
+ */
+export function getAuthenticatedHttpClient(options = {}) {
+  return service.getAuthenticatedHttpClient(options);
+}
+
+/**
+ * Gets the unauthenticated HTTP client for the service.
+ *
+ * @param {Object} [options] Optional options for how to configure the authenticated HTTP client
+ * @param {boolean} [options.useCache] Whether to use front end caching for all requests made with the returned client
+ *
+ * @returns {HttpClient}
+ */
+export function getHttpClient(options = {}) {
+  return service.getHttpClient(options);
+}
+
+/**
+ * Builds a URL to the login page with a post-login redirect URL attached as a query parameter.
+ *
+ * ```
+ * const url = getLoginRedirectUrl('http://localhost/mypage');
+ * console.log(url); // http://localhost/login?next=http%3A%2F%2Flocalhost%2Fmypage
+ * ```
+ *
+ * @param {string} redirectUrl The URL the user should be redirected to after logging in.
+ */
+export function getLoginRedirectUrl(redirectUrl) {
+  return service.getLoginRedirectUrl(redirectUrl);
+}
+
+/**
+ * Redirects the user to the login page.
+ *
+ * @param {string} redirectUrl The URL the user should be redirected to after logging in.
+ */
+export function redirectToLogin(redirectUrl) {
+  return service.redirectToLogin(redirectUrl);
+}
+
+/**
+ * Builds a URL to the logout page with a post-logout redirect URL attached as a query parameter.
+ *
+ * ```
+ * const url = getLogoutRedirectUrl('http://localhost/mypage');
+ * console.log(url); // http://localhost/logout?redirect_url=http%3A%2F%2Flocalhost%2Fmypage
+ * ```
+ *
+ * @param {string} redirectUrl The URL the user should be redirected to after logging out.
+ */
+export function getLogoutRedirectUrl(redirectUrl) {
+  return service.getLogoutRedirectUrl(redirectUrl);
+}
+
+/**
+ * Redirects the user to the logout page.
+ *
+ * @param {string} redirectUrl The URL the user should be redirected to after logging out.
+ */
+export function redirectToLogout(redirectUrl) {
+  return service.redirectToLogout(redirectUrl);
+}
+
+/**
+ * If it exists, returns the user data representing the currently authenticated user. If the
+ * user is anonymous, returns null.
+ *
+ * @returns {UserData|null}
+ */
+export function getAuthenticatedUser() {
+  return service.getAuthenticatedUser();
+}
+
+/**
+ * Sets the authenticated user to the provided value.
+ *
+ * @param {UserData} authUser
+ * @emits AUTHENTICATED_USER_CHANGED
+ */
+export function setAuthenticatedUser(authUser) {
+  service.setAuthenticatedUser(authUser);
+  publish(AUTHENTICATED_USER_CHANGED);
+}
+
+/**
+ * Reads the authenticated user's access token. Resolves to null if the user is
+ * unauthenticated.
+ *
+ * @returns {Promise<UserData>|Promise<null>} Resolves to the user's access token if they are
+ * logged in.
+ */
+export async function fetchAuthenticatedUser(options = {}) {
+  return service.fetchAuthenticatedUser(options);
+}
+
+/**
+ * Ensures a user is authenticated. It will redirect to login when not
+ * authenticated.
+ *
+ * @param {string} [redirectUrl=config.baseUrl] to return user after login when not
+ * authenticated.
+ * @returns {Promise<UserData>}
+ */
+export async function ensureAuthenticatedUser(redirectUrl) {
+  return service.ensureAuthenticatedUser(redirectUrl);
+}
+
+/**
+ * Fetches additional user account information for the authenticated user and merges it into the
+ * existing authenticatedUser object, available via getAuthenticatedUser().
+ *
+ * ```
+ *  console.log(authenticatedUser); // Will be sparse and only contain basic information.
+ *  await hydrateAuthenticatedUser()
+ *  const authenticatedUser = getAuthenticatedUser();
+ *  console.log(authenticatedUser); // Will contain additional user information
+ * ```
+ *
+ * @emits AUTHENTICATED_USER_CHANGED
+ */
+export async function hydrateAuthenticatedUser() {
+  await service.hydrateAuthenticatedUser();
+  publish(AUTHENTICATED_USER_CHANGED);
+}
+
+/**
+ * @name AuthService
+ * @interface
+ * @memberof module:Auth
+ * @property {function} getAuthenticatedHttpClient
+ * @property {function} getHttpClient
+ * @property {function} getLoginRedirectUrl
+ * @property {function} redirectToLogin
+ * @property {function} getLogoutRedirectUrl
+ * @property {function} redirectToLogout
+ * @property {function} getAuthenticatedUser
+ * @property {function} setAuthenticatedUser
+ * @property {function} fetchAuthenticatedUser
+ * @property {function} ensureAuthenticatedUser
+ * @property {function} hydrateAuthenticatedUser
+ */
+
+/**
+ * A configured axios client. See axios docs for more
+ * info https://github.com/axios/axios. All the functions
+ * below accept isPublic and isCsrfExempt in the request
+ * config options. Setting these to true will prevent this
+ * client from attempting to refresh the jwt access token
+ * or a csrf token respectively.
+ *
+ * ```
+ *  // A public endpoint (no jwt token refresh)
+ *  apiClient.get('/path/to/endpoint', { isPublic: true });
+ * ```
+ *
+ * ```
+ *  // A csrf exempt endpoint
+ *  apiClient.post('/path/to/endpoint', { data }, { isCsrfExempt: true });
+ * ```
+ *
+ * @name HttpClient
+ * @interface
+ * @memberof module:Auth
+ * @property {function} get
+ * @property {function} head
+ * @property {function} options
+ * @property {function} delete (csrf protected)
+ * @property {function} post (csrf protected)
+ * @property {function} put (csrf protected)
+ * @property {function} patch (csrf protected)
+ */
+
+/**
+ * @name UserData
+ * @interface
+ * @memberof module:Auth
+ * @property {string} userId
+ * @property {string} username
+ * @property {Array} roles
+ * @property {boolean} administrator
+ */

package/runtime/auth/utils.js

@@ -0,0 +1,105 @@
+// Lifted from here: https://regexr.com/3ok5o
+const urlRegex = /([a-z]{1,2}tps?):\/\/((?:(?!(?:\/|#|\?|&)).)+)(?:(\/(?:(?:(?:(?!(?:#|\?|&)).)+\/))?))?(?:((?:(?!(?:\.|$|\?|#)).)+))?(?:(\.(?:(?!(?:\?|$|#)).)+))?(?:(\?(?:(?!(?:$|#)).)+))?(?:(#.+))?/;
+const getUrlParts = (url) => {
+  const found = url.match(urlRegex);
+  try {
+    const [
+      fullUrl,
+      protocol,
+      domain,
+      path,
+      endFilename,
+      endFileExtension,
+      query,
+      hash,
+    ] = found;
+
+    return {
+      fullUrl,
+      protocol,
+      domain,
+      path,
+      endFilename,
+      endFileExtension,
+      query,
+      hash,
+    };
+  } catch (e) {
+    throw new Error(`Could not find url parts from ${url}.`);
+  }
+};
+
+const logFrontendAuthError = (loggingService, error) => {
+  const prefixedMessageError = Object.create(error);
+  prefixedMessageError.message = `[frontend-auth] ${error.message}`;
+  loggingService.logError(prefixedMessageError, prefixedMessageError.customAttributes);
+};
+
+const processAxiosError = (axiosErrorObject) => {
+  const error = Object.create(axiosErrorObject);
+  const { request, response, config } = error;
+
+  if (!config) {
+    error.customAttributes = {
+      ...error.customAttributes,
+      httpErrorType: 'unknown-api-request-error',
+    };
+    return error;
+  }
+
+  const {
+    url: httpErrorRequestUrl,
+    method: httpErrorRequestMethod,
+  } = config;
+  /* istanbul ignore else: difficult to enter the request-only error case in a unit test */
+  if (response) {
+    const { status, data } = response;
+    const stringifiedData = JSON.stringify(data) || '(empty response)';
+    const responseIsHTML = stringifiedData.includes('<!DOCTYPE html>');
+    // Don't include data if it is just an HTML document, like a 500 error page.
+    /* istanbul ignore next */
+    const httpErrorResponseData = responseIsHTML ? '<Response is HTML>' : stringifiedData;
+    error.customAttributes = {
+      ...error.customAttributes,
+      httpErrorType: 'api-response-error',
+      httpErrorStatus: status,
+      httpErrorResponseData,
+      httpErrorRequestUrl,
+      httpErrorRequestMethod,
+    };
+    error.message = `Axios Error (Response): ${status} - See custom attributes for details.`;
+  } else if (request) {
+    error.customAttributes = {
+      ...error.customAttributes,
+      httpErrorType: 'api-request-error',
+      httpErrorMessage: error.message,
+      httpErrorRequestUrl,
+      httpErrorRequestMethod,
+    };
+    // This case occurs most likely because of intermittent internet connection issues
+    // but it also, though less often, catches CORS or server configuration problems.
+    error.message = 'Axios Error (Request): (Possible local connectivity issue.) See custom attributes for details.';
+  } else {
+    error.customAttributes = {
+      ...error.customAttributes,
+      httpErrorType: 'api-request-config-error',
+      httpErrorMessage: error.message,
+      httpErrorRequestUrl,
+      httpErrorRequestMethod,
+    };
+    error.message = 'Axios Error (Config): See custom attributes for details.';
+  }
+
+  return error;
+};
+
+const processAxiosErrorAndThrow = (axiosErrorObject) => {
+  throw processAxiosError(axiosErrorObject);
+};
+
+export {
+  getUrlParts,
+  logFrontendAuthError,
+  processAxiosError,
+  processAxiosErrorAndThrow
+};

package/runtime/babel.config.js

@@ -0,0 +1,3 @@
+const config = require('../tools/babel/babel.config');
+
+module.exports = config;

package/runtime/config/index.ts

@@ -0,0 +1,295 @@
+/**
+ * #### Import members from **@edx/frontend-base**
+ *
+ * The configuration module provides utilities for working with an application's configuration
+ * document (SiteConfig).  Configuration variables can be supplied to the
+ * application in three different ways.  They are applied in the following order:
+ *
+ * - Site Configuration File (site.config.tsx)
+ * - Initialization Config Handler
+ * - Runtime Configuration
+ *
+ * Last one in wins, and are deep merged together.  Variables with the same name defined via the
+ * later methods will override any defined using an earlier method.  i.e., if a variable is defined
+ * in Runtime Configuration, that will override the same variable defined in either of the earlier
+ * methods.  Configuration defined in a JS file will override any default values below.
+ *
+ * ##### Site Configuration File
+ *
+ * Configuration variables can be supplied in a file named site.config.tsx.  This file must
+ * export either an Object containing configuration variables or a function.  The function must
+ * return an Object containing configuration variables or, alternately, a promise which resolves to
+ * an Object.
+ *
+ * Using a function or async function allows the configuration to be resolved at runtime (because
+ * the function will be executed at runtime).  This is not common, and the capability is included
+ * for the sake of flexibility.
+ *
+ * The Site Configuration File is well-suited to extensibility use cases or component overrides,
+ * in that the configuration file can depend on any installed JavaScript module.  It is also the
+ * preferred way of doing build-time configuration if runtime configuration isn't used by your
+ * deployment of the platform.
+ *
+ * Exporting a config object:
+ * ```
+ * const siteConfig = {
+ *   lmsBaseUrl: 'http://localhost:18000'
+ * };
+ *
+ * export default siteConfig;
+ * ```
+ *
+ * Exporting a function that returns an object:
+ * ```
+ * function getSiteConfig() {
+ *   return {
+ *     lmsBaseUrl: 'http://localhost:18000'
+ *   };
+ * }
+ * ```
+ *
+ * Exporting a function that returns a promise that resolves to an object:
+ * ```
+ * function getAsyncSiteConfig() {
+ *   return new Promise((resolve, reject) => {
+ *     resolve({
+ *       lmsBaseUrl: 'http://localhost:18000'
+ *     });
+ *   });
+ * }
+ *
+ * export default getAsyncSiteConfig;
+ * ```
+ *
+ * ##### Initialization Config Handler
+ *
+ * The configuration document can be extended by
+ * applications at run-time using a `config` initialization handler.  Please see the Initialization
+ * documentation for more information on handlers and initialization phases.
+ *
+ * ```
+ * initialize({
+ *   handlers: {
+ *     config: () => {
+ *       mergeSiteConfig({
+ *         CUSTOM_VARIABLE: 'custom value',
+ *         lmsBaseUrl: 'http://localhost:18001' // You can override variables, but this is uncommon.
+  *       }, 'App config override handler');
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * ##### Runtime Configuration
+ *
+ * Configuration variables can also be supplied using the "runtime configuration" method, taking
+ * advantage of the Micro-frontend Config API in edx-platform. More information on this API can be
+ * found in the ADR which introduced it:
+ *
+ * https://github.com/openedx/edx-platform/blob/master/lms/djangoapps/mfe_config_api/docs/decisions/0001-mfe-config-api.rst
+ *
+ * The runtime configuration method can be enabled by supplying a mfeConfigApiUrl via one of the other
+ * two configuration methods above.
+ *
+ * Runtime configuration is particularly useful if you need to supply different configurations to
+ * a single deployment of a micro-frontend, for instance.  It is also a perfectly valid alternative
+ * to build-time configuration, though it introduces an additional API call to edx-platform on MFE
+ * initialization.
+ *
+ *
+ * @module Config
+ */
+
+import merge from 'lodash.merge';
+import {
+  AppConfig,
+  EnvironmentTypes,
+  SiteConfig
+} from '../../types';
+import { ACTIVE_ROLES_CHANGED, CONFIG_CHANGED } from '../constants';
+import { publish } from '../subscriptions';
+
+let siteConfig: SiteConfig = {
+  // Required
+  siteId: '',
+  baseUrl: '',
+  siteName: '',
+  loginUrl: '',
+  logoutUrl: '',
+  lmsBaseUrl: '',
+
+  // Optional
+  environment: EnvironmentTypes.PRODUCTION,
+  apps: [],
+  externalRoutes: [],
+  externalLinkUrlOverrides: [],
+  mfeConfigApiUrl: null,
+  accessTokenCookieName: 'edx-jwt-cookie-header-payload',
+  csrfTokenApiPath: '/csrf/api/v1/token',
+  ignoredErrorRegex: null,
+  languagePreferenceCookieName: 'openedx-language-preference',
+  refreshAccessTokenApiPath: '/login_refresh',
+  userInfoCookieName: 'edx-user-info',
+  segmentKey: null,
+};
+
+/**
+ * Getter for the application configuration document.  This is synchronous and merely returns a
+ * reference to an existing object, and is thus safe to call as often as desired.
+ *
+ * Example:
+ *
+ * ```
+ * import { getSiteConfig } from '@openedx/frontend-base';
+ *
+ * const {
+ *   lmsBaseUrl,
+ * } = getSiteConfig();
+ * ```
+ *
+ * @returns {SiteConfig}
+  */
+export function getSiteConfig() {
+  return siteConfig;
+}
+
+/**
+ * Replaces the existing SiteConfig.  This is not commonly used, but can be helpful for tests.
+ *
+ * Example:
+ *
+ * ```
+ * import { setSiteConfig } from '@openedx/frontend-base';
+ *
+ * setSiteConfig({
+ *   lmsBaseUrl, // This is overriding the ENTIRE document - this is not merged in!
+ * });
+ * ```
+ *
+ * @param newConfig A replacement SiteConfig which will completely override the current SiteConfig.
+ */
+export function setSiteConfig(newSiteConfig: SiteConfig) {
+  siteConfig = newSiteConfig;
+  publish(CONFIG_CHANGED);
+}
+
+/**
+ * Merges additional configuration values into the site config returned by `getSiteConfig`.  Will
+ * override any values that exist with the same keys.
+ *
+ * ```
+ * mergeSiteConfig({
+ *   NEW_KEY: 'new value',
+ *   OTHER_NEW_KEY: 'other new value',
+ * });
+ *
+ * This function uses lodash.merge internally to merge configuration objects
+ * which means they will be merged recursively.  See https://lodash.com/docs/latest#merge for
+ * documentation on the exact behavior.
+ *
+ * @param {Object} newSiteConfig
+ */
+export function mergeSiteConfig(newSiteConfig: Partial<SiteConfig>) {
+  siteConfig = merge(siteConfig, newSiteConfig);
+  publish(CONFIG_CHANGED);
+}
+
+const appConfigs: Record<string, AppConfig> = {};
+
+/**
+ * addAppConfigs finds any AppConfig objects in the apps in SiteConfig and makes their config
+ * available to be used by Apps via getAppConfig(appId) or useAppConfig() functions.  This is
+ * used at initialization time to process any AppConfigs bundled with the site.
+ */
+export function addAppConfigs() {
+  const { apps } = getSiteConfig();
+  if (!apps) return;
+
+  for (const app of apps) {
+    const { appId, config } = app;
+    if (config !== undefined) {
+      appConfigs[appId] = config;
+    }
+  }
+
+  publish(CONFIG_CHANGED);
+}
+
+export function getAppConfig(id: string) {
+  return appConfigs[id];
+}
+
+export function mergeAppConfig(id: string, newAppConfig: AppConfig) {
+  appConfigs[id] = merge(appConfigs[id], newAppConfig);
+  publish(CONFIG_CHANGED);
+}
+
+let activeRouteRoles: string[] = [];
+
+export function setActiveRouteRoles(roles: string[]) {
+  activeRouteRoles = roles;
+  publish(ACTIVE_ROLES_CHANGED);
+}
+
+export function getActiveRouteRoles() {
+  return activeRouteRoles;
+}
+
+const activeWidgetRoles: Record<string, number> = {};
+
+export function addActiveWidgetRole(role: string) {
+  if (activeWidgetRoles[role] === undefined) {
+    activeWidgetRoles[role] = 0;
+  }
+  activeWidgetRoles[role] += 1;
+  publish(ACTIVE_ROLES_CHANGED);
+}
+
+export function removeActiveWidgetRole(role: string) {
+  if (activeWidgetRoles[role] !== undefined) {
+    activeWidgetRoles[role] -= 1;
+  }
+  if (activeWidgetRoles[role] < 1) {
+    delete activeWidgetRoles[role];
+  }
+  publish(ACTIVE_ROLES_CHANGED);
+}
+
+export function getActiveWidgetRoles() {
+  return Object.entries(activeWidgetRoles)
+    .filter(([, count]: [role: string, count: number]) => count !== undefined && count > 0)
+    .map(([role]: [role: string, count: number]) => role);
+}
+
+// Gets all active roles from the route roles and widget roles.
+export function getActiveRoles() {
+  return [...getActiveRouteRoles(), ...getActiveWidgetRoles()];
+}
+
+/**
+ * Get an external link URL based on the URL provided. If the passed in URL is overridden in the
+ * `externalLinkUrlOverrides` object, it will return the overridden URL. Otherwise, it will return
+ * the provided URL.
+ *
+ *
+ * @param {string} url - The default URL.
+ * @returns {string} - The external link URL. Defaults to the input URL if not found in the
+ * `externalLinkUrlOverrides` object. If the input URL is invalid, '#' is returned.
+ *
+ * @example
+ * import { getExternalLinkUrl } from '@openedx/frontend-base';
+ *
+ * <Hyperlink
+ *   destination={getExternalLinkUrl(data.helpLink)}
+ *   target="_blank"
+ * >
+ */
+export function getExternalLinkUrl(url: string): string {
+  // Guard against whitespace-only strings
+  if (typeof url !== 'string' || !url.trim()) {
+    return '#';
+  }
+
+  const overriddenLinkUrls = getSiteConfig().externalLinkUrlOverrides ?? {};
+  return overriddenLinkUrls[url] ?? url;
+}