@learncard/helpers 1.6.2 → 1.7.0

package/dist/index.d.cts

@@ -42,4 +42,5 @@ export * from './credential-format';
  */
 export declare const isAppDidWeb: (did?: string) => boolean;
 export * from './share-content-canonical';
+export * from './credential-materialization';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -42,4 +42,5 @@ export * from './credential-format';
  */
 export declare const isAppDidWeb: (did?: string) => boolean;
 export * from './share-content-canonical';
+export * from './credential-materialization';
 //# sourceMappingURL=index.d.ts.map

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,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;AAEF,cAAc,2BAA2B,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;AAEF,cAAc,2BAA2B,CAAC;AAE1C,cAAc,8BAA8B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/helpers",
-    "version": "1.6.2",
+    "version": "1.7.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.23.0",
+        "@learncard/types": "5.23.2",
         "@trpc/server": "11.8.0",
         "immer": "^10.0.3",
         "use-immer": "^0.9.0",

package/src/credential-materialization.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import {
+    materializeCredentialFields,
+    normalizeCredentialAwardDate,
+    parseCredentialNumber,
+} from './credential-materialization';
+
+describe('standard credential materialization', () => {
+    it('converts only declared numeric paths, preserving zero, result text and identifiers', () => {
+        const input = {
+            type: ['VerifiableCredential', 'OpenBadgeCredential'],
+            credentialSubject: {
+                id: '0012',
+                creditsEarned: '0',
+                achievement: { creditsAvailable: '12.5' },
+                result: [{ value: '95' }],
+            },
+            awardedDate: '2024-02-29',
+        };
+        expect(materializeCredentialFields(input)).toEqual({
+            ...input,
+            credentialSubject: {
+                ...input.credentialSubject,
+                creditsEarned: 0,
+                achievement: { creditsAvailable: 12.5 },
+            },
+            awardedDate: '2024-02-29T00:00:00.000Z',
+        });
+        expect(input.credentialSubject.creditsEarned).toBe('0');
+    });
+    it.each(['', '   '])('omits blank optional credits %j without changing the input', value => {
+        const input = {
+            type: ['OpenBadgeCredential'],
+            credentialSubject: { creditsEarned: value, achievement: { creditsAvailable: value } },
+        };
+        expect(materializeCredentialFields(input)).toEqual({
+            type: ['OpenBadgeCredential'],
+            credentialSubject: { achievement: {} },
+        });
+        expect(input.credentialSubject.creditsEarned).toBe(value);
+    });
+    it.each(['', '  '])(
+        'omits a blank optional awardedDate %j without mutating the source',
+        awardedDate => {
+            const input = { type: ['OpenBadgeCredential'], awardedDate, credentialSubject: {} };
+            expect(materializeCredentialFields(input)).not.toHaveProperty('awardedDate');
+            expect(input.awardedDate).toBe(awardedDate);
+        }
+    );
+    it('does not modify signed credentials or embedded signed credentials', () => {
+        const signed = {
+            type: ['OpenBadgeCredential'],
+            proof: { proofValue: 'signature' },
+            credentialSubject: { creditsEarned: '3' },
+        };
+        expect(materializeCredentialFields(signed)).toBe(signed);
+        const clr = {
+            type: ['ClrCredential'],
+            credentialSubject: {
+                achievement: [{ creditsAvailable: '3' }],
+                verifiableCredential: [signed],
+            },
+        };
+        expect(materializeCredentialFields(clr)).toMatchObject({
+            credentialSubject: { verifiableCredential: [signed] },
+        });
+    });
+    it.each(['', '12 hours', '0x10', '1,000', 'Infinity', 'NaN', '1e999'])(
+        'rejects incomplete or ambiguous numeric input %s',
+        value => expect(() => parseCredentialNumber(value)).toThrow()
+    );
+    it('normalizes explicit offsets without changing the represented instant', () =>
+        expect(normalizeCredentialAwardDate('2024-03-01T01:30:00+02:00')).toBe(
+            '2024-02-29T23:30:00.000Z'
+        ));
+    it('preserves submillisecond precision while normalizing an explicit offset', () => {
+        expect(normalizeCredentialAwardDate('2024-03-01T01:30:00.123456+02:00')).toBe(
+            '2024-02-29T23:30:00.123456Z'
+        );
+    });
+    it.each([
+        '02/03/2024',
+        '2023-02-29',
+        '2024-04-31',
+        '2024-01-01T12:00:00',
+        '2024-05-01T10:00Z',
+        '2024-05-01 10:00:00Z',
+    ])('rejects ambiguous or invalid dates %s', value =>
+        expect(() => normalizeCredentialAwardDate(value)).toThrow('awardedDate')
+    );
+});

package/src/credential-materialization.ts

@@ -0,0 +1,101 @@
+export class CredentialFieldError extends Error {
+    constructor(readonly field: 'creditsEarned' | 'creditsAvailable' | 'awardedDate') {
+        super(`Invalid standard credential field: ${field}`);
+        this.name = 'CredentialFieldError';
+    }
+}
+
+/** Parse a complete finite decimal, without guessing locale or accepting partial input. */
+export const parseCredentialNumber = (value: unknown): number => {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (
+        typeof value !== 'string' ||
+        !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(value.trim())
+    )
+        throw new Error('Expected a finite decimal');
+    const number = Number(value.trim());
+    if (!Number.isFinite(number)) throw new Error('Expected a finite decimal');
+    return number;
+};
+
+/** Calendar dates keep their day; timestamps must declare their timezone. */
+export const normalizeCredentialAwardDate = (value: string): string => {
+    const text = value.trim();
+    const calendar = /^(\d{4})-(\d{2})-(\d{2})/.exec(text);
+    if (
+        !calendar ||
+        !/^\d{4}-\d{2}-\d{2}(?:T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))?$/i.test(
+            text
+        )
+    )
+        throw new CredentialFieldError('awardedDate');
+    const day = new Date(`${calendar[0]}T00:00:00Z`);
+    if (
+        !Number.isFinite(day.getTime()) ||
+        day.getUTCFullYear() !== Number(calendar[1]) ||
+        day.getUTCMonth() + 1 !== Number(calendar[2]) ||
+        day.getUTCDate() !== Number(calendar[3])
+    )
+        throw new CredentialFieldError('awardedDate');
+    const instant = text.length === 10 ? day : new Date(text);
+    if (!Number.isFinite(instant.getTime())) throw new CredentialFieldError('awardedDate');
+    const fraction = /\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/i.exec(text)?.[1];
+    const iso = instant.toISOString();
+    return fraction && fraction.length > 3 ? iso.replace(/\.\d{3}Z$/, `.${fraction}Z`) : iso;
+};
+
+const object = (value: unknown): value is Record<string, unknown> =>
+    Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+/**
+ * Materialize declared OBv3/CLR numeric fields after template substitution.
+ * Result values and identifiers remain strings. Signed credentials are never changed.
+ */
+export const materializeCredentialFields = (
+    credential: Record<string, unknown>
+): Record<string, unknown> => {
+    if (credential.proof) return credential;
+    const types = Array.isArray(credential.type) ? credential.type : [credential.type];
+    if (
+        !types.some(type =>
+            ['OpenBadgeCredential', 'AchievementCredential', 'ClrCredential'].includes(String(type))
+        )
+    )
+        return credential;
+    const result = structuredClone(credential);
+    const numeric = (
+        container: Record<string, unknown>,
+        field: 'creditsEarned' | 'creditsAvailable'
+    ): void => {
+        if (container[field] === undefined) return;
+        if (typeof container[field] === 'string' && !(container[field] as string).trim()) {
+            delete container[field];
+            return;
+        }
+        try {
+            container[field] = parseCredentialNumber(container[field]);
+        } catch {
+            throw new CredentialFieldError(field);
+        }
+    };
+    const subject = (value: unknown): void => {
+        if (!object(value)) return;
+        numeric(value, 'creditsEarned');
+        for (const achievement of Array.isArray(value.achievement)
+            ? value.achievement
+            : [value.achievement]) {
+            if (object(achievement)) numeric(achievement, 'creditsAvailable');
+        }
+        // Embedded verifiableCredential entries have independent signatures.
+    };
+    for (const value of Array.isArray(result.credentialSubject)
+        ? result.credentialSubject
+        : [result.credentialSubject])
+        subject(value);
+    if (result.awardedDate !== undefined) {
+        if (typeof result.awardedDate !== 'string') throw new CredentialFieldError('awardedDate');
+        if (!result.awardedDate.trim()) delete result.awardedDate;
+        else result.awardedDate = normalizeCredentialAwardDate(result.awardedDate);
+    }
+    return result;
+};

package/src/index.ts

@@ -108,3 +108,5 @@ export const isAppDidWeb = (did?: string): boolean => {
 };
 
 export * from './share-content-canonical';
+
+export * from './credential-materialization';