jimpex 7.0.1 → 8.0.0

package/src/services/http/responsesBuilder.ts

@@ -0,0 +1,265 @@
+import type { Config, Response } from '../../types';
+import { provider, type Statuses } from '../../utils';
+/**
+ * The options to construct a {@link ResponsesBuilder}.
+ *
+ * @group Services/ResponsesBuilder
+ */
+export type ResponsesBuilderConstructorOptions = {
+  /**
+   * A dictionary with the dependencies to inject.
+   */
+  inject: {
+    config: Config;
+    statuses: Statuses;
+  };
+};
+/**
+ * The options to build a response for a post message.
+ *
+ * @group Services/ResponsesBuilder
+ */
+export type HTMLPostMessageResponseOptions = {
+  /**
+   * The response object generated by the application.
+   */
+  res: Response;
+  /**
+   * The title for the HTML.
+   */
+  title: string;
+  /**
+   * The contents of the post message.
+   */
+  message: string;
+  /**
+   * The status code for the response.
+   *
+   * @default 200
+   */
+  status?: number | string;
+  /**
+   * From which object will the `postMessage` method called from.
+   *
+   * @default 'window.opener'
+   */
+  target?: string;
+  /**
+   * Whether or not to call `window.close` after sending the message.
+   *
+   * @default true
+   */
+  close?: boolean;
+  /**
+   * In case `close` is set to `true`, this option is to specify how many milliseconds
+   * should be waited before closing the window.
+   *
+   * @default 700
+   */
+  closeDelay?: number;
+};
+/**
+ * The options to build a reponse for JSON.
+ *
+ * @group Services/ResponsesBuilder
+ */
+export type JSONResponseOptions = {
+  /**
+   * The response object generated by the application.
+   */
+  res: Response;
+  /**
+   * The actual data for the response. It will be added in a `data` property.
+   */
+  data: unknown;
+  /**
+   * The status code for the response.
+   *
+   * @default 200
+   */
+  status?: number | string;
+  /**
+   * Extra information to include inside the `metadata` object.
+   */
+  metadata?: object;
+};
+/**
+ * The default time to wait before closing a window, in case it's enabled.
+ */
+const DEFAULT_CLOSE_DELAY_FOR_POST_MESSAGE = 700;
+/**
+ * A utility service to build responses.
+ *
+ * @group Services
+ * @group Services/ResponsesBuilder
+ */
+export class ResponsesBuilder {
+  /**
+   * The application configuration, to get the `version` and the `postMessagesPrefix`.
+   */
+  protected readonly _config: Config;
+  /**
+   * The uility service to get HTTP status codes.
+   */
+  protected readonly _statuses: Statuses;
+  /**
+   * @param options  The options to construct the service.
+   */
+  constructor({ inject: { config, statuses } }: ResponsesBuilderConstructorOptions) {
+    this._config = config;
+    this._statuses = statuses;
+  }
+  /**
+   * Generates and send an HTML response that emits a post message.
+   * The post message will be prefixed with the value of the configuration setting
+   * `postMessagesPrefix`.
+   *
+   * @param options  The options to customize how the HTML is generated.
+   */
+  htmlPostMessage(options: HTMLPostMessageResponseOptions): void {
+    const {
+      res,
+      title,
+      message,
+      status,
+      target = 'window.opener',
+      close = true,
+      closeDelay = DEFAULT_CLOSE_DELAY_FOR_POST_MESSAGE,
+    } = options;
+    const prefix = this._config.get<string | undefined>('postMessagesPrefix') ?? '';
+    const closeCode = close
+      ? `setTimeout(function() { window.close(); }, ${closeDelay});`
+      : '';
+
+    const html = this._htmlTemplate(
+      title,
+      `
+      (function() {
+        if (${target}) {
+          ${target}.postMessage('${prefix}${message}', '*');
+          ${closeCode}
+        }
+      })();
+      `,
+    );
+
+    const useStatus =
+      typeof status === 'undefined'
+        ? (this._statuses('ok') as number)
+        : this._normalizeStatus(status);
+
+    res.setHeader('Content-Type', 'text/html');
+    res.setHeader('Cache-Control', 'no-cache, max-age=0, must-revalidate, no-store');
+    res.status(useStatus);
+    res.write(html);
+    res.end();
+  }
+  /**
+   * Generates and sends a JSON response.
+   *
+   * @param options  The options to customize how the JSON is generated.
+   * @example
+   *
+   * <caption>The generated looks like this.</caption>
+   *
+   * {
+   *   metadata: {
+   *     version: 'dev',
+   *     status: 200,
+   *   },
+   *   data: { foo: 'bar' },
+   * }
+   *
+   */
+  json(options: JSONResponseOptions): void {
+    const { res, data, status, metadata = {} } = options;
+    const useStatus =
+      typeof status === 'undefined'
+        ? (this._statuses('ok') as number)
+        : this._normalizeStatus(status);
+
+    res.status(useStatus);
+    res.json({
+      metadata: {
+        version: this._config.get<string>('version'),
+        status: useStatus,
+        ...metadata,
+      },
+      data,
+    });
+    res.end();
+  }
+  /**
+   * Generates a basic HTML template for the service to use when generating a post message
+   * response.
+   *
+   * @param title  The HTML `<title />` attribute.
+   * @param code   Javascript code to be wrapped on a `<script />` tag.
+   */
+  protected _htmlTemplate(title: string, code: string): string {
+    return `
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <meta charset="utf-8" />
+          <meta http-equiv="x-ua-compatible" content="ie=edge" />
+          <meta name="viewport" content="width=device-width, initial-scale=1" />
+          <title>${title}</title>
+        </head>
+        <body>
+          <script type="text/javascript">
+          ${code}
+        </script>
+      </body>
+    </html>
+    `;
+  }
+  /**
+   * Utility method used to make sure a recevied status is a valid status code. If the
+   * status is a string, the method will try to find the code from the `statuses` package.
+   *
+   * @param status  The status to normalize.
+   * @returns If `status` is a string, but there's no valid code, it will return 200.
+   */
+  protected _normalizeStatus(status: number | string): number {
+    let useStatus: number;
+    try {
+      if (typeof status === 'string') {
+        useStatus = this._statuses(status) as number;
+      } else {
+        this._statuses(status);
+        useStatus = status;
+      }
+    } catch (_) {
+      useStatus = this._statuses('ok') as number;
+    }
+
+    return useStatus;
+  }
+}
+/**
+ * The service provider that once registered on the container will set an instance of
+ * {@link ResponsesBuilder} as the `responsesBuilder` service.
+ *
+ * @example
+ *
+ *   // Register it on the container
+ *   container.register(responsesBuilderProvider);
+ *   // Getting access to the service instance
+ *   const responsesBuilder = container.get<ResponsesBuilder>('responsesBuilder');
+ *
+ * @group Providers
+ * @group Services/ResponsesBuilder
+ */
+export const responsesBuilderProvider = provider((app) => {
+  app.set(
+    'responsesBuilder',
+    () =>
+      new ResponsesBuilder({
+        inject: {
+          config: app.getConfig(),
+          statuses: app.get('statuses'),
+        },
+      }),
+  );
+});

package/src/services/index.ts

@@ -0,0 +1,5 @@
+export * from './common';
+export * from './frontend';
+export * from './html';
+export * from './http';
+export * from './utils';

package/src/services/utils/ensureBearerToken.ts

@@ -0,0 +1,202 @@
+import { deepAssignWithOverwrite } from '@homer0/deep-assign';
+import { providerCreator, type Statuses } from '../../utils';
+import type { HTTPErrorClass } from '../common';
+import type { DeepPartial, ExpressMiddleware } from '../../types';
+/**
+ * The options for the error the middleare can generate.
+ *
+ * @group Services/EnsureBearerToken
+ */
+export type EnsureBearerTokenErrorOptions = {
+  /**
+   * The error message for the response.
+   *
+   * @default 'Unauthorized'
+   */
+  message: string;
+  /**
+   * The HTTP status that will be added to the error context.
+   *
+   * @default 401
+   */
+  status: number;
+  /**
+   * Context information for the error handler and that can be added to the actual
+   * response.
+   */
+  response: unknown;
+};
+/**
+ * The options to customize the service/middleware.
+ *
+ * @group Services/EnsureBearerToken
+ */
+export type EnsureBearerTokenOptions = {
+  error: EnsureBearerTokenErrorOptions;
+  expression: RegExp;
+  local: string;
+};
+/**
+ * The options to construct a {@link EnsureBearerToken}.
+ *
+ * @group Services/EnsureBearerToken
+ */
+export type EnsureBearerConstructorOptions = DeepPartial<EnsureBearerTokenOptions> & {
+  /**
+   * A dictionary with the dependencies to inject.
+   */
+  inject: {
+    HTTPError: HTTPErrorClass;
+    statuses: Statuses;
+  };
+};
+/**
+ * Custom options for the provider that will register an instance of
+ * {@link EnsureBearerToken}
+ * as a service.
+ *
+ * @group Services/EnsureBearerToken
+ */
+export type EnsureBearerTokenProviderOptions = DeepPartial<EnsureBearerTokenOptions> & {
+  /**
+   * The name that will be used to register the service on the container. This is to allow
+   * multiple "instances" of the service to be created.
+   *
+   * @default 'ensureBearerToken'
+   */
+  serviceName?: string;
+};
+/**
+ * This service gives you a middleware that verifies if a request has an `Authorization`
+ * header with a bearer token; if it does, the token will be saved on the `res.locals`,
+ * otherwise, it will generate an error.
+ *
+ * This is a "service middleware" to allow certain flexibility: you can have controllers
+ * where some routes are protected and others are not. For those cases, you get the
+ * service from the container, and include it only in the routes that need it.
+ *
+ * @group Services
+ * @group Services/EnsureBearerToken
+ */
+export class EnsureBearerToken {
+  /**
+   * To generate the errors when the validation fails.
+   */
+  protected readonly _HTTPError: HTTPErrorClass;
+  /**
+   * The customization options for the service.
+   */
+  protected readonly _options: EnsureBearerTokenOptions;
+  /**
+   * @param options  The options to construct the class.
+   */
+  constructor({
+    inject: { HTTPError, statuses },
+    ...options
+  }: EnsureBearerConstructorOptions) {
+    this._HTTPError = HTTPError;
+    this._options = deepAssignWithOverwrite(
+      {
+        error: {
+          message: 'Unauthorized',
+          status: statuses('unauthorized'),
+          response: {},
+        },
+        expression: /bearer (.*?)(?:$|\s)/i,
+        local: 'token',
+      },
+      options,
+    );
+  }
+  /**
+   * Generates the middleware that verifies if a request has an `Authorization` header
+   * with a bearer token.
+   */
+  getMiddleware(): ExpressMiddleware {
+    return (req, res, next) => {
+      let unauthorized = true;
+      const {
+        headers: { authorization },
+      } = req;
+      if (authorization) {
+        const matches = this._options.expression.exec(authorization);
+        if (matches) {
+          const [, token] = matches;
+          res.locals[this._options.local] = token;
+          unauthorized = false;
+        }
+      }
+
+      if (unauthorized) {
+        const {
+          error: { message, status, response },
+        } = this._options;
+        next(
+          new this._HTTPError(message, status, {
+            response,
+          }),
+        );
+      } else {
+        next();
+      }
+    };
+  }
+  /**
+   * The customization options.
+   */
+  get options(): Readonly<EnsureBearerTokenOptions> {
+    return deepAssignWithOverwrite({}, this._options);
+  }
+}
+/**
+ * Generates a "service middleware" that can be used on route controllers in order to
+ * validate the presence of a bearer token on the requests authorization header.
+ *
+ * The registered service is an instance of {@link EnsureBearerToken}, and it uses the key
+ * `ensureBearerToken`.
+ *
+ * Since it's a "provider creator", when registering it, you can pass custom options.
+ *
+ * @example
+ *
+ * <caption>Basic usage</caption>
+ *
+ *   // Register it on the container
+ *   container.register(ensureBearerTokenProvider);
+ *
+ *   // Let's assume we are in a controller now...
+ *   // Getting access to the middleware.
+ *   const ensureBearerToken = container.get<ExpressMiddleware>('ensureBearerToken');
+ *
+ * @example
+ *
+ * <caption>Customizing the service</caption>
+ *
+ *   // Register it on the container
+ *   container.register(
+ *     ensureBearerTokenProvider({
+ *       serviceName: 'ensureBearerTokenCustom',
+ *       error: {
+ *         message: 'Missing token!',
+ *       },
+ *     }),
+ *   );
+ *
+ * @group Providers
+ * @group Services/EnsureBearerToken
+ */
+export const ensureBearerTokenProvider = providerCreator(
+  (options: EnsureBearerTokenProviderOptions = {}) =>
+    (app) => {
+      const { serviceName = 'ensureBearerToken', ...rest } = options;
+      app.set(serviceName, () =>
+        new EnsureBearerToken({
+          inject: {
+            HTTPError: app.get('HTTPError'),
+            statuses: app.get('statuses'),
+          },
+          ...rest,
+        }).getMiddleware(),
+      );
+    },
+);

package/src/services/utils/index.ts

@@ -0,0 +1,21 @@
+import { providers } from '../../utils';
+import { ensureBearerTokenProvider } from './ensureBearerToken';
+/**
+ * Registers all the utility services on the container.
+ *
+ * - {@link EnsureBearerToken | ensureBearerToken}
+ *
+ * @example
+ *
+ *   // Register the collection on the container
+ *   container.register(utilsServicesProvider);
+ *   // Getting access to one the services instance
+ *   const ensureBearerToken = container.get<EnsureBearerToken>('ensureBearerToken');
+ *
+ * @group Providers
+ */
+export const utilsServicesProvider = providers({
+  ensureBearerTokenProvider,
+});
+
+export * from './ensureBearerToken';