rapidoc 11.0.1 → 12.1.0

package/src/utils/oauth-utils.js

@@ -0,0 +1,87 @@
+/**
+ * Helpers for the OAuth popup flow (Authorize button): unguessable values, PKCE, reading the reply the
+ * provider sends to the return page (`<oauth-receiver>`), and checking that reply before it is trusted.
+ */
+
+/** BroadcastChannel the return page also replies on: still works when the provider's page cuts `window.opener`. */
+export const OAUTH_CHANNEL = "rapidoc-oauth";
+
+function base64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * A random URL-safe string from the platform's cryptographic random generator.
+ * 32 bytes give a 43-character value, the shortest a PKCE code_verifier may be.
+ *
+ * @param {number} [bytes]
+ */
+export function randomUrlSafe(bytes = 32) {
+  return base64Url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+
+/**
+ * PKCE S256 code_challenge for a code_verifier (RFC 7636): base64url(SHA-256(verifier)).
+ *
+ * @param {string} verifier
+ * @returns {Promise<string>}
+ */
+export async function pkceChallenge(verifier) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64Url(new Uint8Array(digest));
+}
+
+/**
+ * The provider's reply as the return page sees it: authorization code flow in the query, implicit flow in the
+ * fragment. `state` is read in both, so the opener can check it.
+ *
+ * @param {{search: string, hash: string}} location
+ */
+export function readOAuthReply(location) {
+  if (location.search && location.search.length > 1) {
+    const params = new URLSearchParams(location.search);
+    return {
+      responseType: "code",
+      code: params.get("code"),
+      state: params.get("state"),
+      error: params.get("error"),
+      errorDescription: params.get("error_description"),
+    };
+  }
+  if (location.hash && location.hash.length > 1) {
+    const params = new URLSearchParams(location.hash.slice(1));
+    return {
+      responseType: "token",
+      accessToken: params.get("access_token"),
+      tokenType: params.get("token_type"),
+      state: params.get("state"),
+      error: params.get("error"),
+      errorDescription: params.get("error_description"),
+    };
+  }
+  return null;
+}
+
+/**
+ * Is this the reply to the sign-in we started? It must look like a reply, carry the `state` we sent, and, when it
+ * came as a window message, come from this site and from the popup we opened. Anything else is ignored, so a
+ * message from another frame or window can neither inject a code or token nor end the wait.
+ *
+ * @param {object} reply - message data
+ * @param {object} expected
+ * @param {string} expected.state
+ * @param {string} [expected.origin] - for window messages: this page's origin
+ * @param {string} [origin] - for window messages: MessageEvent.origin
+ * @param {*} [source] - for window messages: MessageEvent.source
+ * @param {*} [expectedSource] - the popup window
+ */
+export function isExpectedOAuthReply(reply, expected, origin, source, expectedSource) {
+  if (!reply || typeof reply !== "object") return false;
+  if (reply.responseType !== "code" && reply.responseType !== "token") return false;
+  if (!expected.state || reply.state !== expected.state) return false;
+  if (expected.origin !== undefined && origin !== expected.origin) return false;
+  if (expectedSource !== undefined && source !== expectedSource) return false;
+  return true;
+}

package/src/utils/request-utils.js

@@ -0,0 +1,264 @@
+/**
+ * Serializes a header parameter value according to OpenAPI 3 rules.
+ * Objects can be serialized exploded (key=value,key2=value2) or unexploded (key,value,key2,value2).
+ *
+ * @param {any} rawValue - Raw header parameter value
+ * @param {object} [options]
+ * @param {boolean} [options.explode=false] - Whether to explode object properties with '='
+ * @param {boolean} [options.isObject=false] - Whether value is an object
+ * @returns {string} Serialized header string
+ */
+export function serializeHeaderValue(rawValue, options = {}) {
+  const { explode = false, isObject = false } = options;
+
+  if (rawValue === undefined || rawValue === null || rawValue === "") {
+    return "";
+  }
+
+  if (isObject || (typeof rawValue === "object" && !Array.isArray(rawValue))) {
+    let obj = rawValue;
+    if (typeof rawValue === "string") {
+      try {
+        obj = JSON.parse(rawValue.replace(/\n/g, "").trim());
+      } catch {
+        return "";
+      }
+    }
+
+    if (!obj || typeof obj !== "object") {
+      return "";
+    }
+
+    const separator = explode ? "=" : ",";
+    return Object.keys(obj)
+      .map((key) => {
+        const val = obj[key];
+        const valStr = typeof val === "object" ? JSON.stringify(val) : String(val);
+        return `${key}${separator}${valStr}`;
+      })
+      .join(",");
+  }
+
+  if (Array.isArray(rawValue)) {
+    const filtered = rawValue.filter((v) => v !== "" && v !== undefined && v !== null);
+    return filtered.join(",");
+  }
+
+  return String(rawValue);
+}
+
+/**
+ * Constructs a Headers instance for an API request from structured inputs.
+ *
+ * @param {object} options
+ * @param {string} [options.accept] - Accept header
+ * @param {Array<object>} [options.apiKeys] - Applied API keys
+ * @param {Array<{ name: string, value: any, explode?: boolean, isObject?: boolean }>} [options.headerParams]
+ * @param {string} [options.contentType] - Content-Type to apply (omitted for multipart/form-data)
+ * @returns {Headers}
+ */
+export function constructFetchHeaders({
+  accept = "",
+  apiKeys = [],
+  headerParams = [],
+  contentType = "",
+} = {}) {
+  const reqHeaders = new Headers();
+
+  if (accept) {
+    reqHeaders.append("Accept", accept);
+  }
+
+  if (Array.isArray(apiKeys)) {
+    apiKeys
+      .filter((k) => k && k.in === "header" && k.finalKeyValue)
+      .forEach((k) => {
+        reqHeaders.append(k.name, k.finalKeyValue);
+      });
+  }
+
+  if (Array.isArray(headerParams)) {
+    headerParams.forEach((param) => {
+      if (
+        param &&
+        param.name &&
+        param.value !== undefined &&
+        param.value !== null &&
+        param.value !== ""
+      ) {
+        const headerValue = serializeHeaderValue(param.value, {
+          explode: param.explode === true || param.explode === "true",
+          isObject: param.isObject === true,
+        });
+        if (headerValue) {
+          reqHeaders.append(param.name, headerValue);
+        }
+      }
+    });
+  }
+
+  if (contentType && !contentType.includes("form-data")) {
+    reqHeaders.append("Content-Type", contentType);
+  }
+
+  return reqHeaders;
+}
+
+/**
+ * Builds a URLSearchParams body from field entries or a dynamic JSON template.
+ *
+ * @param {Array<{ name: string, value: any, isArray?: boolean }>} fields
+ * @param {string} [dynamicJson] - Raw JSON string for dynamic forms
+ * @returns {URLSearchParams}
+ */
+export function buildUrlEncodedBody(fields = [], dynamicJson = "") {
+  const params = new URLSearchParams();
+
+  if (dynamicJson) {
+    try {
+      const obj = JSON.parse(dynamicJson);
+      if (obj && typeof obj === "object") {
+        for (const prop of Object.keys(obj)) {
+          params.append(
+            prop,
+            typeof obj[prop] === "object" ? JSON.stringify(obj[prop]) : String(obj[prop]),
+          );
+        }
+        return params;
+      }
+    } catch {
+      // Fall through to fields
+    }
+  }
+
+  if (Array.isArray(fields)) {
+    fields.forEach((field) => {
+      if (
+        !field ||
+        !field.name ||
+        field.value === undefined ||
+        field.value === null ||
+        field.value === ""
+      ) {
+        return;
+      }
+      if (field.isArray) {
+        const arr = Array.isArray(field.value) ? field.value : [field.value];
+        const filtered = arr.filter((v) => v !== "" && v !== undefined && v !== null);
+        if (filtered.length > 0) {
+          params.append(field.name, filtered.join(","));
+        }
+      } else {
+        params.append(field.name, String(field.value));
+      }
+    });
+  }
+
+  return params;
+}
+
+const isComplexSchema = (schema) =>
+  !!schema &&
+  (schema.type === "object" ||
+    (Array.isArray(schema.type) && schema.type.includes("object")) ||
+    (!schema.type && !!schema.properties));
+
+/**
+ * Content-Type of a multipart/form-data part, following OpenAPI's "Special Considerations for multipart Content":
+ * the encoding object's contentType when the spec gives one (the first of a comma-separated list), application/json
+ * for an object or an array of objects, and "" otherwise (text/plain, or a file's own type).
+ *
+ * @param {object} schema - Schema of the form field
+ * @param {object} [encoding] - The media type's encoding entry for that field
+ * @returns {string}
+ */
+export function multipartPartContentType(schema, encoding) {
+  const declared =
+    typeof encoding?.contentType === "string" ? encoding.contentType.split(",")[0].trim() : "";
+  if (declared) {
+    return declared;
+  }
+  if (isComplexSchema(schema) || (schema?.type === "array" && isComplexSchema(schema.items))) {
+    return "application/json";
+  }
+  return "";
+}
+
+// Quotes and line breaks in part names and file names are percent-encoded, as browsers do for FormData
+const escapePartName = (name) =>
+  String(name).replace(/"/g, "%22").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+
+/**
+ * Serializes FormData into a multipart/form-data body in which parts carry a Content-Type.
+ * A browser only sends a Content-Type for a part that is a file, and a Blob part always gets filename="blob",
+ * which servers read as an upload; so parts with a type in partContentTypes are written by hand.
+ *
+ * @param {FormData} formData
+ * @param {Object<string, string>} partContentTypes - Content-Type per field name, for fields that are not files
+ * @param {string} [boundary]
+ * @returns {{ body: Blob, contentType: string }}
+ */
+export function serializeMultipartBody(
+  formData,
+  partContentTypes = {},
+  boundary = `----RapiDocFormBoundary${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`,
+) {
+  const chunks = [];
+  for (const [name, value] of formData.entries()) {
+    const isFile = typeof value !== "string";
+    let head = `--${boundary}\r\nContent-Disposition: form-data; name="${escapePartName(name)}"`;
+    if (isFile) {
+      head += `; filename="${escapePartName(value.name ?? "blob")}"\r\nContent-Type: ${value.type || partContentTypes[name] || "application/octet-stream"}`;
+    } else if (partContentTypes[name]) {
+      head += `\r\nContent-Type: ${partContentTypes[name]}`;
+    }
+    chunks.push(`${head}\r\n\r\n`, isFile ? value : value.replace(/\r?\n/g, "\r\n"), "\r\n");
+  }
+  chunks.push(`--${boundary}--\r\n`);
+  return { body: new Blob(chunks), contentType: `multipart/form-data; boundary=${boundary}` };
+}
+
+/**
+ * Builds a FormData instance from structured field entries.
+ *
+ * @param {Array<{ name: string, value: any, file?: File, isArray?: boolean }>} fields
+ * @returns {FormData}
+ */
+export function buildMultipartFormData(fields = []) {
+  const formData = new FormData();
+
+  if (!Array.isArray(fields)) {
+    return formData;
+  }
+
+  fields.forEach((field) => {
+    if (!field || !field.name) {
+      return;
+    }
+
+    if (typeof File !== "undefined" && field.file instanceof File) {
+      formData.append(field.name, field.file, field.file.name);
+      return;
+    }
+
+    if (field.value === undefined || field.value === null || field.value === "") {
+      return;
+    }
+
+    if (field.isArray) {
+      const arr = Array.isArray(field.value) ? field.value : [field.value];
+      const filtered = arr.filter((v) => v !== "" && v !== undefined && v !== null);
+      filtered.forEach((item) => {
+        if (typeof File !== "undefined" && item instanceof File) {
+          formData.append(field.name, item, item.name);
+        } else {
+          formData.append(field.name, String(item));
+        }
+      });
+    } else {
+      formData.append(field.name, String(field.value));
+    }
+  });
+
+  return formData;
+}

package/src/utils/response-utils.js

@@ -0,0 +1,203 @@
+import { formatXml } from "./xml-utils.js";
+import { schemaToAST, generateExample, standardizeExample } from "./schema-utils.js";
+
+/**
+ * Parses and processes a standard Fetch API Response into RapiDoc formatted response state.
+ * Handles JSON parsing, XML formatting, NDJSON streaming format, charset decoding,
+ * and binary MIME sniffing with RFC 5987 Content-Disposition decoding.
+ *
+ * @param {Response} fetchResponse - Standard Fetch Response object
+ * @returns {Promise<{
+ *   responseText: string,
+ *   respJson?: any,
+ *   respBlob?: Blob,
+ *   respText?: string,
+ *   responseIsBlob: boolean,
+ *   responseBlobType: string,
+ *   responseBlobUrl: string,
+ *   respContentDisposition: string
+ * }>}
+ */
+export async function processFetchResponse(fetchResponse) {
+  let respBlob;
+  let respJson;
+  let respText;
+  let responseIsBlob = false;
+  let responseBlobType = "";
+  let responseBlobUrl = "";
+  let respContentDisposition = "";
+  let responseText = "";
+
+  let contentType = fetchResponse.headers.get("content-type");
+  const respEmpty = (await fetchResponse.clone().text()).length === 0;
+  if (respEmpty) {
+    responseText = "";
+  } else if (contentType) {
+    contentType = contentType.split(";")[0].trim();
+    if (contentType === "application/x-ndjson") {
+      responseText = await fetchResponse.text();
+    } else if (contentType.includes("json")) {
+      if (/charset=[^"']+/.test(contentType)) {
+        const encoding = contentType.split("charset=")[1];
+        const buffer = await fetchResponse.arrayBuffer();
+        try {
+          respText = new TextDecoder(encoding).decode(buffer);
+        } catch {
+          respText = new TextDecoder("utf-8").decode(buffer);
+        }
+        try {
+          respJson = JSON.parse(respText);
+          responseText = JSON.stringify(respJson, null, 2);
+        } catch {
+          responseText = respText;
+        }
+      } else {
+        respJson = await fetchResponse.json();
+        responseText = JSON.stringify(respJson, null, 2);
+      }
+    } else if (
+      /^font\/|tar$|zip$|7z$|rtf$|msword$|excel$|\/pdf$|\/octet-stream$|^application\/vnd\./.test(
+        contentType,
+      )
+    ) {
+      responseIsBlob = true;
+      responseBlobType = "download";
+    } else if (contentType.startsWith("image")) {
+      responseIsBlob = true;
+      responseBlobType = "image";
+    } else if (/^audio|^image|^video/.test(contentType)) {
+      responseIsBlob = true;
+      responseBlobType = "view";
+    } else {
+      respText = await fetchResponse.text();
+      if (contentType.includes("xml")) {
+        responseText = formatXml(respText, { textNodesOnSameLine: true, indentor: "  " });
+      } else {
+        responseText = respText;
+      }
+    }
+    if (responseIsBlob) {
+      const contentDisposition = fetchResponse.headers.get("content-disposition") || "";
+      let filenameFromContentDisposition = "filename";
+      if (contentDisposition) {
+        const filenameStarRegexMatch = contentDisposition.match(/filename\*=\s*UTF-8''([^;]+)/);
+        if (filenameStarRegexMatch) {
+          filenameFromContentDisposition = decodeURIComponent(filenameStarRegexMatch[1]);
+        } else {
+          const filenameMatch = contentDisposition.match(/filename="?([^"]+)"?/);
+          if (filenameMatch) {
+            filenameFromContentDisposition = filenameMatch[1];
+          }
+        }
+      }
+      respContentDisposition = filenameFromContentDisposition;
+      respBlob = await fetchResponse.blob();
+      if (typeof URL !== "undefined" && URL.createObjectURL) {
+        responseBlobUrl = URL.createObjectURL(respBlob);
+      }
+    }
+  } else {
+    respText = await fetchResponse.text();
+    responseText = respText;
+  }
+
+  return {
+    responseText,
+    respJson,
+    respBlob,
+    respText,
+    responseIsBlob,
+    responseBlobType,
+    responseBlobUrl,
+    respContentDisposition,
+  };
+}
+
+/**
+ * Pre-computes schema ASTs, examples, and headers for all response codes and MIME types.
+ * Pure function extracted from api-response component to enable caching and unit testing.
+ *
+ * @param {object} responses - OpenAPI responses map
+ * @param {object} [options]
+ * @param {boolean|string} [options.callback=false]
+ * @param {boolean|string} [options.webhook=false]
+ * @returns {{
+ *   headersForEachRespStatus: object,
+ *   mimeResponsesForEachStatus: object,
+ *   defaultStatus: string,
+ *   defaultMimeType: string
+ * }}
+ */
+export function prepareResponseDefinitions(responses, options = {}) {
+  const { callback = false, webhook = false } = options;
+  const isCallbackOrWebhook =
+    callback === true || callback === "true" || webhook === true || webhook === "true";
+
+  const headersForEachRespStatus = {};
+  const mimeResponsesForEachStatus = {};
+  let defaultStatus = "";
+  let defaultMimeType = "";
+
+  if (!responses || typeof responses !== "object") {
+    return {
+      headersForEachRespStatus,
+      mimeResponsesForEachStatus,
+      defaultStatus,
+      defaultMimeType,
+    };
+  }
+
+  for (const statusCode of Object.keys(responses)) {
+    if (statusCode === "$$ref") {
+      continue;
+    }
+    if (!defaultStatus) {
+      defaultStatus = statusCode;
+    }
+    const allMimeResp = {};
+    const content = responses[statusCode]?.content;
+
+    if (content && typeof content === "object") {
+      for (const mimeResp of Object.keys(content)) {
+        const mimeRespObj = content[mimeResp];
+        if (!defaultMimeType) {
+          defaultMimeType = mimeResp;
+        }
+
+        const schemaTree = mimeRespObj?.schema ? schemaToAST(mimeRespObj.schema) : null;
+        const respExamples = generateExample(
+          mimeRespObj?.schema,
+          mimeResp,
+          standardizeExample(mimeRespObj?.examples),
+          standardizeExample(mimeRespObj?.example),
+          !isCallbackOrWebhook,
+          isCallbackOrWebhook,
+          mimeResp.includes("json") ? "json" : "text",
+        );
+
+        allMimeResp[mimeResp] = {
+          description: responses[statusCode].description,
+          examples: respExamples,
+          selectedExample: respExamples[0]?.exampleId || "",
+          schemaTree,
+        };
+      }
+    }
+
+    const tempHeaders = [];
+    if (responses[statusCode]?.headers) {
+      for (const key of Object.keys(responses[statusCode].headers)) {
+        tempHeaders.push({ name: key, ...responses[statusCode].headers[key] });
+      }
+    }
+    headersForEachRespStatus[statusCode] = tempHeaders;
+    mimeResponsesForEachStatus[statusCode] = allMimeResp;
+  }
+
+  return {
+    headersForEachRespStatus,
+    mimeResponsesForEachStatus,
+    defaultStatus,
+    defaultMimeType,
+  };
+}

package/src/utils/sanitize.js

@@ -0,0 +1,57 @@
+// One instance for every call: constructing it per description is measurable on large schemas
+let nativeSanitizer;
+
+export function sanitizeHTML(htmlString) {
+  if (typeof htmlString !== "string") {
+    return "";
+  }
+
+  // Use native Sanitizer API if supported
+  if (typeof window !== "undefined" && window.Sanitizer && Element.prototype.setHTML) {
+    try {
+      const el = document.createElement("div");
+      nativeSanitizer ??= new window.Sanitizer({ allowAttributes: { "*": ["*"] } });
+      el.setHTML(htmlString, { sanitizer: nativeSanitizer });
+      return el.innerHTML;
+    } catch {
+      // If Sanitizer with options throws, fall through to fallback shim
+    }
+  }
+
+  // Minimal shim for unsupported browsers to prevent basic XSS
+  let doc;
+  if (typeof DOMParser !== "undefined") {
+    doc = new DOMParser().parseFromString(htmlString, "text/html");
+  } else {
+    // Fallback for SSR/Node if needed, though this is primarily browser-side
+    return htmlString;
+  }
+
+  // Remove script tags
+  const scripts = doc.querySelectorAll("script");
+  for (let i = scripts.length - 1; i >= 0; i--) {
+    scripts[i].parentNode.removeChild(scripts[i]);
+  }
+
+  // Remove on* attributes and javascript: URIs
+  const allElements = doc.querySelectorAll("*");
+  for (let i = 0; i < allElements.length; i++) {
+    const el = allElements[i];
+    for (let j = el.attributes.length - 1; j >= 0; j--) {
+      const attr = el.attributes[j];
+      const attrName = attr.name.toLowerCase();
+      const attrValue = attr.value.toLowerCase();
+
+      if (attrName.startsWith("on")) {
+        el.removeAttribute(attr.name);
+      } else if (
+        (attrName === "href" || attrName === "src") &&
+        (attrValue.includes("javascript:") || attrValue.includes("data:text/html"))
+      ) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+
+  return doc.body.innerHTML;
+}