@learncard/helpers 1.4.0 → 1.4.1

package/dist/images/images.helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"images.helpers.d.ts","sourceRoot":"","sources":["../../src/images/images.helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,OAAO,MAAM,mBAAmB,CAAC;AAE7C,QAAA,MAAM,SAAS;;;;CAAmC,CAAC;AAEnD,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAAM,OAAO,SAAS,GAAG,IAQnE,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,EAAE,SAAS,MAAM,KAAG,MAM5D,CAAC;AAEF,eAAO,MAAM,MAAM,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,EAAE,cAAY,KAAG,MAMrE,CAAC;AAEF,eAAO,MAAM,cAAc,GACvB,KAAK,MAAM,EACX,aAAa,MAAM,EAAE,EACrB,UAAS;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,KACnE,MAMF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAC/B,KAAK,MAAM,EACX,MAAM,MAAM,EACZ,SAAS,MAAM,EACf,UAAS;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,KACnE,MAMF,CAAC;AAEF,eAAO,MAAM,mBAAmB,UAAkB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAQlE,CAAC"}
+{"version":3,"file":"images.helpers.d.ts","sourceRoot":"","sources":["../../src/images/images.helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,OAAO,MAAM,mBAAmB,CAAC;AAE7C,QAAA,MAAM,SAAS;;;;CAAmC,CAAC;AASnD,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAAM,OAAO,SAAS,GAAG,IAkBnE,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,EAAE,SAAS,MAAM,KAAG,MAM5D,CAAC;AAEF,eAAO,MAAM,MAAM,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,EAAE,cAAY,KAAG,MAMrE,CAAC;AAEF,eAAO,MAAM,cAAc,GACvB,KAAK,MAAM,EACX,aAAa,MAAM,EAAE,EACrB,UAAS;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,KACnE,MAMF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAC/B,KAAK,MAAM,EACX,MAAM,MAAM,EACZ,SAAS,MAAM,EACf,UAAS;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,KACnE,MAMF,CAAC;AAEF,eAAO,MAAM,mBAAmB,UAAkB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAQlE,CAAC"}

package/dist/images/index.d.ts

@@ -1,2 +1,3 @@
 export * from './images.helpers';
+export * from './sanitize.helpers';
 //# sourceMappingURL=index.d.ts.map

package/dist/images/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/images/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/images/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/images/sanitize.helpers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Options for sanitizeImageUrl
+ */
+export type SanitizeImageUrlOptions = {
+    /**
+     * Allow blob: URLs (e.g., from URL.createObjectURL for local file previews).
+     * Default: false
+     */
+    allowBlobUrls?: boolean;
+    /**
+     * Allow data: URLs (e.g., data:image/png;base64,... for inline images).
+     * Only data:image/* URLs are allowed when enabled.
+     * Default: false
+     */
+    allowDataUrls?: boolean;
+};
+/**
+ * Sanitizes an image URL to prevent XSS via javascript: or other malicious URL schemes.
+ * Only allows http: and https: protocols by default.
+ * Optionally allows blob: URLs for local file preview scenarios.
+ * Optionally allows data:image/* URLs for inline base64 images.
+ *
+ * @param url - The URL to sanitize
+ * @param options - Optional configuration
+ * @returns The sanitized URL, or undefined if the URL is invalid or uses a disallowed protocol
+ */
+export declare const sanitizeImageUrl: (url: string | undefined, options?: SanitizeImageUrlOptions) => string | undefined;
+//# sourceMappingURL=sanitize.helpers.d.ts.map

package/dist/images/sanitize.helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.helpers.d.ts","sourceRoot":"","sources":["../../src/images/sanitize.helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IAClC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GACzB,KAAK,MAAM,GAAG,SAAS,EACvB,UAAS,uBAA4B,KACtC,MAAM,GAAG,SA4BX,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/helpers",
-    "version": "1.4.0",
+    "version": "1.4.1",
     "description": "Shared helpers for LearnCard packages",
     "type": "module",
     "main": "./dist/index.cjs",

package/src/images/images.helpers.ts

@@ -4,14 +4,31 @@ import * as discord from './discord.helpers';
 
 const Providers = { filestack, unsplash, discord };
 
-export const getProvider = (url?: string): keyof typeof Providers | null => {
-    if (url?.includes('cdn.filestackcontent.com')) return 'filestack';
-
-    if (url?.includes('images.unsplash.com')) return 'unsplash';
-
-    if (url?.includes('cdn.discordapp.com')) return 'discord';
+/**
+ * Checks if the hostname matches exactly or is a subdomain of the target domain.
+ */
+const isHostnameMatch = (hostname: string, target: string): boolean => {
+    return hostname === target || hostname.endsWith(`.${target}`);
+};
 
-    return null;
+export const getProvider = (url?: string): keyof typeof Providers | null => {
+    if (!url) return null;
+
+    try {
+        // Handle protocol-relative URLs (e.g., //cdn.filestackcontent.com/...)
+        // by prepending https: so URL parsing succeeds
+        const normalizedUrl = url.startsWith('//') ? `https:${url}` : url;
+        const { hostname } = new URL(normalizedUrl);
+
+        // Check exact hostname or proper subdomain to prevent bypass via attacker-controlled domains
+        if (isHostnameMatch(hostname, 'cdn.filestackcontent.com')) return 'filestack';
+        if (isHostnameMatch(hostname, 'images.unsplash.com')) return 'unsplash';
+        if (isHostnameMatch(hostname, 'cdn.discordapp.com')) return 'discord';
+
+        return null;
+    } catch {
+        return null;
+    }
 };
 
 export const changeQuality = (url: string, quality: number): string => {

package/src/images/index.ts

@@ -1 +1,2 @@
 export * from './images.helpers';
+export * from './sanitize.helpers';

package/src/images/sanitize.helpers.ts

@@ -0,0 +1,59 @@
+/**
+ * Options for sanitizeImageUrl
+ */
+export type SanitizeImageUrlOptions = {
+    /**
+     * Allow blob: URLs (e.g., from URL.createObjectURL for local file previews).
+     * Default: false
+     */
+    allowBlobUrls?: boolean;
+    /**
+     * Allow data: URLs (e.g., data:image/png;base64,... for inline images).
+     * Only data:image/* URLs are allowed when enabled.
+     * Default: false
+     */
+    allowDataUrls?: boolean;
+};
+
+/**
+ * Sanitizes an image URL to prevent XSS via javascript: or other malicious URL schemes.
+ * Only allows http: and https: protocols by default.
+ * Optionally allows blob: URLs for local file preview scenarios.
+ * Optionally allows data:image/* URLs for inline base64 images.
+ *
+ * @param url - The URL to sanitize
+ * @param options - Optional configuration
+ * @returns The sanitized URL, or undefined if the URL is invalid or uses a disallowed protocol
+ */
+export const sanitizeImageUrl = (
+    url: string | undefined,
+    options: SanitizeImageUrlOptions = {}
+): string | undefined => {
+    if (!url) return undefined;
+
+    const { allowBlobUrls = false, allowDataUrls = false } = options;
+
+    try {
+        const parsed = new URL(url);
+
+        if (parsed.protocol === 'https:' || parsed.protocol === 'http:') {
+            return parsed.href;
+        }
+
+        if (allowBlobUrls && parsed.protocol === 'blob:') {
+            return parsed.href;
+        }
+
+        if (allowDataUrls && parsed.protocol === 'data:') {
+            // Only allow image/* MIME types for security
+            if (url.startsWith('data:image/')) {
+                return url;
+            }
+            return undefined;
+        }
+
+        return undefined;
+    } catch {
+        return undefined;
+    }
+};