@dytsou/github-readme-stats 1.0.1

package/src/common/Card.js

@@ -0,0 +1,294 @@
+// @ts-check
+
+import { encodeHTML, escapeCSSValue } from "./html.js";
+import { flexLayout } from "./render.js";
+
+class Card {
+  /**
+   * Creates a new card instance.
+   *
+   * @param {object} args Card arguments.
+   * @param {number=} args.width Card width.
+   * @param {number=} args.height Card height.
+   * @param {number=} args.border_radius Card border radius.
+   * @param {string=} args.customTitle Card custom title.
+   * @param {string=} args.defaultTitle Card default title.
+   * @param {string=} args.titlePrefixIcon Card title prefix icon.
+   * @param {object} [args.colors={}] Card colors arguments.
+   * @param {string=} args.colors.titleColor Card title color.
+   * @param {string=} args.colors.textColor Card text color.
+   * @param {string=} args.colors.iconColor Card icon color.
+   * @param {string|string[]=} args.colors.bgColor Card background color.
+   * @param {string=} args.colors.borderColor Card border color.
+   */
+  constructor({
+    width = 100,
+    height = 100,
+    border_radius = 4.5,
+    colors = {},
+    customTitle,
+    defaultTitle = "",
+    titlePrefixIcon,
+  }) {
+    this.width = width;
+    this.height = height;
+
+    this.hideBorder = false;
+    this.hideTitle = false;
+
+    this.border_radius = border_radius;
+
+    // returns theme based colors with proper overrides and defaults
+    this.colors = colors;
+    this.title =
+      customTitle === undefined
+        ? encodeHTML(defaultTitle)
+        : encodeHTML(customTitle);
+
+    this.css = "";
+
+    this.paddingX = 25;
+    this.paddingY = 35;
+    this.titlePrefixIcon = titlePrefixIcon;
+    this.animations = true;
+    this.a11yTitle = "";
+    this.a11yDesc = "";
+  }
+
+  /**
+   * @returns {void}
+   */
+  disableAnimations() {
+    this.animations = false;
+  }
+
+  /**
+   * @param {Object} props The props object.
+   * @param {string} props.title Accessibility title.
+   * @param {string} props.desc Accessibility description.
+   * @returns {void}
+   */
+  setAccessibilityLabel({ title, desc }) {
+    this.a11yTitle = title;
+    this.a11yDesc = desc;
+  }
+
+  /**
+   * @param {string} value The CSS to add to the card.
+   * @returns {void}
+   */
+  setCSS(value) {
+    this.css = value;
+  }
+
+  /**
+   * @param {boolean} value Whether to hide the border or not.
+   * @returns {void}
+   */
+  setHideBorder(value) {
+    this.hideBorder = value;
+  }
+
+  /**
+   * @param {boolean} value Whether to hide the title or not.
+   * @returns {void}
+   */
+  setHideTitle(value) {
+    this.hideTitle = value;
+    if (value) {
+      this.height -= 30;
+    }
+  }
+
+  /**
+   * @param {string} text The title to set.
+   * @returns {void}
+   */
+  setTitle(text) {
+    this.title = text;
+  }
+
+  /**
+   * @returns {string} The rendered card title.
+   */
+  renderTitle() {
+    const titleText = `
+      <text
+        x="0"
+        y="0"
+        class="header"
+        data-testid="header"
+      >${this.title}</text>
+    `;
+
+    const prefixIcon = `
+      <svg
+        class="icon"
+        x="0"
+        y="-13"
+        viewBox="0 0 16 16"
+        version="1.1"
+        width="16"
+        height="16"
+      >
+        ${this.titlePrefixIcon}
+      </svg>
+    `;
+    return `
+      <g
+        data-testid="card-title"
+        transform="translate(${this.paddingX}, ${this.paddingY})"
+      >
+        ${flexLayout({
+          items: [this.titlePrefixIcon ? prefixIcon : "", titleText],
+          gap: 25,
+        }).join("")}
+      </g>
+    `;
+  }
+
+  /**
+   * @returns {string} The rendered card gradient.
+   */
+  renderGradient() {
+    if (typeof this.colors.bgColor !== "object") {
+      return "";
+    }
+
+    const gradients = this.colors.bgColor.slice(1);
+    return typeof this.colors.bgColor === "object"
+      ? `
+        <defs>
+          <linearGradient
+            id="gradient"
+            gradientTransform="rotate(${this.colors.bgColor[0]})"
+            gradientUnits="userSpaceOnUse"
+          >
+            ${gradients.map((grad, index) => {
+              let offset = (index * 100) / (gradients.length - 1);
+              return `<stop offset="${offset}%" stop-color="#${grad}" />`;
+            })}
+          </linearGradient>
+        </defs>
+        `
+      : "";
+  }
+
+  /**
+   * Retrieves css animations for a card.
+   *
+   * @returns {string} Animation css.
+   */
+  getAnimations = () => {
+    return `
+      /* Animations */
+      @keyframes scaleInAnimation {
+        from {
+          transform: translate(-5px, 5px) scale(0);
+        }
+        to {
+          transform: translate(-5px, 5px) scale(1);
+        }
+      }
+      @keyframes fadeInAnimation {
+        from {
+          opacity: 0;
+        }
+        to {
+          opacity: 1;
+        }
+      }
+    `;
+  };
+
+  /**
+   * Renders the card with inner body HTML/SVG.
+   *
+   * **Security Model:**
+   * This method accepts pre-built SVG content from internal rendering functions.
+   * All user-controlled data (custom_title, descriptions, language names, etc.)
+   * MUST be sanitized using `escapeHtml()` or `escapeCSSValue()` BEFORE being
+   * included in the body content. The sanitization happens at the data entry points
+   * in the individual card rendering functions (stats.js, repo.js, gist.js, etc.),
+   * not at this aggregation point.
+   *
+   * This is a trusted internal API - the body parameter contains SVG elements
+   * that have already been constructed with proper escaping of dynamic values.
+   *
+   * @param {string} body The inner body of the card (pre-sanitized SVG content).
+   * @returns {string} The rendered card.
+   */
+  render(body) {
+    // Security: body contains pre-sanitized SVG from internal render functions.
+    // User inputs are escaped at source using escapeHtml() before reaching here.
+    // Sanitize color values to prevent XSS in SVG attributes
+    const safeTitleColor = escapeCSSValue(this.colors.titleColor || "");
+    const safeBorderColor = escapeCSSValue(this.colors.borderColor || "");
+    const safeBgColor =
+      typeof this.colors.bgColor === "object"
+        ? "url(#gradient)"
+        : escapeCSSValue(this.colors.bgColor || "");
+
+    return `
+      <svg
+        width="${this.width}"
+        height="${this.height}"
+        viewBox="0 0 ${this.width} ${this.height}"
+        fill="none"
+        xmlns="http://www.w3.org/2000/svg"
+        role="img"
+        aria-labelledby="descId"
+      >
+        <title id="titleId">${encodeHTML(this.a11yTitle)}</title>
+        <desc id="descId">${encodeHTML(this.a11yDesc)}</desc>
+        <style>
+          .header {
+            font: 600 18px 'Segoe UI', Ubuntu, Sans-Serif;
+            fill: ${safeTitleColor};
+            animation: fadeInAnimation 0.8s ease-in-out forwards;
+          }
+          @supports(-moz-appearance: auto) {
+            /* Selector detects Firefox */
+            .header { font-size: 15.5px; }
+          }
+          ${this.css}
+
+          ${process.env.NODE_ENV === "test" ? "" : this.getAnimations()}
+          ${
+            this.animations === false
+              ? `* { animation-duration: 0s !important; animation-delay: 0s !important; }`
+              : ""
+          }
+        </style>
+
+        ${this.renderGradient()}
+
+        <rect
+          data-testid="card-bg"
+          x="0.5"
+          y="0.5"
+          rx="${this.border_radius}"
+          height="99%"
+          stroke="${safeBorderColor}"
+          width="${this.width - 1}"
+          fill="${safeBgColor}"
+          stroke-opacity="${this.hideBorder ? 0 : 1}"
+        />
+
+        ${this.hideTitle ? "" : this.renderTitle()}
+
+        <g
+          data-testid="main-card-body"
+          transform="translate(0, ${
+            this.hideTitle ? this.paddingX : this.paddingY + 20
+          })"
+        >
+          ${body}
+        </g>
+      </svg>
+    `;
+  }
+}
+
+export { Card };
+export default Card;

package/src/common/I18n.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+const FALLBACK_LOCALE = "en";
+
+/**
+ * I18n translation class.
+ */
+class I18n {
+  /**
+   * Constructor.
+   *
+   * @param {Object} options Options.
+   * @param {string=} options.locale Locale.
+   * @param {any} options.translations Translations.
+   */
+  constructor({ locale, translations }) {
+    this.locale = locale || FALLBACK_LOCALE;
+    this.translations = translations;
+  }
+
+  /**
+   * Get translation.
+   *
+   * @param {string} str String to translate.
+   * @returns {string} Translated string.
+   */
+  t(str) {
+    if (!this.translations[str]) {
+      throw new Error(`${str} Translation string not found`);
+    }
+
+    if (!this.translations[str][this.locale]) {
+      throw new Error(`'${str}' translation not found for requested locale'`);
+    }
+
+    return this.translations[str][this.locale];
+  }
+}
+
+export { I18n };
+export default I18n;

package/src/common/access.js

@@ -0,0 +1,69 @@
+// @ts-check
+
+import { renderError } from "./render.js";
+import { blacklist } from "./blacklist.js";
+import { whitelist, gistWhitelist } from "./envs.js";
+
+const NOT_WHITELISTED_USERNAME_MESSAGE = "This username is not whitelisted";
+const NOT_WHITELISTED_GIST_MESSAGE = "This gist ID is not whitelisted";
+const BLACKLISTED_MESSAGE = "This username is blacklisted";
+
+/**
+ * Guards access using whitelist/blacklist.
+ *
+ * @param {Object} args The parameters object.
+ * @param {any} args.res The response object.
+ * @param {string} args.id Resource identifier (username or gist id).
+ * @param {"username"|"gist"|"wakatime"} args.type The type of identifier.
+ * @param {{ title_color?: string, text_color?: string, bg_color?: string, border_color?: string, theme?: string }} args.colors Color options for the error card.
+ * @returns {{ isPassed: boolean, result?: any }} The result object indicating success or failure.
+ */
+const guardAccess = ({ res, id, type, colors }) => {
+  if (!["username", "gist", "wakatime"].includes(type)) {
+    throw new Error(
+      'Invalid type. Expected "username", "gist", or "wakatime".',
+    );
+  }
+
+  const currentWhitelist = type === "gist" ? gistWhitelist : whitelist;
+  const notWhitelistedMsg =
+    type === "gist"
+      ? NOT_WHITELISTED_GIST_MESSAGE
+      : NOT_WHITELISTED_USERNAME_MESSAGE;
+
+  if (Array.isArray(currentWhitelist) && !currentWhitelist.includes(id)) {
+    const result = res.send(
+      renderError({
+        message: notWhitelistedMsg,
+        secondaryMessage: "Please deploy your own instance",
+        renderOptions: {
+          ...colors,
+          show_repo_link: false,
+        },
+      }),
+    );
+    return { isPassed: false, result };
+  }
+
+  if (
+    type === "username" &&
+    currentWhitelist === undefined &&
+    blacklist.includes(id)
+  ) {
+    const result = res.send(
+      renderError({
+        message: BLACKLISTED_MESSAGE,
+        secondaryMessage: "Please deploy your own instance",
+        renderOptions: {
+          ...colors,
+          show_repo_link: false,
+        },
+      }),
+    );
+    return { isPassed: false, result };
+  }
+
+  return { isPassed: true };
+};
+
+export { guardAccess };

package/src/common/api-utils.js

@@ -0,0 +1,221 @@
+// @ts-check
+
+/**
+ * @file Shared API utilities for request handling, validation, and error responses.
+ * Centralizes common patterns to reduce code duplication and improve maintainability.
+ */
+
+import { renderError } from "./render.js";
+import { validateColor, validateTheme } from "./color.js";
+import { MissingParamError, retrieveSecondaryMessage } from "./error.js";
+import { setErrorCacheHeaders } from "./cache.js";
+
+/**
+ * @typedef {Object} ColorOptions
+ * @property {string|undefined} title_color
+ * @property {string|undefined} text_color
+ * @property {string|undefined} bg_color
+ * @property {string|undefined} border_color
+ * @property {string|undefined} theme
+ */
+
+/**
+ * @typedef {Object} RawColorParams
+ * @property {string} [title_color]
+ * @property {string} [text_color]
+ * @property {string} [bg_color]
+ * @property {string} [border_color]
+ * @property {string} [theme]
+ */
+
+/**
+ * Creates validated color options from raw query parameters.
+ * All color values are validated and sanitized to prevent XSS attacks.
+ *
+ * @param {RawColorParams} params - Raw color parameters from query string.
+ * @returns {ColorOptions} Validated and sanitized color options.
+ */
+const createValidatedColorOptions = ({
+  title_color,
+  text_color,
+  bg_color,
+  border_color,
+  theme,
+}) => ({
+  title_color: validateColor(title_color),
+  text_color: validateColor(text_color),
+  bg_color: validateColor(bg_color),
+  border_color: validateColor(border_color),
+  theme: validateTheme(theme),
+});
+
+/**
+ * @typedef {Object} ErrorResponseOptions
+ * @property {any} res - Express response object.
+ * @property {Error|unknown} error - The error that occurred.
+ * @property {ColorOptions} colorOptions - Validated color options for error card styling.
+ */
+
+/**
+ * Patterns that indicate error messages containing user-controlled data.
+ * These patterns are replaced with safe generic alternatives to prevent XSS.
+ * @type {ReadonlyArray<{pattern: RegExp, replacement: string}>}
+ */
+const UNSAFE_MESSAGE_PATTERNS = [
+  {
+    pattern: /translation not found for/i,
+    replacement: "Invalid locale specified",
+  },
+  {
+    pattern: /Could not resolve to a User with the login of/i,
+    replacement: "User not found",
+  },
+];
+
+/**
+ * Sanitizes error messages to prevent XSS by filtering out messages that
+ * contain user-controlled data (like usernames or locales embedded in errors).
+ * Other error messages in this codebase are hardcoded and safe.
+ * Note: renderError also applies HTML encoding as an additional safety layer.
+ *
+ * @param {string} message - The error message to sanitize.
+ * @returns {string} A safe error message.
+ */
+const sanitizeErrorMessage = (message) => {
+  if (!message || typeof message !== "string") {
+    return "An error occurred";
+  }
+
+  // Replace messages containing user-controlled data with safe alternatives
+  for (const { pattern, replacement } of UNSAFE_MESSAGE_PATTERNS) {
+    if (pattern.test(message)) {
+      return replacement;
+    }
+  }
+
+  // Other error messages in this codebase are hardcoded strings (safe)
+  // renderError will HTML-encode the output as an additional safety layer
+  return message;
+};
+
+/**
+ * Handles API errors by setting cache headers and sending a rendered error response.
+ * Centralizes error handling logic to ensure consistent behavior across all API endpoints.
+ *
+ * @param {ErrorResponseOptions} options - Error handling options.
+ * @returns {any} The response result.
+ */
+const handleApiError = ({ res, error, colorOptions }) => {
+  setErrorCacheHeaders(res);
+
+  if (error instanceof Error) {
+    // Sanitize error message to prevent XSS from user-controlled data in exceptions
+    const safeMessage = sanitizeErrorMessage(error.message);
+    const rawSecondary = retrieveSecondaryMessage(error);
+    const safeSecondary = rawSecondary
+      ? sanitizeErrorMessage(rawSecondary)
+      : undefined;
+
+    return res.send(
+      renderError({
+        message: safeMessage,
+        secondaryMessage: safeSecondary,
+        renderOptions: {
+          ...colorOptions,
+          show_repo_link: !(error instanceof MissingParamError),
+        },
+      }),
+    );
+  }
+
+  return res.send(
+    renderError({
+      message: "An unknown error occurred",
+      renderOptions: colorOptions,
+    }),
+  );
+};
+
+/**
+ * @typedef {Object} ValidationErrorOptions
+ * @property {any} res - Express response object.
+ * @property {string} message - Primary error message.
+ * @property {string} [secondaryMessage] - Secondary error message.
+ * @property {ColorOptions} colorOptions - Validated color options for error card styling.
+ */
+
+/**
+ * Sends a validation error response with consistent styling.
+ * Used for parameter validation failures before main processing.
+ *
+ * @param {ValidationErrorOptions} options - Validation error options.
+ * @returns {any} The response result.
+ */
+const sendValidationError = ({
+  res,
+  message,
+  secondaryMessage = "",
+  colorOptions,
+}) => {
+  return res.send(
+    renderError({
+      message,
+      secondaryMessage,
+      renderOptions: colorOptions,
+    }),
+  );
+};
+
+/**
+ * Sets the standard SVG content type header.
+ *
+ * @param {any} res - Express response object.
+ */
+const setSvgContentType = (res) => {
+  res.setHeader("Content-Type", "image/svg+xml; charset=utf-8");
+};
+
+/**
+ * Sets the standard JSON content type header.
+ *
+ * @param {any} res - Express response object.
+ */
+const setJsonContentType = (res) => {
+  res.setHeader("Content-Type", "application/json");
+};
+
+/**
+ * Parses and validates a numeric parameter with bounds checking.
+ *
+ * @param {string|undefined} value - The value to parse.
+ * @param {number|undefined} defaultValue - Default value if parsing fails.
+ * @param {number} [min] - Minimum allowed value.
+ * @param {number} [max] - Maximum allowed value.
+ * @returns {number|undefined} The parsed and clamped value.
+ */
+const parseNumericParam = (value, defaultValue, min, max) => {
+  if (value === undefined || value === null) {
+    return defaultValue;
+  }
+  const parsed = parseFloat(value);
+  if (isNaN(parsed)) {
+    return defaultValue;
+  }
+  let result = parsed;
+  if (min !== undefined) {
+    result = Math.max(min, result);
+  }
+  if (max !== undefined) {
+    result = Math.min(max, result);
+  }
+  return result;
+};
+
+export {
+  createValidatedColorOptions,
+  handleApiError,
+  sendValidationError,
+  setSvgContentType,
+  setJsonContentType,
+  parseNumericParam,
+};

package/src/common/blacklist.js

@@ -0,0 +1,10 @@
+const blacklist = [
+  "renovate-bot",
+  "technote-space",
+  "sw-yx",
+  "YourUsername",
+  "[YourUsername]",
+];
+
+export { blacklist };
+export default blacklist;