imgix-url-builder 0.0.1

package/src/node/buildSignedWidthSrcSet.ts

@@ -0,0 +1,68 @@
+import type { BuildWidthSrcSetParams } from "../buildWidthSrcSet";
+import { buildSignedURL } from "./buildSignedURL";
+
+/**
+ * Builds an `<img>` `srcset` attribute value for a given set of widths. It can
+ * also optinally apply Imgix URL API parameters to the URLs. The URLs are
+ * signed by appending a signature to their URL parameters. This locks the URLs
+ * and their parameters to the signature to prevent URL tampering.
+ *
+ * The `width` URL parameter will be applied for each `srcset` entry. If a
+ * `width` or `w` parameter is provided to the `params` parameter, it will be ignored.
+ *
+ * **Important**: This function should only be used in a trusted environment and
+ * never in a browser. The `secureURLToken` parameter is a secret and should not
+ * be exposed to the public.
+ *
+ * @example
+ *
+ * ```ts
+ * const srcset = buildSignedWidthSrcSet(
+ * 	"https://example.imgix.net/image.png",
+ * 	"example-token",
+ * 	{ widths: [400, 800, 1600] },
+ * );
+ * // => https://example.imgix.net/image.png?width=400&s=def3e221c3f4c4debda091b8e49420ea 400w,
+ * //    https://example.imgix.net/image.png?width=800&s=f12c7c39333410c10c2930b57116a943 800w,
+ * //    https://example.imgix.net/image.png?width=1600&s=3a975b5087ab7ad2ab91fe66072fd628 1600w
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const srcset = buildSignedWidthSrcSet(
+ * 	"https://example.imgix.net/image.png",
+ * 	"example-token",
+ * 	{
+ * 		widths: [400, 800, 1600],
+ * 		sat: -100,
+ * 	},
+ * );
+ * // => https://example.imgix.net/image.png?width=400&sat=-100&s=def3e221c3f4c4debda091b8e49420ea 400w,
+ * //    https://example.imgix.net/image.png?width=800&sat=-100&s=f12c7c39333410c10c2930b57116a943 800w,
+ * //    https://example.imgix.net/image.png?width=1600&sat=-100&s=3a975b5087ab7ad2ab91fe66072fd628 1600w
+ * ```
+ *
+ * @param url - Full absolute URL to the Imgix image.
+ * @param secureURLToken - The secret secure URL token for the image's Imgix source.
+ * @param params - An object of Imgix URL API parameters. The `widths` parameter
+ *   defines the resulting `srcset` widths.
+ *
+ * @returns A `srcset` attribute value for `url` with the given Imgix URL API
+ *   parameters applied.
+ */
+export const buildSignedWidthSrcSet = (
+	url: string,
+	secureURLToken: string,
+	{ widths, ...params }: BuildWidthSrcSetParams,
+): string => {
+	return widths
+		.map((width) => {
+			return `${buildSignedURL(url, secureURLToken, {
+				...params,
+				w: undefined,
+				width,
+			})} ${width}w`;
+		})
+		.join(", ");
+};

package/src/node/index.ts

@@ -0,0 +1,19 @@
+// Re-exports of the root entry.
+export { buildURL } from "../buildURL";
+
+// Node.js-specific exports
+//
+// These exports contain code that should only be run in a Node.js environment.
+// They may contain Node.js-specific code or should not be run in a
+// client-facing environment.
+
+export { SecureClient } from "./SecureClient";
+export type { SecureClientOptions } from "./SecureClient";
+
+export { buildSignedURL } from "./buildSignedURL";
+
+export { buildSignedWidthSrcSet } from "./buildSignedWidthSrcSet";
+
+export { buildSignedPixelDensitySrcSet } from "./buildSignedPixelDensitySrcSet";
+
+export { signURL } from "./signURL";

package/src/node/signURL.ts

@@ -0,0 +1,44 @@
+import { createHash } from "crypto";
+
+/**
+ * Signs an Imgix image URL by appending a signature to the URL parameters. This
+ * locks the URL and its parameters to the signature to prevent URL tampering.
+ *
+ * **Important**: This function should only be used in a trusted environment and
+ * never in a browser. The `secureURLToken` parameter is a secret and should not
+ * be exposed to the public.
+ *
+ * @example
+ *
+ * ```ts
+ * const url = signURL(
+ * 	"https://example.imgix.net/image.png?width=400",
+ * 	"example-token",
+ * );
+ * // => https://example.imgix.net/image.png?width=400&s=def3e221c3f4c4debda091b8e49420ea
+ * ```
+ *
+ * @param url - Full absolute URL to the Imgix image to sign.
+ * @param secureURLToken - The secret Imgix secure URL token used to generate
+ *   the signature.
+ *
+ * @returns `url` with a signature appended via an `s` URL parameter.
+ *
+ * @see Details on securing Imgix images: https://docs.imgix.com/setup/securing-images
+ */
+export const signURL = (url: string, secureURLToken: string): string => {
+	const instance = new URL(url);
+
+	// If an `s` param is passed explicitly, it will be overridden. It must
+	// also not be used when generating the signature.
+	instance.searchParams.delete("s");
+
+	// @see https://github.com/imgix/imgix-blueprint#securing-urls
+	const signature = createHash("md5")
+		.update(secureURLToken + instance.pathname + instance.search)
+		.digest("hex");
+
+	instance.searchParams.append("s", signature);
+
+	return instance.toString();
+};