@learncard/credential-library 2.0.4 → 2.0.5

package/src/__tests__/bundles.test.ts

@@ -0,0 +1,234 @@
+import { KnownAchievementTypeValidator } from '@learncard/types';
+import { describe, expect, it } from 'vitest';
+
+import { getBundle, getFixture, isCredentialFixture, prepareFixture } from '../index';
+
+const STANDARD_CONTEXTS = new Set([
+    'https://www.w3.org/ns/credentials/v2',
+    'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
+    'https://purl.imsglobal.org/spec/clr/v2p0/context.json',
+]);
+
+const PROPRIETARY_FIELDS = new Set([
+    'address',
+    'attachments',
+    'boostId',
+    'boostID',
+    'display',
+    'groupID',
+    'skills',
+]);
+
+const collectContexts = (value: unknown): string[] => {
+    if (Array.isArray(value)) return value.flatMap(collectContexts);
+    if (!value || typeof value !== 'object') return [];
+
+    return Object.entries(value as Record<string, unknown>).flatMap(([key, nested]) =>
+        key === '@context' && Array.isArray(nested)
+            ? nested.filter((context): context is string => typeof context === 'string')
+            : collectContexts(nested)
+    );
+};
+
+const collectPropertyValues = (value: unknown, property: string): unknown[] => {
+    if (Array.isArray(value)) {
+        return value.flatMap(nested => collectPropertyValues(nested, property));
+    }
+    if (!value || typeof value !== 'object') return [];
+
+    return Object.entries(value as Record<string, unknown>).flatMap(([key, nested]) => [
+        ...(key === property ? [nested] : []),
+        ...collectPropertyValues(nested, property),
+    ]);
+};
+
+const collectProprietaryFields = (value: unknown): string[] => {
+    if (Array.isArray(value)) return value.flatMap(collectProprietaryFields);
+    if (!value || typeof value !== 'object') return [];
+
+    return Object.entries(value as Record<string, unknown>).flatMap(([key, nested]) => [
+        ...(PROPRIETARY_FIELDS.has(key) ? [key] : []),
+        ...collectProprietaryFields(nested),
+    ]);
+};
+
+const collectSubjectIds = (credential: unknown): unknown[] =>
+    collectPropertyValues(credential, 'credentialSubject').flatMap(subject => {
+        const subjects = Array.isArray(subject) ? subject : [subject];
+
+        return subjects.map(currentSubject =>
+            currentSubject && typeof currentSubject === 'object'
+                ? (currentSubject as Record<string, unknown>).id
+                : undefined
+        );
+    });
+
+describe('student credential bundle', () => {
+    it('prepares every manifest entry as a standards-pure credential', () => {
+        const bundle = getBundle('student');
+        const fixtureIds = bundle.entries.map(entry => entry.fixtureId);
+        let backgroundImageHintCount = 0;
+
+        expect(bundle.entries).toHaveLength(33);
+        expect(new Set(fixtureIds).size).toBe(fixtureIds.length);
+        expect(bundle.entries.some(entry => entry.fixtureId.startsWith('clr/'))).toBe(true);
+        expect(new Set(bundle.entries.map(entry => entry.issuer.profileId)).size).toBeGreaterThan(
+            1
+        );
+
+        for (const entry of bundle.entries) {
+            expect(entry.issuer.profileId).toMatch(/^sample-/);
+
+            const fixture = getFixture(entry.fixtureId);
+            expect(isCredentialFixture(fixture)).toBe(true);
+            if (!isCredentialFixture(fixture)) {
+                throw new Error(`${entry.fixtureId} is not a credential fixture`);
+            }
+
+            const sourceCredential = fixture.credential as Record<string, unknown>;
+            expect(sourceCredential).not.toHaveProperty('id');
+            expect(sourceCredential).not.toHaveProperty('proof');
+            expect(sourceCredential).not.toHaveProperty('credentialStatus');
+            expect(sourceCredential).not.toHaveProperty('image');
+            expect(collectProprietaryFields(sourceCredential)).toEqual([]);
+
+            const serializedCredential = JSON.stringify(sourceCredential);
+            expect(serializedCredential).not.toContain('ctx.learncard.com');
+            expect(serializedCredential).not.toContain('BoostCredential');
+            expect(serializedCredential).not.toContain('"BoostID"');
+
+            const contexts = collectContexts(sourceCredential);
+            expect(contexts.length).toBeGreaterThan(0);
+            expect(contexts.every(context => STANDARD_CONTEXTS.has(context))).toBe(true);
+
+            const achievementTypes = collectPropertyValues(sourceCredential, 'achievementType');
+            expect(achievementTypes.length).toBeGreaterThan(0);
+            achievementTypes.forEach(achievementType => {
+                expect(KnownAchievementTypeValidator.safeParse(achievementType).success).toBe(true);
+            });
+
+            backgroundImageHintCount += collectPropertyValues(sourceCredential, 'tag').filter(
+                tags =>
+                    Array.isArray(tags) &&
+                    tags.some(
+                        tag =>
+                            typeof tag === 'string' &&
+                            tag.startsWith('lc:bgImage:https://cdn.filestackcontent.com/')
+                    )
+            ).length;
+
+            const issuerDid = `did:web:demo.example:users:${entry.issuer.profileId}`;
+            const credential = prepareFixture(fixture, {
+                issuerDid,
+                subjectDid: 'did:example:prepared-student',
+                freshIds: false,
+            });
+
+            expect(fixture.validity).toBe('valid');
+            expect(fixture.validator?.safeParse(credential).success ?? true).toBe(true);
+            expect(credential.name).toBe(entry.name ?? sourceCredential.name);
+            expect(credential.issuer).toMatchObject({ id: issuerDid });
+            expect(new Set(collectSubjectIds(credential))).toEqual(
+                new Set(['did:example:prepared-student'])
+            );
+        }
+
+        expect(backgroundImageHintCount).toBe(26);
+    });
+
+    it('preserves the supplied Capstone Project badge presentation as OBv3 tags', () => {
+        const fixture = getFixture('obv3/student-capstone-project');
+        if (!isCredentialFixture(fixture)) throw new Error('Capstone Project fixture is missing');
+
+        const subject = fixture.credential.credentialSubject as Record<string, unknown>;
+        const achievement = subject.achievement as Record<string, unknown>;
+
+        expect(achievement.achievementType).toBe('Assignment');
+        expect(achievement.image).toBe('https://cdn.filestackcontent.com/W6nqpwFySGO5EwFi4dAk');
+        expect(achievement.tag).toEqual(
+            expect.arrayContaining([
+                'lc:category:Accomplishment',
+                'lc:subtype:Project',
+                'lc:displayType:badge',
+                'lc:bgImage:https://cdn.filestackcontent.com/OQWyjlSauKQAD3Z2qwEw',
+            ])
+        );
+    });
+
+    it('preserves the supplied ID artwork and issuer marks as OBv3 tags', () => {
+        const expectations = [
+            {
+                fixtureId: 'obv3/student-world-scouting-troop-id',
+                idBackgroundImage: 'https://cdn.filestackcontent.com/SyKchHHLRucuS087I4rE',
+                idIssuerThumbnail: 'https://cdn.filestackcontent.com/KsarfGXWS2uR4xmqEeDD',
+            },
+            {
+                fixtureId: 'obv3/student-hill-valley-high-school-student-id',
+                idBackgroundImage: 'https://cdn.filestackcontent.com/cKTNAyZ9RGF4oUGTRh2r',
+                idIssuerThumbnail: 'https://cdn.filestackcontent.com/Otu9MBWYSemRxEKJQxAB',
+            },
+            {
+                fixtureId: 'obv3/student-motlow-college-id',
+                idBackgroundImage: 'https://cdn.filestackcontent.com/CnqU0q7xQoOxkwQMliz4',
+                idIssuerThumbnail: 'https://cdn.filestackcontent.com/mSjAUhi3Rw2BH2pp4Nah',
+            },
+        ];
+
+        for (const expectation of expectations) {
+            const fixture = getFixture(expectation.fixtureId);
+            if (!isCredentialFixture(fixture)) {
+                throw new Error(`${expectation.fixtureId} fixture is missing`);
+            }
+
+            const subject = fixture.credential.credentialSubject as Record<string, unknown>;
+            const achievement = subject.achievement as Record<string, unknown>;
+
+            expect(achievement.tag).toEqual(
+                expect.arrayContaining([
+                    `lc:idBackgroundImage:${expectation.idBackgroundImage}`,
+                    `lc:idIssuerThumbnail:${expectation.idIssuerThumbnail}`,
+                    'lc:idDimBackgroundImage:true',
+                ])
+            );
+        }
+    });
+
+    it('preserves all authoritative CLR records and the official identifier context', () => {
+        const fixture = getFixture('clr/student-official-academic-transcript');
+        if (!isCredentialFixture(fixture)) throw new Error('Student CLR fixture is missing');
+
+        const transcriptEntry = getBundle('student').entries.find(
+            entry => entry.fixtureId === 'clr/student-official-academic-transcript'
+        );
+        expect(transcriptEntry?.issuer.profileId).toBe('sample-redwood-valley-university');
+        expect(fixture.credential.issuer).toMatchObject({
+            id: 'did:web:network.learncard.com:users:redwoodvalley2',
+        });
+
+        const subject = fixture.credential.credentialSubject as Record<string, unknown>;
+        const context = subject['@context'];
+        const embeddedCredentials = subject.verifiableCredential as Record<string, unknown>[];
+        const typographyCourse = embeddedCredentials.find(credential => {
+            const embeddedSubject = credential.credentialSubject as Record<string, unknown>;
+            const achievement = embeddedSubject.achievement as Record<string, unknown>;
+
+            return achievement.humanCode === 'IMD 120';
+        });
+
+        expect(context).toEqual({
+            identifier: {
+                '@id': 'https://purl.imsglobal.org/spec/vc/clr/vocab.html#identifier-1',
+                '@type': 'https://purl.imsglobal.org/spec/vc/ob/vocab.html#Identifier',
+                '@container': '@set',
+            },
+        });
+        expect(embeddedCredentials).toHaveLength(35);
+        expect(typographyCourse).toBeDefined();
+        expect(
+            (
+                (typographyCourse?.credentialSubject as Record<string, unknown>)
+                    .achievement as Record<string, unknown>
+            ).name
+        ).toBe('Typography and Layout');
+    });
+});

package/src/__tests__/clr-non-academic.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, it } from 'vitest';
+import {
+    UnsignedAchievementCredentialValidator,
+    UnsignedClrCredentialValidator,
+    UnsignedVCValidator,
+} from '@learncard/types';
+
+import { ALL_FIXTURES } from '../fixtures';
+import { clrEmploymentRecord } from '../fixtures/clr/employment-record';
+import { clrTrainingProviderRecord } from '../fixtures/clr/training-provider-record';
+import { clrMilitaryTrainingRecord } from '../fixtures/clr/military-training-record';
+import { clrProfessionalOrganizationRecord } from '../fixtures/clr/professional-organization-record';
+import { clrLicensingRegulatoryRecord } from '../fixtures/clr/licensing-regulatory-record';
+import { clrMixedCareerRecord } from '../fixtures/clr/mixed-career-record';
+import { prepareFixture } from '../prepare';
+import type { CredentialFixture } from '../types';
+
+type JsonRecord = Record<string, unknown>;
+
+const asRecord = (value: unknown): JsonRecord => {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Expected a JSON object in a CLR fixture');
+    }
+    return value as JsonRecord;
+};
+
+const asRecords = (value: unknown): JsonRecord[] => {
+    if (!Array.isArray(value)) throw new Error('Expected a JSON array in a CLR fixture');
+    return value.map(asRecord);
+};
+
+const subjectOf = (credential: JsonRecord): JsonRecord => asRecord(credential.credentialSubject);
+const achievementOf = (credential: JsonRecord): JsonRecord =>
+    asRecord(subjectOf(credential).achievement);
+const childrenOf = (credential: JsonRecord): JsonRecord[] =>
+    asRecords(subjectOf(credential).verifiableCredential);
+
+const fixtures: CredentialFixture[] = [
+    clrEmploymentRecord,
+    clrTrainingProviderRecord,
+    clrMilitaryTrainingRecord,
+    clrProfessionalOrganizationRecord,
+    clrLicensingRegulatoryRecord,
+    clrMixedCareerRecord,
+];
+const cases = fixtures.map(fixture => [fixture.id, fixture] as const);
+
+/** Check achievement, result-description and rubric references without network lookups. */
+const expectResolvableReferences = (credential: JsonRecord): void => {
+    const children = childrenOf(credential);
+    const achievementIds = new Set(children.map(child => achievementOf(child).id));
+    const childIds = children.map(child => child.id);
+    expect(new Set(childIds).size).toBe(childIds.length);
+
+    for (const association of asRecords(subjectOf(credential).association)) {
+        // CLR associations target achievement definitions, not credential IDs.
+        expect(achievementIds.has(association.sourceId)).toBe(true);
+        expect(achievementIds.has(association.targetId)).toBe(true);
+    }
+
+    for (const child of children) {
+        const descriptions = asRecords(achievementOf(child).resultDescription);
+        const byId = new Map(descriptions.map(description => [description.id, description]));
+        expect(byId.size).toBe(descriptions.length);
+
+        for (const result of asRecords(subjectOf(child).result)) {
+            const description = byId.get(result.resultDescription);
+            expect(description).toBeDefined();
+            if (!description) throw new Error('Missing referenced result description');
+            if (description.resultType === 'Status') expect(result.status).toBeDefined();
+            if (result.value !== undefined) expect(typeof result.value).toBe('string');
+
+            const levels = description.rubricCriterionLevel
+                ? asRecords(description.rubricCriterionLevel)
+                : [];
+            if (result.achievedLevel) {
+                expect(levels.some(level => level.id === result.achievedLevel)).toBe(true);
+            }
+            if (description.requiredLevel) {
+                expect(levels.some(level => level.id === description.requiredLevel)).toBe(true);
+            }
+        }
+    }
+};
+
+describe('LC-2184 non-academic CLR fixtures', () => {
+    it.each(cases)('%s is registered exactly once and explicitly unsigned', (_id, fixture) => {
+        expect(ALL_FIXTURES.filter(entry => entry.id === fixture.id)).toEqual([fixture]);
+        expect(fixture.spec).toBe('clr-v2');
+        expect(fixture.signed).toBe(false);
+        expect(fixture.validity).toBe('valid'); // Valid unsigned template, not a verified VC.
+        expect(fixture.source).toBe('synthetic');
+        expect(fixture.credential.proof).toBeUndefined();
+        for (const child of childrenOf(fixture.credential)) expect(child.proof).toBeUndefined();
+    });
+
+    it.each(cases)(
+        '%s passes the shared unsigned CLR and achievement validators',
+        (_id, fixture) => {
+            expect(UnsignedVCValidator.safeParse(fixture.credential).success).toBe(true);
+            expect(UnsignedClrCredentialValidator.safeParse(fixture.credential).success).toBe(true);
+            for (const child of childrenOf(fixture.credential)) {
+                expect(UnsignedAchievementCredentialValidator.safeParse(child).success).toBe(true);
+            }
+        }
+    );
+
+    it.each(cases)(
+        '%s binds every embedded record to the same synthetic learner',
+        (_id, fixture) => {
+            const parentSubject = subjectOf(fixture.credential);
+            expect(parentSubject.id).toBe('did:example:lc2184-alex-morgan');
+            for (const child of childrenOf(fixture.credential)) {
+                expect(subjectOf(child).id).toBe(parentSubject.id);
+            }
+        }
+    );
+
+    it.each(cases)('%s has resolvable achievement and result references', (_id, fixture) => {
+        expectResolvableReferences(fixture.credential);
+    });
+
+    it.each(cases)('%s keeps references intact when UUIDs are regenerated', (_id, fixture) => {
+        const before = JSON.stringify(fixture.credential);
+        const prepared = prepareFixture(fixture, {
+            issuerDid: 'did:example:lc2184-test-publisher',
+            // Deliberately no subjectDid: prepareFixture is not a recursive child rebinder.
+            freshIds: true,
+            validFrom: '2026-09-01T12:00:00Z',
+        });
+        expect(prepared.id).not.toBe(fixture.credential.id);
+        expectResolvableReferences(prepared);
+        expect(JSON.stringify(fixture.credential)).toBe(before);
+    });
+
+    it('keeps non-academic training free of inferred GPA, terms, and academic credits', () => {
+        const children = childrenOf(clrTrainingProviderRecord.credential);
+        for (const child of children) {
+            expect(subjectOf(child).term).toBeUndefined();
+            expect(subjectOf(child).creditsEarned).toBeUndefined();
+            expect(achievementOf(child).creditsAvailable).toBeUndefined();
+            expect(
+                asRecords(achievementOf(child).resultDescription).some(
+                    description => description.resultType === 'GradePointAverage'
+                )
+            ).toBe(false);
+        }
+        const ongoing = children.find(child =>
+            asRecords(subjectOf(child).result).some(result => result.status === 'InProgress')
+        );
+        expect(ongoing).toBeDefined();
+        if (!ongoing) throw new Error('Missing ongoing training record');
+        expect(subjectOf(ongoing).activityStartDate).toBeDefined();
+        expect(subjectOf(ongoing).activityEndDate).toBeUndefined();
+    });
+
+    it('includes achieved-level-only results without manufacturing value or completion status', () => {
+        for (const fixture of [clrEmploymentRecord, clrMilitaryTrainingRecord]) {
+            const results = childrenOf(fixture.credential).flatMap(child =>
+                asRecords(subjectOf(child).result)
+            );
+            expect(
+                results.some(
+                    result =>
+                        typeof result.achievedLevel === 'string' &&
+                        result.value === undefined &&
+                        result.status === undefined
+                )
+            ).toBe(true);
+        }
+    });
+
+    it('retains an expired child without calling the entire licensing collection expired', () => {
+        const credential = clrLicensingRegulatoryRecord.credential;
+        const snapshot = Date.parse(String(credential.validFrom));
+        const children = childrenOf(credential);
+        expect(children.some(child => Date.parse(String(child.validUntil)) < snapshot)).toBe(true);
+        expect(children.some(child => Date.parse(String(child.validUntil)) > snapshot)).toBe(true);
+        expect(Date.parse(String(credential.validUntil))).toBeGreaterThan(snapshot);
+        expect(children.some(child => subjectOf(child).licenseNumber === 'SYN-LIC-2184-042')).toBe(
+            true
+        );
+        // No fake status list or cryptographic proof is used to claim real-world standing.
+        for (const child of children) expect(child.credentialStatus).toBeUndefined();
+    });
+
+    it('keeps course-first mixed records and their multiple issuers', () => {
+        const credential = clrMixedCareerRecord.credential;
+        const children = childrenOf(credential);
+        expect(achievementOf(children[0]!).achievementType).toBe('Course');
+        expect(children.map(child => achievementOf(child).achievementType)).toEqual([
+            'Course',
+            'Achievement',
+            'Membership',
+            'ApprenticeshipCertificate',
+            'Competency',
+            'License',
+        ]);
+        const publisherId = asRecord(credential.issuer).id;
+        const childIssuerIds = new Set(children.map(child => asRecord(child.issuer).id));
+        expect(childIssuerIds.size).toBe(4);
+        expect(childIssuerIds.has(publisherId)).toBe(false);
+    });
+
+    it('separates activity end, award, and credential validity dates', () => {
+        const work = childrenOf(clrEmploymentRecord.credential)[0]!;
+        expect(subjectOf(work).activityEndDate).toBe('2026-06-30T17:00:00Z');
+        expect(work.awardedDate).toBe('2026-07-10T12:00:00Z');
+        expect(work.validFrom).toBe('2026-08-15T12:00:00Z');
+    });
+
+    it('keeps duplicated source credentials identical across independent fixture objects', () => {
+        const source = childrenOf(clrProfessionalOrganizationRecord.credential)[0]!;
+        const copy = childrenOf(clrMixedCareerRecord.credential).find(
+            child => child.id === source.id
+        );
+        expect(copy).toEqual(source);
+        expect(copy).not.toBe(source);
+    });
+});

package/src/__tests__/registry.test.ts

@@ -582,6 +582,37 @@ describe('prepareFixture', () => {
         expect(subject.id).toBe(subjectDid);
     });
 
+    it('preserves signed credentials nested in a CLR', () => {
+        const fixture = getFixture('vc-v2/basic');
+        const signedEmbeddedCredential = {
+            '@context': ['https://www.w3.org/ns/credentials/v2'],
+            id: fixture.credential.id,
+            type: ['VerifiableCredential'],
+            issuer: 'did:example:nested-issuer',
+            validFrom: '2025-01-01T00:00:00Z',
+            credentialSubject: { id: 'did:example:signed-subject' },
+            proof: { type: 'DataIntegrityProof', proofValue: 'signed-value' },
+        };
+        const prepared = prepareFixture(
+            {
+                ...fixture,
+                credential: {
+                    ...fixture.credential,
+                    credentialSubject: {
+                        id: 'did:example:old-root',
+                        verifiableCredential: [signedEmbeddedCredential],
+                    },
+                },
+            },
+            { issuerDid, subjectDid }
+        );
+        const subject = prepared.credentialSubject as UnknownRecord;
+        const embedded = subject.verifiableCredential as UnknownRecord[];
+
+        expect(subject.id).toBe(subjectDid);
+        expect(embedded[0]).toEqual(signedEmbeddedCredential);
+    });
+
     it('generates fresh UUIDs for id fields by default', () => {
         const fixture = getFixture('obv3/minimal-badge');
         const prepared = prepareFixture(fixture, { issuerDid });

package/src/bundles/index.ts

@@ -0,0 +1,19 @@
+import type { CredentialBundle } from './types';
+import { studentBundle } from './student';
+
+const BUNDLES: Readonly<Record<string, CredentialBundle>> = {
+    [studentBundle.id]: studentBundle,
+};
+
+export const getBundle = (id: string): CredentialBundle => {
+    const bundle = BUNDLES[id];
+
+    if (!bundle) {
+        throw new Error(`Unknown credential bundle: ${id}`);
+    }
+
+    return bundle;
+};
+
+export { studentBundle } from './student';
+export type { CredentialBundle, CredentialBundleEntry, CredentialBundleIssuer } from './types';