@gjsify/fetch 0.3.13 → 0.3.15

package/lib/esm/utils/referrer.js

@@ -1,153 +1,205 @@
 import { URL } from "@gjsify/url";
 import { isIP } from "node:net";
+
+//#region src/utils/referrer.ts
+/**
+* @external URL
+* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/URL URL}
+*/
+/**
+* @module utils/referrer
+* @private
+*/
+/**
+* @see {@link https://w3c.github.io/webappsec-referrer-policy/#strip-url Referrer Policy §8.4. Strip url for use as a referrer}
+* @param url
+* @param originOnly
+*/
 function stripURLForUseAsAReferrer(url, originOnly = false) {
-  if (url == null || url === "no-referrer") {
-    return "no-referrer";
-  }
-  const u = new URL(url);
-  if (/^(about|blob|data):$/.test(u.protocol)) {
-    return "no-referrer";
-  }
-  u.username = "";
-  u.password = "";
-  u.hash = "";
-  if (originOnly) {
-    u.pathname = "";
-    u.search = "";
-  }
-  return u;
+	if (url == null || url === "no-referrer") {
+		return "no-referrer";
+	}
+	const u = new URL(url);
+	if (/^(about|blob|data):$/.test(u.protocol)) {
+		return "no-referrer";
+	}
+	u.username = "";
+	u.password = "";
+	u.hash = "";
+	if (originOnly) {
+		u.pathname = "";
+		u.search = "";
+	}
+	return u;
 }
-const ReferrerPolicy = /* @__PURE__ */ new Set([
-  "",
-  "no-referrer",
-  "no-referrer-when-downgrade",
-  "same-origin",
-  "origin",
-  "strict-origin",
-  "origin-when-cross-origin",
-  "strict-origin-when-cross-origin",
-  "unsafe-url"
+/**
+* @see {@link https://w3c.github.io/webappsec-referrer-policy/#enumdef-referrerpolicy enum ReferrerPolicy}
+*/
+const ReferrerPolicy = new Set([
+	"",
+	"no-referrer",
+	"no-referrer-when-downgrade",
+	"same-origin",
+	"origin",
+	"strict-origin",
+	"origin-when-cross-origin",
+	"strict-origin-when-cross-origin",
+	"unsafe-url"
 ]);
+/**
+* @see {@link https://w3c.github.io/webappsec-referrer-policy/#default-referrer-policy default referrer policy}
+*/
 const DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
+/**
+* @see {@link https://w3c.github.io/webappsec-referrer-policy/#referrer-policies Referrer Policy §3. Referrer Policies}
+* @param referrerPolicy
+* @returns referrerPolicy
+*/
 function validateReferrerPolicy(referrerPolicy) {
-  if (!ReferrerPolicy.has(referrerPolicy)) {
-    throw new TypeError(`Invalid referrerPolicy: ${referrerPolicy}`);
-  }
-  return referrerPolicy;
+	if (!ReferrerPolicy.has(referrerPolicy)) {
+		throw new TypeError(`Invalid referrerPolicy: ${referrerPolicy}`);
+	}
+	return referrerPolicy;
 }
+/**
+* @see {@link https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy Referrer Policy §3.2. Is origin potentially trustworthy?}
+* @param url
+* @returns `true`: "Potentially Trustworthy", `false`: "Not Trustworthy"
+*/
 function isOriginPotentiallyTrustworthy(url) {
-  if (/^(http|ws)s:$/.test(url.protocol)) {
-    return true;
-  }
-  const hostIp = url.host.replace(/(^\[)|(]$)/g, "");
-  const hostIPVersion = isIP(hostIp);
-  if (hostIPVersion === 4 && /^127\./.test(hostIp)) {
-    return true;
-  }
-  if (hostIPVersion === 6 && /^(((0+:){7})|(::(0+:){0,6}))0*1$/.test(hostIp)) {
-    return true;
-  }
-  if (url.host === "localhost" || url.host.endsWith(".localhost")) {
-    return false;
-  }
-  if (url.protocol === "file:") {
-    return true;
-  }
-  return false;
+	if (/^(http|ws)s:$/.test(url.protocol)) {
+		return true;
+	}
+	const hostIp = url.host.replace(/(^\[)|(]$)/g, "");
+	const hostIPVersion = isIP(hostIp);
+	if (hostIPVersion === 4 && /^127\./.test(hostIp)) {
+		return true;
+	}
+	if (hostIPVersion === 6 && /^(((0+:){7})|(::(0+:){0,6}))0*1$/.test(hostIp)) {
+		return true;
+	}
+	if (url.host === "localhost" || url.host.endsWith(".localhost")) {
+		return false;
+	}
+	if (url.protocol === "file:") {
+		return true;
+	}
+	return false;
 }
+/**
+* @see {@link https://w3c.github.io/webappsec-secure-contexts/#is-url-trustworthy Referrer Policy §3.3. Is url potentially trustworthy?}
+* @param url
+* @returns `true`: "Potentially Trustworthy", `false`: "Not Trustworthy"
+*/
 function isUrlPotentiallyTrustworthy(url) {
-  if (/^about:(blank|srcdoc)$/.test(url.toString())) {
-    return true;
-  }
-  if (typeof url === "string") {
-    url = new URL(url);
-  }
-  if (url.protocol === "data:") {
-    return true;
-  }
-  if (/^(blob|filesystem):$/.test(url.protocol)) {
-    return true;
-  }
-  return isOriginPotentiallyTrustworthy(url);
+	if (/^about:(blank|srcdoc)$/.test(url.toString())) {
+		return true;
+	}
+	if (typeof url === "string") {
+		url = new URL(url);
+	}
+	if (url.protocol === "data:") {
+		return true;
+	}
+	if (/^(blob|filesystem):$/.test(url.protocol)) {
+		return true;
+	}
+	return isOriginPotentiallyTrustworthy(url);
 }
+/**
+* Modifies the referrerURL to enforce any extra security policy considerations.
+* @see {@link https://w3c.github.io/webappsec-referrer-policy/#determine-requests-referrer Referrer Policy §8.3. Determine request's Referrer}, step 7
+* @callback module:utils/referrer~referrerURLCallback
+* @param {external:URL} referrerURL
+* @returns {external:URL} modified referrerURL
+*/
+/**
+* Modifies the referrerOrigin to enforce any extra security policy considerations.
+* @see {@link https://w3c.github.io/webappsec-referrer-policy/#determine-requests-referrer Referrer Policy §8.3. Determine request's Referrer}, step 7
+* @callback module:utils/referrer~referrerOriginCallback
+* @param {external:URL} referrerOrigin
+* @returns {external:URL} modified referrerOrigin
+*/
+/**
+* @see {@link https://w3c.github.io/webappsec-referrer-policy/#determine-requests-referrer Referrer Policy §8.3. Determine request's Referrer}
+* @param request
+* @param {object} o
+* @param {module:utils/referrer~referrerURLCallback} o.referrerURLCallback
+* @param {module:utils/referrer~referrerOriginCallback} o.referrerOriginCallback
+* @returns {external:URL} Request's referrer
+*/
 function determineRequestsReferrer(request, obj = {}) {
-  const { referrerURLCallback, referrerOriginCallback } = obj;
-  if (request.referrer === "no-referrer" || request.referrerPolicy === "") {
-    return null;
-  }
-  const policy = request.referrerPolicy;
-  if (request.referrer === "about:client") {
-    return "no-referrer";
-  }
-  const referrerSource = new URL(request.referrer);
-  let referrerURL = stripURLForUseAsAReferrer(referrerSource);
-  let referrerOrigin = stripURLForUseAsAReferrer(referrerSource, true);
-  if (referrerURL.toString().length > 4096) {
-    referrerURL = referrerOrigin;
-  }
-  if (referrerURLCallback) {
-    referrerURL = referrerURLCallback(referrerURL);
-  }
-  if (referrerOriginCallback) {
-    referrerOrigin = referrerOriginCallback(referrerOrigin);
-  }
-  const currentURL = new URL(request.url);
-  switch (policy) {
-    case "no-referrer":
-      return "no-referrer";
-    case "origin":
-      return referrerOrigin;
-    case "unsafe-url":
-      return referrerURL;
-    case "strict-origin":
-      if (isUrlPotentiallyTrustworthy(referrerURL) && !isUrlPotentiallyTrustworthy(currentURL)) {
-        return "no-referrer";
-      }
-      return referrerOrigin.toString();
-    case "strict-origin-when-cross-origin":
-      if (referrerURL.origin === currentURL.origin) {
-        return referrerURL;
-      }
-      if (isUrlPotentiallyTrustworthy(referrerURL) && !isUrlPotentiallyTrustworthy(currentURL)) {
-        return "no-referrer";
-      }
-      return referrerOrigin;
-    case "same-origin":
-      if (referrerURL.origin === currentURL.origin) {
-        return referrerURL;
-      }
-      return "no-referrer";
-    case "origin-when-cross-origin":
-      if (referrerURL.origin === currentURL.origin) {
-        return referrerURL;
-      }
-      return referrerOrigin;
-    case "no-referrer-when-downgrade":
-      if (isUrlPotentiallyTrustworthy(referrerURL) && !isUrlPotentiallyTrustworthy(currentURL)) {
-        return "no-referrer";
-      }
-      return referrerURL;
-    default:
-      throw new TypeError(`Invalid referrerPolicy: ${policy}`);
-  }
+	const { referrerURLCallback, referrerOriginCallback } = obj;
+	if (request.referrer === "no-referrer" || request.referrerPolicy === "") {
+		return null;
+	}
+	const policy = request.referrerPolicy;
+	if (request.referrer === "about:client") {
+		return "no-referrer";
+	}
+	const referrerSource = new URL(request.referrer);
+	let referrerURL = stripURLForUseAsAReferrer(referrerSource);
+	let referrerOrigin = stripURLForUseAsAReferrer(referrerSource, true);
+	if (referrerURL.toString().length > 4096) {
+		referrerURL = referrerOrigin;
+	}
+	if (referrerURLCallback) {
+		referrerURL = referrerURLCallback(referrerURL);
+	}
+	if (referrerOriginCallback) {
+		referrerOrigin = referrerOriginCallback(referrerOrigin);
+	}
+	const currentURL = new URL(request.url);
+	switch (policy) {
+		case "no-referrer": return "no-referrer";
+		case "origin": return referrerOrigin;
+		case "unsafe-url": return referrerURL;
+		case "strict-origin":
+			if (isUrlPotentiallyTrustworthy(referrerURL) && !isUrlPotentiallyTrustworthy(currentURL)) {
+				return "no-referrer";
+			}
+			return referrerOrigin.toString();
+		case "strict-origin-when-cross-origin":
+			if (referrerURL.origin === currentURL.origin) {
+				return referrerURL;
+			}
+			if (isUrlPotentiallyTrustworthy(referrerURL) && !isUrlPotentiallyTrustworthy(currentURL)) {
+				return "no-referrer";
+			}
+			return referrerOrigin;
+		case "same-origin":
+			if (referrerURL.origin === currentURL.origin) {
+				return referrerURL;
+			}
+			return "no-referrer";
+		case "origin-when-cross-origin":
+			if (referrerURL.origin === currentURL.origin) {
+				return referrerURL;
+			}
+			return referrerOrigin;
+		case "no-referrer-when-downgrade":
+			if (isUrlPotentiallyTrustworthy(referrerURL) && !isUrlPotentiallyTrustworthy(currentURL)) {
+				return "no-referrer";
+			}
+			return referrerURL;
+		default: throw new TypeError(`Invalid referrerPolicy: ${policy}`);
+	}
 }
+/**
+* @see {@link https://w3c.github.io/webappsec-referrer-policy/#parse-referrer-policy-from-header|Referrer Policy §8.1. Parse a referrer policy from a Referrer-Policy header}
+* @param {Headers} headers Response headers
+* @returns {string} policy
+*/
 function parseReferrerPolicyFromHeader(headers) {
-  const policyTokens = (headers.get("referrer-policy") || "").split(/[,\s]+/);
-  let policy = "";
-  for (const token of policyTokens) {
-    if (token && ReferrerPolicy.has(token)) {
-      policy = token;
-    }
-  }
-  return policy;
+	const policyTokens = (headers.get("referrer-policy") || "").split(/[,\s]+/);
+	let policy = "";
+	for (const token of policyTokens) {
+		if (token && ReferrerPolicy.has(token)) {
+			policy = token;
+		}
+	}
+	return policy;
 }
-export {
-  DEFAULT_REFERRER_POLICY,
-  ReferrerPolicy,
-  determineRequestsReferrer,
-  isOriginPotentiallyTrustworthy,
-  isUrlPotentiallyTrustworthy,
-  parseReferrerPolicyFromHeader,
-  stripURLForUseAsAReferrer,
-  validateReferrerPolicy
-};
+
+//#endregion
+export { DEFAULT_REFERRER_POLICY, ReferrerPolicy, determineRequestsReferrer, isOriginPotentiallyTrustworthy, isUrlPotentiallyTrustworthy, parseReferrerPolicyFromHeader, stripURLForUseAsAReferrer, validateReferrerPolicy };

package/lib/esm/utils/soup-helpers.js

@@ -1,22 +1,29 @@
-import GLib from "@girs/glib-2.0";
 import { Readable } from "node:stream";
+import GLib from "@girs/glib-2.0";
 import { inputStreamAsyncIterator } from "@gjsify/utils";
+
+//#region src/utils/soup-helpers.ts
+/**
+* Promise wrapper around `Soup.Session.send_async` / `send_finish`.
+*/
 async function soupSendAsync(session, msg, ioPriority = GLib.PRIORITY_DEFAULT, cancellable = null) {
-  return new Promise((resolve, reject) => {
-    session.send_async(msg, ioPriority, cancellable, (_self, asyncRes) => {
-      try {
-        const inputStream = session.send_finish(asyncRes);
-        resolve(inputStream);
-      } catch (error) {
-        reject(error);
-      }
-    });
-  });
+	return new Promise((resolve, reject) => {
+		session.send_async(msg, ioPriority, cancellable, (_self, asyncRes) => {
+			try {
+				const inputStream = session.send_finish(asyncRes);
+				resolve(inputStream);
+			} catch (error) {
+				reject(error);
+			}
+		});
+	});
 }
+/**
+* Converts a `Gio.InputStream` to a Node.js `Readable` stream.
+*/
 function inputStreamToReadable(inputStream, options = {}) {
-  return Readable.from(inputStreamAsyncIterator(inputStream), options);
+	return Readable.from(inputStreamAsyncIterator(inputStream), options);
 }
-export {
-  inputStreamToReadable,
-  soupSendAsync
-};
+
+//#endregion
+export { inputStreamToReadable, soupSendAsync };