@learncard/helpers 1.3.13 → 1.4.1

package/src/credential-format.ts

@@ -5,6 +5,7 @@ import type {
     StoredCredential,
     StoredCredentialEnvelope,
     VC,
+    VP,
 } from '@learncard/types';
 import { isStoredCredentialEnvelope } from '@learncard/types';
 
@@ -485,8 +486,8 @@ const projectJwtVcCompactToVc = (compact: string): VC | undefined => {
  * `read.get` result without branching themselves).
  */
 export const resolveStorageReadResult = (
-    value: VC | StoredCredentialEnvelope | undefined
-): VC | StoredCredentialEnvelope | undefined => {
+    value: VC | VP | StoredCredentialEnvelope | undefined
+): VC | VP | StoredCredentialEnvelope | undefined => {
     if (!value) return value;
     if (!isStoredCredentialEnvelope(value)) return value;
     const projected = projectEnvelopeToDisplayVc(value);
@@ -499,8 +500,8 @@ const inferW3cVersionFromContext = (vc: unknown): 'w3c-vc-2.0' | 'w3c-vc-1.1' =>
     const contexts = Array.isArray(contextRaw)
         ? contextRaw
         : contextRaw !== undefined
-        ? [contextRaw]
-        : [];
+          ? [contextRaw]
+          : [];
     const isV2 = contexts.some(
         c => typeof c === 'string' && c.includes('w3.org/ns/credentials/v2')
     );

package/src/environment.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+
+export type EnvironmentSource = {
+    project: string;
+    source: string;
+    examplePath: string;
+};
+
+export class EnvironmentConfigurationError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'EnvironmentConfigurationError';
+    }
+}
+
+export const requiredEnvironmentString = z.string().trim().min(1, 'Required but missing');
+
+export const optionalEnvironmentString = z.preprocess(
+    value => (value === '' ? undefined : value),
+    requiredEnvironmentString.optional()
+);
+
+export const optionalEnvironmentUrl = z.preprocess(
+    value => (value === '' ? undefined : value),
+    z.url('Expected a valid URL').optional()
+);
+
+/**
+ * Deployment manifests historically use both true/false and 1/0. These are the complete
+ * accepted spellings; every other value fails validation.
+ */
+export const environmentBoolean = z
+    .enum(['true', 'false', '1', '0'])
+    .transform(value => value === 'true' || value === '1');
+
+export const optionalEnvironmentBoolean = z.preprocess(
+    value => (value === '' || value === undefined ? undefined : value),
+    environmentBoolean.optional()
+);
+
+export const environmentPort = z.coerce.number().int().min(1).max(65_535);
+
+export const optionalEnvironmentPort = z.preprocess(
+    value => (value === '' || value === undefined ? undefined : value),
+    environmentPort.optional()
+);
+
+export const parseEnvironment = <Schema extends z.ZodType>(
+    schema: Schema,
+    raw: Record<string, unknown>,
+    context: EnvironmentSource
+): z.output<Schema> => {
+    const result = schema.safeParse(raw);
+
+    if (result.success) return result.data;
+
+    const issues = result.error.issues
+        .map(issue => {
+            const key = issue.path.length ? issue.path.map(String).join('.') : '(environment)';
+
+            return `${key}\n  ${issue.message}`;
+        })
+        .join('\n\n');
+
+    throw new EnvironmentConfigurationError(
+        [
+            `Invalid ${context.project} configuration`,
+            '',
+            issues,
+            '',
+            `Configuration source: ${context.source}`,
+            `Copy ${context.examplePath} to .env and correct the values above.`,
+        ].join('\n')
+    );
+};

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;
+    }
+};

package/src/index.ts

@@ -9,7 +9,7 @@ import type { DataTransformer } from '@trpc/server';
 export const isHex = (str: string) => /^[0-9a-f]+$/i.test(str);
 
 /** Determines whether or not an object is an encrypted JWE */
-export const isEncrypted = (item: Record<string, any>): item is JWE => {
+export const isEncrypted = (item: unknown): item is JWE => {
     return JWEValidator.safeParse(item).success;
 };
 
@@ -17,7 +17,7 @@ export const isEncrypted = (item: Record<string, any>): item is JWE => {
  * tRPC data transformer that handles RegExp serialization/deserialization
  */
 export const RegExpTransformer: DataTransformer = {
-    serialize(object: any): any {
+    serialize(object) {
         return JSON.stringify(object, (_key, value) => {
             if (value instanceof RegExp) return value.toString(); // Converts to format /pattern/flags
 
@@ -25,7 +25,7 @@ export const RegExpTransformer: DataTransformer = {
         });
     },
 
-    deserialize(object: any): any {
+    deserialize(object) {
         // Old clients will for some reason already be deserialized, so this checks for that to retain
         // backwards compat
         if (typeof object !== 'string') return object;
@@ -51,14 +51,14 @@ export const RegExpTransformer: DataTransformer = {
 /**
  * Determines if a credential uses VC 2.0 format by checking the context array
  */
-export const isVC2Format = (credential: UnsignedVC | VC): boolean => {
-    if (!credential['@context'] || !Array.isArray(credential['@context'])) {
-        return false;
-    }
+export const isVC2Format = (credential: unknown): boolean => {
+    if (!credential || typeof credential !== 'object' || !('@context' in credential)) return false;
+
+    const context = credential['@context'];
 
-    return credential['@context'].some(
-        context => context === 'https://www.w3.org/ns/credentials/v2'
-    );
+    return Array.isArray(context)
+        ? context.some(value => value === 'https://www.w3.org/ns/credentials/v2')
+        : context === 'https://www.w3.org/ns/credentials/v2';
 };
 
 /** Unwraps a boost credential from a CertifiedBoostCredential, if it is one */
@@ -86,6 +86,7 @@ export * from './Utilities';
 export * from './app-install';
 export * from './credential-format';
 export * from './did';
+export * from './environment';
 
 // ADR-0001 Phase 1: format-tagged credential storage projector
 export * from './credential-format';