@learncard/helpers 1.4.0 → 1.5.0

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/dist/index.d.cts

@@ -28,6 +28,7 @@ export * from './bitstring-status-list';
 export * from './Utilities';
 export * from './app-install';
 export * from './credential-format';
+export * from './credential-refresh';
 export * from './did';
 export * from './environment';
 export * from './credential-format';

package/dist/index.d.ts

@@ -28,6 +28,7 @@ export * from './bitstring-status-list';
 export * from './Utilities';
 export * from './app-install';
 export * from './credential-format';
+export * from './credential-refresh';
 export * from './did';
 export * from './environment';
 export * from './credential-format';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAgB,UAAU,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,YAA6B,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,KAAG,IAAI,IAAI,GAEnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,eA8B/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,OAAO,KAAG,OAQjD,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,GAAI,KAAK,EAAE,GAAG,UAAU,QAMzD,CAAC;AAGF,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AAGxC,cAAc,aAAa,CAAC;AAG5B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,OAAO,CAAC;AACtB,cAAc,eAAe,CAAC;AAG9B,cAAc,qBAAqB,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,OAK1C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAgB,UAAU,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,YAA6B,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,KAAG,IAAI,IAAI,GAEnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,eA8B/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,OAAO,KAAG,OAQjD,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,GAAI,KAAK,EAAE,GAAG,UAAU,QAMzD,CAAC;AAGF,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AAGxC,cAAc,aAAa,CAAC;AAG5B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,OAAO,CAAC;AACtB,cAAc,eAAe,CAAC;AAG9B,cAAc,qBAAqB,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,OAK1C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/helpers",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "description": "Shared helpers for LearnCard packages",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -54,7 +54,7 @@
     "dependencies": {
         "@noble/hashes": "^1.8.0",
         "@sd-jwt/decode": "^0.19.0",
-        "@learncard/types": "5.18.3",
+        "@learncard/types": "5.19.0",
         "@trpc/server": "11.8.0",
         "immer": "^10.0.3",
         "use-immer": "^0.9.0",

package/src/credential-refresh.ts

@@ -0,0 +1,128 @@
+import {
+    SupportedCredentialRefreshServiceValidator,
+    type SupportedCredentialRefreshService,
+} from '@learncard/types';
+
+/**
+ * Canonical helpers for credential refresh (LC-2117, LC-2135, LC-2136).
+ *
+ * These helpers are storage-independent: they select a supported refresh service,
+ * normalize issuer/effective-time identity, and provide deterministic canonicalization
+ * plus a proof-insensitive content comparison used by both the holder SDK and the
+ * brain-service publication pipeline.
+ */
+
+type RefreshableCredential = Record<string, unknown> & {
+    refreshService?: unknown;
+    issuer?: string | { id?: unknown } | null;
+    validFrom?: unknown;
+    issuanceDate?: unknown;
+    proof?: unknown;
+};
+
+/**
+ * Selects the first supported refresh service from a credential's `refreshService`.
+ *
+ * Accepts a single service object or an array. An array is treated as ordered: the
+ * first entry whose type is supported is selected. Supported types are
+ * `1EdTechCredentialRefresh` and `LearnCardCredentialRefresh2026`.
+ *
+ * @returns the supported service, or `undefined` when none is present/supported
+ */
+export const getSupportedRefreshService = (
+    vc: RefreshableCredential
+): SupportedCredentialRefreshService | undefined => {
+    const refreshService = vc?.refreshService;
+
+    if (!refreshService) return undefined;
+
+    const services = Array.isArray(refreshService) ? refreshService : [refreshService];
+
+    for (const service of services) {
+        const parsed = SupportedCredentialRefreshServiceValidator.safeParse(service);
+
+        if (parsed.success) return parsed.data;
+    }
+
+    return undefined;
+};
+
+/**
+ * Normalizes a credential's issuer to its identifier.
+ *
+ * Handles both the string form (`issuer: 'did:example:x'`) and the object form
+ * (`issuer: { id: 'did:example:x', ... }`).
+ */
+export const getCredentialIssuerId = (vc: RefreshableCredential): string | undefined => {
+    const issuer = vc?.issuer;
+
+    if (!issuer) return undefined;
+    if (typeof issuer === 'string') return issuer;
+
+    return typeof issuer.id === 'string' ? issuer.id : undefined;
+};
+
+/**
+ * Returns the credential's effective timestamp in milliseconds since the epoch.
+ *
+ * Prefers VCDM 2.0 `validFrom` and falls back to VCDM 1.1 `issuanceDate`. Returns
+ * `undefined` when no parseable timestamp exists.
+ */
+export const getCredentialEffectiveTime = (vc: RefreshableCredential): number | undefined => {
+    const raw = vc?.validFrom ?? vc?.issuanceDate;
+
+    if (typeof raw !== 'string' || raw.length === 0) return undefined;
+
+    const parsed = Date.parse(raw);
+
+    return Number.isNaN(parsed) ? undefined : parsed;
+};
+
+/**
+ * Deterministically canonicalizes a JSON-like value: object keys are recursively
+ * sorted, array order is preserved, and primitives pass through unchanged.
+ */
+export const canonicalizeCredentialContent = <T>(value: T): T => {
+    if (Array.isArray(value)) {
+        return value.map(entry => canonicalizeCredentialContent(entry)) as T;
+    }
+
+    if (value !== null && typeof value === 'object') {
+        const source = value as Record<string, unknown>;
+        const sorted: Record<string, unknown> = {};
+
+        for (const key of Object.keys(source).sort()) {
+            sorted[key] = canonicalizeCredentialContent(source[key]);
+        }
+
+        return sorted as T;
+    }
+
+    return value;
+};
+
+/** Serializes a value to a deterministic canonical JSON string */
+export const canonicalizeCredentialJson = (value: unknown): string =>
+    JSON.stringify(canonicalizeCredentialContent(value));
+
+/**
+ * Proof-insensitive content comparison for refresh changed-content detection.
+ *
+ * Only the top-level `proof` property is excluded; everything else (subject claims,
+ * identifiers, timestamps, services) participates in the comparison.
+ */
+export const credentialContentsEqual = (
+    first: RefreshableCredential,
+    second: RefreshableCredential
+): boolean => {
+    const stripProof = (vc: RefreshableCredential) => {
+        const { proof: _proof, ...rest } = vc ?? {};
+
+        return rest;
+    };
+
+    return (
+        canonicalizeCredentialJson(stripProof(first)) ===
+        canonicalizeCredentialJson(stripProof(second))
+    );
+};

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

@@ -85,6 +85,7 @@ export * from './Utilities';
 // Export app install helpers
 export * from './app-install';
 export * from './credential-format';
+export * from './credential-refresh';
 export * from './did';
 export * from './environment';