dce-expresskit 4.0.0-beta.10

package/src/helpers/handleError.ts

@@ -0,0 +1,66 @@
+// Import shared types
+import { ReactKitErrorCode } from 'dce-reactkit';
+import ExpressKitErrorCode from '../types/ExpressKitErrorCode';
+
+/**
+ * Handle an error and respond to the client
+ * @author Gabe Abrams
+ * @param res express response
+ * @param error error info
+ * @param opts.err the error to send to the client
+ *   or the error message
+ * @param [opts.code] an error code (only used if err.code is not
+ *   included)
+ * @param [opts.status=500] the https status code to use
+ *   defined)
+ */
+const handleError = (
+  res: any,
+  error: (
+    | {
+      message: any,
+      code?: string,
+      status?: number,
+    }
+    | Error
+    | string
+    | any
+  ),
+): undefined => {
+  // Get the error message
+  let message;
+  if (error && (error as any).message) {
+    message = (error.message || 'An unknown error occurred.');
+  } else if (typeof error === 'string') {
+    message = (
+      error.trim().length > 0
+        ? error
+        : 'An unknown error occurred.'
+    );
+  } else {
+    message = 'An unknown error occurred.';
+  }
+
+  // Get the error code
+  const code = (error.code || ReactKitErrorCode.NoCode);
+
+  // Get the status code
+  const status = (error.status || 500);
+
+  // Respond to user
+  res
+    // Set the http status code
+    .status(status)
+    // Send a JSON response
+    .json({
+      // Error message
+      message,
+      // Error code
+      code,
+      // Success = false flag so client can detect server-side errors
+      success: false,
+    });
+  return undefined;
+};
+
+export default handleError;

package/src/helpers/handleSuccess.ts

@@ -0,0 +1,18 @@
+/**
+ * Send successful API response
+ * @author Gabe Abrams
+ * @param res express response
+ * @param body the body of the response to send to the client
+ */
+const handleSuccess = (res: any, body: any): undefined => {
+  // Send a http 200 json response
+  res.json({
+    // Include the body as a parameter
+    body,
+    // Success = true flag so client can detect successful responses
+    success: true,
+  });
+  return undefined;
+};
+
+export default handleSuccess;

package/src/helpers/initCrossServerCredentialCollection.ts

@@ -0,0 +1,19 @@
+// Import dce-mango
+import { Collection as MangoCollection } from 'dce-mango';
+
+/**
+ * Initialize a cross-server credential collection given the dce-mango Collection class
+ * @author Gabe Abrams
+ * @param Collection the Collection class from dce-mango
+ * @returns initialized logCollection
+ */
+const initCrossServerCredentialCollection = (Collection: typeof MangoCollection) => {
+  return new Collection(
+    'CrossServerCredential',
+    {
+      uniqueIndexKey: 'key',
+    },
+  );
+};
+
+export default initCrossServerCredentialCollection;

package/src/helpers/initLogCollection.ts

@@ -0,0 +1,31 @@
+// Import dce-mango
+import { Collection as MangoCollection } from 'dce-mango';
+
+
+/**
+ * Initialize a log collection given the dce-mango Collection class
+ * @author Gabe Abrams
+ * @param Collection the Collection class from dce-mango
+ * @returns initialized logCollection
+ */
+const initLogCollection = (Collection: typeof MangoCollection) => {
+  return new Collection(
+    'Log',
+    {
+      uniqueIndexKey: 'id',
+      indexKeys: [
+        'courseId',
+        'context',
+        'subcontext',
+        'tags',
+        'year',
+        'month',
+        'day',
+        'hour',
+        'type',
+      ],
+    },
+  );
+};
+
+export default initLogCollection;

package/src/helpers/initServer.ts

@@ -0,0 +1,284 @@
+// Import express
+import express from 'express';
+
+// Import dce-mango
+import { Collection } from 'dce-mango';
+
+// Import dce-reactkit
+import {
+  ErrorWithCode,
+  ParamType,
+  LogFunction,
+  LOG_REVIEW_ROUTE_PATH_PREFIX,
+  LOG_ROUTE_PATH,
+  LOG_REVIEW_STATUS_ROUTE,
+  Log,
+} from 'dce-reactkit';
+
+// Import shared helpers
+import genRouteHandler from './genRouteHandler';
+
+// Import shared types
+import ExpressKitErrorCode from '../types/ExpressKitErrorCode';
+import CrossServerCredential from '../types/CrossServerCredential';
+
+// Stored copy of dce-mango log collection
+let _logCollection: Collection<Log>;
+
+// Stored copy of dce-mango cross-server credential collection
+let _crossServerCredentialCollection: Collection<CrossServerCredential>;
+
+/*------------------------------------------------------------------------*/
+/*                                 Helpers                                */
+/*------------------------------------------------------------------------*/
+
+/**
+ * Get log collection
+ * @author Gabe Abrams
+ * @returns log collection if one was included during launch or null if we don't
+ *   have a log collection (yet)
+ */
+export const internalGetLogCollection = () => {
+  return _logCollection ?? null;
+};
+
+/**
+ * Get cross-server credential collection
+ * @author Gabe Abrams
+ * @return cross-server credential collection if one was included during launch or null
+ *   if we don't have a cross-server credential collection (yet)
+ */
+export const internalGetCrossServerCredentialCollection = () => {
+  return _crossServerCredentialCollection ?? null;
+};
+
+/*------------------------------------------------------------------------*/
+/*                                  Main                                  */
+/*------------------------------------------------------------------------*/
+
+/**
+ * Prepare dce-reactkit to run on the server
+ * @author Gabe Abrams
+ * @param opts object containing all arguments
+ * @param opts.app express app from inside of the postprocessor function that
+ *   we will add routes to
+ * @param opts.getLaunchInfo CACCL LTI's get launch info function
+ * @param [opts.logCollection] mongo collection from dce-mango to use for
+ *   storing logs. If none is included, logs are written to the console
+ * @param [opts.logReviewAdmins=all] info on which admins can review
+ *   logs from the client. If not included, all Canvas admins are allowed to
+ *   review logs. If null, no Canvas admins are allowed to review logs.
+ *   If an array of Canvas userIds (numbers), only Canvas admins with those
+ *   userIds are allowed to review logs. If a dce-mango collection, only
+ *   Canvas admins with entries in that collection ({ userId, ...}) are allowed
+ *   to review logs
+ * @param [opts.crossServerCredentialCollection] mongo collection from dce-mango to use for
+ *   storing cross-server credentials. If none is included, cross-server credentials
+ *   are not supported
+ */
+const initServer = (
+  opts: {
+    app: express.Application,
+    logReviewAdmins?: (number[] | Collection<any>),
+    logCollection?: Collection<Log>,
+    crossServerCredentialCollection?: Collection<CrossServerCredential>,
+  },
+) => {
+  _logCollection = opts.logCollection;
+  _crossServerCredentialCollection = opts.crossServerCredentialCollection;
+
+  /*----------------------------------------*/
+  /*                Logging                 */
+  /*----------------------------------------*/
+
+  /**
+   * Log an event
+   * @author Gabe Abrams
+   * @param {string} context Context of the event (each app determines how to
+   *   organize its contexts)
+   * @param {string} subcontext Subcontext of the event (each app determines
+   *   how to organize its subcontexts)
+   * @param {string} tags stringified list of tags that apply to this action
+   *   (each app determines tag usage)
+   * @param {string} metadata stringified object containing optional custom metadata
+   * @param {string} level log level
+   * @param {string} [errorMessage] error message if type is an error
+   * @param {string} [errorCode] error code if type is an error
+   * @param {string} [errorStack] error stack if type is an error
+   * @param {string} [target] Target of the action (each app determines the list
+   *   of targets) These are usually buttons, panels, elements, etc.
+   * @param {LogAction} [action] the type of action performed on the target
+   * @returns {Log}
+   */
+  opts.app.post(
+    LOG_ROUTE_PATH,
+    genRouteHandler({
+      paramTypes: {
+        context: ParamType.String,
+        subcontext: ParamType.String,
+        tags: ParamType.JSON,
+        level: ParamType.String,
+        metadata: ParamType.JSON,
+        errorMessage: ParamType.StringOptional,
+        errorCode: ParamType.StringOptional,
+        errorStack: ParamType.StringOptional,
+        target: ParamType.StringOptional,
+        action: ParamType.StringOptional,
+      },
+      handler: ({ params, logServerEvent }) => {
+        // Create log info
+        const logInfo: Parameters<LogFunction>[0] = (
+          (params.errorMessage || params.errorCode || params.errorStack)
+            // Error
+            ? {
+              context: params.context,
+              subcontext: params.subcontext,
+              tags: params.tags,
+              level: params.level,
+              metadata: params.metadata,
+              error: {
+                message: params.errorMessage,
+                code: params.errorCode,
+                stack: params.errorStack,
+              },
+            }
+            // Action
+            : {
+              context: params.context,
+              subcontext: params.subcontext,
+              tags: params.tags,
+              level: params.level,
+              metadata: params.metadata,
+              target: params.target,
+              action: params.action,
+            }
+        );
+
+        // Add hidden boolean to change source to "client"
+        const logInfoForcedFromClient = {
+          ...logInfo,
+          overrideAsClientEvent: true,
+        };
+
+        // Write the log
+        const log = logServerEvent(logInfoForcedFromClient);
+
+        // Return
+        return log;
+      },
+    }),
+  );
+
+  /*----------------------------------------*/
+  /*              Log Reviewer              */
+  /*----------------------------------------*/
+
+  /**
+   * Check if a given user is allowed to review logs
+   * @author Gabe Abrams
+   * @param userId the id of the user
+   * @param isAdmin if true, the user is an admin
+   * @returns true if the user can review logs
+   */
+  const canReviewLogs = async (
+    userId: number,
+    isAdmin: boolean,
+  ): Promise<boolean> => {
+    // Immediately deny access if user is not an admin
+    if (!isAdmin) {
+      return false;
+    }
+
+    // If all admins are allowed, we're done
+    if (!opts.logReviewAdmins) {
+      return true;
+    }
+
+    // Do a dynamic check
+    try {
+      // Array of userIds
+      if (Array.isArray(opts.logReviewAdmins)) {
+        return opts.logReviewAdmins.some((allowedId) => {
+          return (userId === allowedId);
+        });
+      }
+
+      // Must be a collection
+      const matches = await opts.logReviewAdmins.find({ userId });
+
+      // Make sure at least one entry matches
+      return matches.length > 0;
+    } catch (err) {
+      // If an error occurred, simply return false
+      return false;
+    }
+  };
+
+  /**
+   * Check if the current user has access to logs
+   * @author Gabe Abrams
+   * @returns {boolean} true if user has access
+   */
+  opts.app.get(
+    LOG_REVIEW_STATUS_ROUTE,
+    genRouteHandler({
+      handler: async ({ params }) => {
+        const { userId, isAdmin } = params;
+        const canReview = await canReviewLogs(userId, isAdmin);
+        return canReview;
+      },
+    }),
+  );
+
+  /**
+   * Get all logs for a certain month
+   * @author Gabe Abrams
+   * @param {number} year the year to query (e.g. 2022)
+   * @param {number} month the month to query (e.g. 1 = January)
+   * @returns {Log[]} list of logs from the given month
+   */
+  opts.app.get(
+    `${LOG_REVIEW_ROUTE_PATH_PREFIX}/years/:year/months/:month`,
+    genRouteHandler({
+      paramTypes: {
+        year: ParamType.Int,
+        month: ParamType.Int,
+        pageNumber: ParamType.Int,
+      },
+      handler: async ({ params }) => {
+        // Get user info
+        const {
+          year,
+          month,
+          pageNumber,
+          userId,
+          isAdmin,
+        } = params;
+
+        // Validate user
+        const canReview = await canReviewLogs(userId, isAdmin);
+        if (!canReview) {
+          throw new ErrorWithCode(
+            'You cannot access this resource because you do not have the appropriate permissions.',
+            ExpressKitErrorCode.NotAllowedToReviewLogs,
+          );
+        }
+
+        // Query for logs
+        const response = await _logCollection.findPaged({
+          query: {
+            year,
+            month,
+          },
+          perPage: 1000,
+          pageNumber,
+        });
+
+        // Return response
+        return response;
+      },
+    }),
+  );
+};
+
+export default initServer;

package/src/helpers/parseUserAgent.ts

@@ -0,0 +1,108 @@
+/**
+ * Perform a rudimentary parsing of the user's browser agent string
+ * @author Gabe Abrams
+ * @param userAgent the user's browser agent
+ * @returns user info
+ */
+const parseUserAgent = (userAgent: string) => {
+  /* ------------- Browser ------------ */
+
+  let browser: { name: string, version: string } = {
+    name: 'Unknown',
+    version: 'Unknown',
+  };
+
+  // Parse user agent
+  let verOffset: number;
+  let nameOffset: number;
+  if ((verOffset = userAgent.indexOf('Opera')) !== -1) {
+    // In Opera, the true version is after 'Opera' or after 'Version'
+    browser = {
+      name: 'Opera',
+      version: userAgent.substring(verOffset + 6),
+    };
+    if ((verOffset = userAgent.indexOf('Version')) !== -1) {
+      browser.version = userAgent.substring(verOffset + 8);
+    }
+  } else if ((verOffset = userAgent.indexOf('MSIE')) !== -1) {
+    // In MSIE, the true version is after 'MSIE' in userAgent
+    browser = {
+      name: 'Internet Explorer',
+      version: userAgent.substring(verOffset + 5),
+    };
+  } else if ((verOffset = userAgent.indexOf('Chrome')) !== -1) {
+    // In Chrome, the true version is after 'Chrome'
+    browser = {
+      name: 'Chrome',
+      version: userAgent.substring(verOffset + 7),
+    };
+  } else if ((verOffset = userAgent.indexOf('Safari')) !== -1) {
+    // In Safari, the true version is after 'Safari' or after 'Version'
+    browser = {
+      name: 'Safari',
+      version: userAgent.substring(verOffset + 7),
+    };
+    if ((verOffset = userAgent.indexOf('Version')) !== -1) {
+      browser.version = userAgent.substring(verOffset + 8);
+    }
+  } else if ((verOffset = userAgent.indexOf('Firefox')) != -1) {
+    // In Firefox, the true version is after 'Firefox'
+    browser = {
+      name: 'Firefox',
+      version: userAgent.substring(verOffset + 8),
+    };
+  } else if (
+    (nameOffset = userAgent.lastIndexOf(' ') + 1)
+    < (verOffset = userAgent.lastIndexOf('/'))
+  ) {
+    browser = {
+      name: userAgent.substring(nameOffset, verOffset),
+      version: userAgent.substring(verOffset + 1),
+    };
+  }
+
+  // Postprocess version
+  // trim the fullVersion string at semicolon/space if present
+  let ix: number;
+  if ((ix = browser.version.indexOf(';')) !== -1) {
+    browser.version = browser.version.substring(0, ix);
+  }
+  if ((ix = browser.version.indexOf(' ')) !== -1) {
+    browser.version = browser.version.substring(0, ix);
+  }
+
+  /* ------------- Device ------------- */
+
+  // Detect os
+  let os = 'Unknown';
+  if (userAgent.includes('Linux')) {
+    os = 'Linux';
+  } else if (userAgent.includes('like Mac')) {
+    os = 'iOS';
+  } else if (userAgent.includes('Mac')) {
+    os = 'Mac';
+  } else if (userAgent.includes('Android')) {
+    os = 'Android';
+  } else if (userAgent.includes('Win')) {
+    os = 'Win';
+  }
+
+  // Check if mobile
+  const isMobile = !!userAgent.match(/(iPhone|iPod|iPad|Android|BlackBerry)/);
+
+  // Device
+  const device = {
+    isMobile,
+    os,
+  };
+
+  /* ------------- Finish ------------- */
+
+  // Return info
+  return {
+    browser,
+    device,
+  };
+};
+
+export default parseUserAgent;

package/src/helpers/visitEndpointOnAnotherServer/index.ts

@@ -0,0 +1,157 @@
+// Import dce-reactkit
+import {
+  ErrorWithCode,
+  ReactKitErrorCode,
+} from 'dce-reactkit';
+
+// Import data signer
+import { signRequest } from '../dataSigner';
+
+// Import shared types
+import ExpressKitErrorCode from '../../types/ExpressKitErrorCode';
+import sendServerToServerRequest from './sendServerToServerRequest';
+
+/*------------------------------------------------------------------------*/
+/* ----------------------------- Credentials ---------------------------- */
+/*------------------------------------------------------------------------*/
+
+/*
+DCEKIT_CROSS_SERVER_CREDENTIALS format:
+|host:key:secret||host:key:secret|...
+*/
+
+const credentials: {
+  host: string,
+  key: string,
+  secret: string,
+}[] = (
+  (process.env.DCEKIT_CROSS_SERVER_CREDENTIALS ?? '')
+    // Replace multiple | with a single one
+    .replace(/\|+/g, '|')
+    // Split by |
+    .split('|')
+    // Remove empty strings
+    .filter((str) => {
+      return str.trim().length > 0;
+    })
+    // Process each credential
+    .map((str) => {
+      // Split by :
+      const parts = str.split(':');
+
+      // Check for errors
+      if (parts.length !== 3) {
+        throw new ErrorWithCode(
+          'Invalid DCEKIT_CROSS_SERVER_CREDENTIALS format. Each credential must be in the format |host:key:secret|',
+          ExpressKitErrorCode.InvalidCrossServerCredentialsFormat,
+        );
+      }
+
+      // Return the credential
+      return {
+        host: parts[0].trim(),
+        key: parts[1].trim(),
+        secret: parts[2].trim(),
+      };
+    })
+);
+
+/*------------------------------------------------------------------------*/
+/* ------------------------------- Helpers ------------------------------ */
+/*------------------------------------------------------------------------*/
+
+/**
+ * Get the credential to use for the request to another server
+ * @author Gabe Abrams
+ * @param host the host of the other server
+ * @return the credential to use
+ */
+const getCrossServerCredential = (host: string) => {
+  // Find the credential
+  const credential = credentials.find((cred) => {
+    return cred.host.toLowerCase() === host.toLowerCase();
+  });
+  if (!credential) {
+    throw new ErrorWithCode(
+      'Cannot send cross-server signed request there was no credential that matched the host that the request is being sent to.',
+      ExpressKitErrorCode.CrossServerNoCredentialsToSignWith,
+    );
+  }
+
+  // Return credential
+  return credential;
+};
+
+/*------------------------------------------------------------------------*/
+/* -------------------------------- Main -------------------------------- */
+/*------------------------------------------------------------------------*/
+
+/**
+ * Visit an endpoint on another server
+ * @author Gabe Abrams
+ * @param opts object containing all arguments
+ * @param opts.method the method of the endpoint
+ * @param opts.path the path of the other server's endpoint
+ * @param opts.host the host of the other server
+ * @param [opts.params={}] query/body parameters to include
+ * @param [opts.responseType=JSON] the response type from the other server
+ */
+const visitEndpointOnAnotherServer = async (
+  opts: {
+    method: 'GET' | 'POST' | 'DELETE' | 'PUT',
+    path: string,
+    host: string,
+    params?: { [key in string]: any },
+    responseType?: 'JSON' | 'Text',
+  },
+): Promise<any> => {
+  // Get cross-server credential
+  const credential = getCrossServerCredential(opts.host);
+
+  // Sign the request, get new params
+  const augmentedParams = await signRequest({
+    method: opts.method,
+    path: opts.path,
+    params: opts.params ?? {},
+    key: credential.key,
+    secret: credential.secret,
+  });
+
+  // Send the request
+  const response = await sendServerToServerRequest({
+    path: opts.path,
+    host: opts.host,
+    method: opts.method,
+    params: augmentedParams,
+    responseType: opts.responseType,
+  });
+
+  // Check for failure
+  if (!response || !response.body) {
+    throw new ErrorWithCode(
+      'We didn\'t get a response from the other server. Please check the network between the two connection.',
+      ReactKitErrorCode.NoResponse,
+    );
+  }
+  if (!response.body.success) {
+    // Other errors
+    throw new ErrorWithCode(
+      (
+        response.body.message
+        || 'An unknown error occurred. Please contact an admin.'
+      ),
+      (
+        response.body.code
+        || ReactKitErrorCode.NoCode
+      ),
+    );
+  }
+
+  // Success! Extract the body
+  const { body } = response.body;
+
+  // Return
+  return body;
+};
+
+export default visitEndpointOnAnotherServer;