@learncard/helpers 1.4.1 → 1.5.0

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.1",
+    "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/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';