@learncard/credential-library 1.0.10 → 1.0.12

package/src/__tests__/registry.test.ts

@@ -0,0 +1,457 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { UnsignedVCValidator } from '@learncard/types';
+
+import {
+    getAllFixtures,
+    getFixture,
+    findFixture,
+    getFixtures,
+    getUnsignedFixtures,
+    getValidFixtures,
+    getInvalidFixtures,
+    getStats,
+    resetRegistry,
+    registerFixtures,
+    prepareFixture,
+    prepareFixtureById,
+} from '../index';
+
+import { ALL_FIXTURES } from '../fixtures';
+
+import type { CredentialFixture } from '../types';
+
+// ---------------------------------------------------------------------------
+// Ensure fixtures are loaded
+// ---------------------------------------------------------------------------
+
+let fixtures: readonly CredentialFixture[];
+
+beforeAll(() => {
+    fixtures = getAllFixtures();
+});
+
+// ---------------------------------------------------------------------------
+// Registry integrity
+// ---------------------------------------------------------------------------
+
+describe('Registry integrity', () => {
+    it('has at least 15 fixtures registered', () => {
+        expect(fixtures.length).toBeGreaterThanOrEqual(15);
+    });
+
+    it('has no duplicate IDs', () => {
+        const ids = fixtures.map(f => f.id);
+        const uniqueIds = new Set(ids);
+
+        expect(uniqueIds.size).toBe(ids.length);
+    });
+
+    it('every fixture has required metadata fields', () => {
+        for (const f of fixtures) {
+            expect(f.id).toBeTruthy();
+            expect(f.name).toBeTruthy();
+            expect(f.description).toBeTruthy();
+            expect(f.spec).toBeTruthy();
+            expect(f.profile).toBeTruthy();
+            expect(f.source).toBeTruthy();
+            expect(typeof f.signed).toBe('boolean');
+            expect(f.validity).toBeTruthy();
+            expect(f.credential).toBeTruthy();
+        }
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Per-fixture validation
+// ---------------------------------------------------------------------------
+
+describe('Fixture validation', () => {
+    describe('Valid fixtures pass their declared validator', () => {
+        const validFixtures = () => getAllFixtures().filter(f => f.validity === 'valid');
+
+        it.each(validFixtures().map(f => [f.id, f] as const))('%s', (_id, fixture) => {
+            if (!fixture.validator) return;
+
+            const result = fixture.validator.safeParse(fixture.credential);
+
+            expect(result.success).toBe(true);
+        });
+    });
+
+    describe('Valid fixtures also pass base UnsignedVC validator', () => {
+        const validFixtures = () => getAllFixtures().filter(f => f.validity === 'valid');
+
+        it.each(validFixtures().map(f => [f.id, f] as const))('%s', (_id, fixture) => {
+            const result = UnsignedVCValidator.safeParse(fixture.credential);
+
+            expect(result.success).toBe(true);
+        });
+    });
+
+    describe('Invalid fixtures fail their declared validator', () => {
+        const invalidFixtures = () =>
+            getAllFixtures().filter(f => f.validity === 'invalid' || f.validity === 'tampered');
+
+        it.each(invalidFixtures().map(f => [f.id, f] as const))('%s', (_id, fixture) => {
+            if (!fixture.validator) return;
+
+            const result = fixture.validator.safeParse(fixture.credential);
+
+            expect(result.success).toBe(false);
+        });
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Query API
+// ---------------------------------------------------------------------------
+
+describe('Query API', () => {
+    it('getFixture returns the correct fixture by ID', () => {
+        const fixture = getFixture('vc-v2/basic');
+
+        expect(fixture.id).toBe('vc-v2/basic');
+        expect(fixture.spec).toBe('vc-v2');
+    });
+
+    it('getFixture throws for unknown ID', () => {
+        expect(() => getFixture('nonexistent/fixture')).toThrow('not found');
+    });
+
+    it('findFixture returns undefined for unknown ID', () => {
+        expect(findFixture('nonexistent/fixture')).toBeUndefined();
+    });
+
+    it('filters by spec', () => {
+        const obv3 = getFixtures({ spec: 'obv3' });
+
+        expect(obv3.length).toBeGreaterThan(0);
+        expect(obv3.every(f => f.spec === 'obv3')).toBe(true);
+    });
+
+    it('filters by multiple specs', () => {
+        const results = getFixtures({ spec: ['vc-v1', 'vc-v2'] });
+
+        expect(results.length).toBeGreaterThan(0);
+        expect(results.every(f => f.spec === 'vc-v1' || f.spec === 'vc-v2')).toBe(true);
+    });
+
+    it('filters by profile', () => {
+        const badges = getFixtures({ profile: 'badge' });
+
+        expect(badges.length).toBeGreaterThan(0);
+        expect(badges.every(f => f.profile === 'badge')).toBe(true);
+    });
+
+    it('filters by features (AND logic)', () => {
+        const results = getFixtures({ features: ['evidence', 'alignment'] });
+
+        expect(results.length).toBeGreaterThan(0);
+
+        for (const f of results) {
+            expect(f.features).toContain('evidence');
+            expect(f.features).toContain('alignment');
+        }
+    });
+
+    it('filters by featuresAny (OR logic)', () => {
+        const results = getFixtures({ featuresAny: ['endorsement', 'results'] });
+
+        expect(results.length).toBeGreaterThan(0);
+
+        for (const f of results) {
+            const hasAny = f.features.includes('endorsement') || f.features.includes('results');
+
+            expect(hasAny).toBe(true);
+        }
+    });
+
+    it('filters by validity', () => {
+        const valid = getValidFixtures();
+        const invalid = getInvalidFixtures();
+
+        expect(valid.length).toBeGreaterThan(0);
+        expect(invalid.length).toBeGreaterThan(0);
+        expect(valid.every(f => f.validity === 'valid')).toBe(true);
+        expect(invalid.every(f => f.validity === 'invalid' || f.validity === 'tampered')).toBe(
+            true
+        );
+    });
+
+    it('filters by tags', () => {
+        const plugfest = getFixtures({ tags: ['plugfest'] });
+
+        expect(plugfest.length).toBeGreaterThan(0);
+
+        for (const f of plugfest) {
+            expect(f.tags).toContain('plugfest');
+        }
+    });
+
+    it('getUnsignedFixtures returns only unsigned', () => {
+        const unsigned = getUnsignedFixtures();
+
+        expect(unsigned.length).toBeGreaterThan(0);
+        expect(unsigned.every(f => f.signed === false)).toBe(true);
+    });
+
+    it('combined filters work together', () => {
+        const results = getFixtures({
+            spec: 'obv3',
+            profile: 'badge',
+            validity: 'valid',
+        });
+
+        expect(results.length).toBeGreaterThan(0);
+
+        for (const f of results) {
+            expect(f.spec).toBe('obv3');
+            expect(f.profile).toBe('badge');
+            expect(f.validity).toBe('valid');
+        }
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Stats
+// ---------------------------------------------------------------------------
+
+describe('Stats', () => {
+    it('reports correct totals', () => {
+        const stats = getStats();
+
+        expect(stats.total).toBe(fixtures.length);
+        expect(stats.signed + stats.unsigned).toBe(stats.total);
+
+        const specTotal = Object.values(stats.bySpec).reduce((sum, n) => sum + n, 0);
+
+        expect(specTotal).toBe(stats.total);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Coverage — ensure we have at least one fixture per spec category
+// ---------------------------------------------------------------------------
+
+describe('Spec coverage', () => {
+    const requiredSpecs = ['vc-v1', 'vc-v2', 'obv3', 'clr-v2'] as const;
+
+    it.each(requiredSpecs)('has at least one fixture for %s', spec => {
+        const results = getFixtures({ spec });
+
+        expect(results.length).toBeGreaterThan(0);
+    });
+
+    it('has at least one invalid fixture', () => {
+        const invalid = getInvalidFixtures();
+
+        expect(invalid.length).toBeGreaterThan(0);
+    });
+
+    it('has at least one boost fixture', () => {
+        const boosts = getFixtures({ profile: 'boost' });
+
+        expect(boosts.length).toBeGreaterThan(0);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// prepareFixture — bridge to wallet issuance
+// ---------------------------------------------------------------------------
+
+describe('prepareFixture', () => {
+    const issuerDid = 'did:key:z6MkTestIssuer123';
+    const subjectDid = 'did:key:z6MkTestSubject456';
+
+    type UnknownRecord = Record<string, unknown>;
+    type UnknownArrayRecord = Record<string, unknown> & {
+        [key: string]: unknown;
+    };
+
+    it('replaces string issuer with provided DID', () => {
+        const fixture = getFixture('vc-v2/basic');
+        const prepared = prepareFixture(fixture, { issuerDid });
+
+        expect(prepared.issuer).toBe(issuerDid);
+    });
+
+    it('replaces object issuer.id with provided DID', () => {
+        const fixture = getFixture('obv3/full-badge');
+        const prepared = prepareFixture(fixture, { issuerDid });
+
+        expect((prepared.issuer as Record<string, unknown>).id).toBe(issuerDid);
+        expect((prepared.issuer as Record<string, unknown>).name).toBeTruthy();
+    });
+
+    it('replaces credentialSubject.id with subjectDid', () => {
+        const fixture = getFixture('obv3/minimal-badge');
+        const prepared = prepareFixture(fixture, { issuerDid, subjectDid });
+        const subject = prepared.credentialSubject as Record<string, unknown>;
+
+        expect(subject.id).toBe(subjectDid);
+    });
+
+    it('generates fresh UUIDs for id fields by default', () => {
+        const fixture = getFixture('obv3/minimal-badge');
+        const prepared = prepareFixture(fixture, { issuerDid });
+
+        expect(prepared.id).toMatch(/^urn:uuid:/);
+        expect(prepared.id).not.toBe(fixture.credential.id);
+    });
+
+    it('keeps internal CLR references aligned when fresh IDs are generated', () => {
+        const fixture = getFixture('clr/westbridge-full');
+        const prepared = prepareFixture(fixture, { issuerDid });
+
+        const ids = new Set<string>();
+        const collectIds = (value: unknown): void => {
+            if (Array.isArray(value)) {
+                value.forEach(collectIds);
+                return;
+            }
+
+            if (!value || typeof value !== 'object') return;
+
+            const record = value as Record<string, unknown>;
+            if (typeof record.id === 'string') {
+                ids.add(record.id);
+            }
+
+            Object.values(record).forEach(collectIds);
+        };
+
+        collectIds(prepared);
+
+        const subject = prepared.credentialSubject as UnknownRecord;
+        const nested = subject.verifiableCredential as UnknownRecord[];
+
+        const programVc = nested.find(vc => {
+            const vcSubject = vc.credentialSubject as UnknownRecord | undefined;
+            const achievement = vcSubject?.achievement as UnknownRecord | undefined;
+            return achievement?.achievementType === 'BachelorDegree';
+        }) as UnknownRecord | undefined;
+
+        const programSubject = programVc?.credentialSubject as UnknownRecord | undefined;
+        const programAchievement = programSubject?.achievement as UnknownRecord | undefined;
+        const programResults = Array.isArray(programSubject?.result)
+            ? (programSubject?.result as UnknownArrayRecord[])
+            : [];
+        const programResultDescriptions = Array.isArray(programAchievement?.resultDescription)
+            ? (programAchievement?.resultDescription as UnknownArrayRecord[])
+            : [];
+        const programResultDescriptionId = programResults[0]?.resultDescription as
+            | string
+            | undefined;
+        const programResultDescription = programResultDescriptions[0]?.id as string | undefined;
+
+        expect(programResultDescriptionId).toBe(programResultDescription);
+        expect(programResultDescriptionId && ids.has(programResultDescriptionId)).toBe(true);
+
+        const nestedAssociations = subject.association as UnknownRecord[];
+        for (const assoc of nestedAssociations) {
+            const sourceId = assoc.sourceId as string | undefined;
+            const targetId = assoc.targetId as string | undefined;
+
+            expect(sourceId && ids.has(sourceId)).toBe(true);
+            expect(targetId && ids.has(targetId)).toBe(true);
+        }
+
+        const gpaRecord = nested.find(vc => {
+            const vcSubject = vc.credentialSubject as UnknownRecord | undefined;
+            const achievement = vcSubject?.achievement as UnknownRecord | undefined;
+            return achievement?.achievementType === 'BachelorDegree';
+        }) as UnknownRecord | undefined;
+        const gpaSubject = gpaRecord?.credentialSubject as UnknownRecord | undefined;
+        const gpaResults = Array.isArray(gpaSubject?.result)
+            ? (gpaSubject?.result as UnknownArrayRecord[])
+            : [];
+        const gpaResultDescriptionId = gpaResults[0]?.resultDescription as string | undefined;
+
+        expect(gpaResultDescriptionId && ids.has(gpaResultDescriptionId)).toBe(true);
+    });
+
+    it('preserves original UUIDs when freshIds is false', () => {
+        const fixture = getFixture('obv3/minimal-badge');
+        const prepared = prepareFixture(fixture, { issuerDid, freshIds: false });
+
+        expect(prepared.id).toBe(fixture.credential.id);
+    });
+
+    it('sets validFrom to now when not specified', () => {
+        const before = new Date().toISOString();
+        const fixture = getFixture('vc-v2/basic');
+        const prepared = prepareFixture(fixture, { issuerDid });
+        const after = new Date().toISOString();
+
+        expect(prepared.validFrom).toBeDefined();
+        expect(prepared.validFrom! >= before).toBe(true);
+        expect(prepared.validFrom! <= after).toBe(true);
+    });
+
+    it('uses provided validFrom date', () => {
+        const fixture = getFixture('vc-v2/basic');
+        const customDate = '2030-01-01T00:00:00Z';
+        const prepared = prepareFixture(fixture, { issuerDid, validFrom: customDate });
+
+        expect(prepared.validFrom).toBe(customDate);
+    });
+
+    it('does not mutate the original fixture', () => {
+        const fixture = getFixture('vc-v2/basic');
+        const originalId = fixture.credential.id;
+
+        prepareFixture(fixture, { issuerDid });
+
+        expect(fixture.credential.id).toBe(originalId);
+    });
+
+    it('prepared credential still passes base validator', () => {
+        const fixture = getFixture('obv3/full-badge');
+        const prepared = prepareFixture(fixture, { issuerDid, subjectDid });
+        const result = UnsignedVCValidator.safeParse(prepared);
+
+        expect(result.success).toBe(true);
+    });
+
+    it('handles multiple credentialSubjects', () => {
+        const fixture = getFixture('vc-v2/multiple-subjects');
+        const prepared = prepareFixture(fixture, { issuerDid, subjectDid });
+        const subjects = prepared.credentialSubject as Record<string, unknown>[];
+
+        expect(Array.isArray(subjects)).toBe(true);
+        expect(subjects.every(s => s.id === subjectDid)).toBe(true);
+    });
+});
+
+describe('prepareFixtureById', () => {
+    it('works as a shorthand for getFixture + prepareFixture', () => {
+        const issuerDid = 'did:key:z6MkShorthand';
+        const prepared = prepareFixtureById('vc-v2/basic', { issuerDid });
+
+        expect(prepared.issuer).toBe(issuerDid);
+        expect(prepared.type).toContain('VerifiableCredential');
+    });
+
+    it('throws for unknown fixture ID', () => {
+        expect(() =>
+            prepareFixtureById('nonexistent/fixture', { issuerDid: 'did:key:z6MkTest' })
+        ).toThrow('not found');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// resetRegistry
+// ---------------------------------------------------------------------------
+
+describe('resetRegistry', () => {
+    it('clears and lazily re-populates the registry', () => {
+        const countBefore = getAllFixtures().length;
+
+        expect(countBefore).toBeGreaterThan(0);
+
+        resetRegistry();
+
+        // After reset, getAllFixtures() lazily re-initializes from ALL_FIXTURES
+        expect(getAllFixtures().length).toBe(countBefore);
+    });
+});

package/src/fixtures/boost/basic.ts

@@ -0,0 +1,50 @@
+import { UnsignedAchievementCredentialValidator } from '@learncard/types';
+
+import type { CredentialFixture } from '../../types';
+
+export const boostBasic: CredentialFixture = {
+    id: 'boost/basic',
+    name: 'Basic LearnCard Boost',
+    description:
+        'LearnCard BoostCredential — an OBv3-compatible badge with the BoostCredential extension context',
+    spec: 'obv3',
+    profile: 'boost',
+    features: ['display'],
+    source: 'synthetic',
+    signed: false,
+    validity: 'valid',
+    validator: UnsignedAchievementCredentialValidator,
+    tags: ['learncard', 'boost'],
+
+    credential: {
+        '@context': [
+            'https://www.w3.org/ns/credentials/v2',
+            'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
+            'https://ctx.learncard.com/boosts/1.0.3.json',
+        ],
+        id: 'urn:uuid:b8c9d0e1-0008-4000-8000-000000000001',
+        type: ['VerifiableCredential', 'OpenBadgeCredential', 'BoostCredential'],
+        name: 'Community Contributor',
+        issuer: { id: 'did:example:orgABC' },
+        validFrom: '2024-07-01T00:00:00Z',
+        credentialSubject: {
+            id: 'did:example:member42',
+            type: ['AchievementSubject'],
+            achievement: {
+                id: 'urn:uuid:b8c9d0e1-0008-4000-8000-000000000002',
+                type: ['Achievement'],
+                achievementType: 'Badge',
+                name: 'Community Contributor',
+                description: 'Recognized for making meaningful contributions to the community.',
+                image: 'https://example.com/badges/contributor.png',
+                criteria: {
+                    narrative: 'Contribute to at least 3 community projects.',
+                },
+            },
+        },
+        display: {
+            backgroundColor: '#2563EB',
+            backgroundImage: '',
+        },
+    },
+};

package/src/fixtures/boost/boost-id.ts

@@ -0,0 +1,59 @@
+import { UnsignedAchievementCredentialValidator } from '@learncard/types';
+
+import type { CredentialFixture } from '../../types';
+
+export const boostId: CredentialFixture = {
+    id: 'boost/boost-id',
+    name: 'LearnCard Boost ID',
+    description:
+        'LearnCard BoostID credential — an identity-style credential with custom display, used for membership cards and IDs',
+    spec: 'obv3',
+    profile: 'boost-id',
+    features: ['display', 'image'],
+    source: 'synthetic',
+    signed: false,
+    validity: 'valid',
+    validator: UnsignedAchievementCredentialValidator,
+    tags: ['learncard', 'boost', 'id'],
+
+    credential: {
+        '@context': [
+            'https://www.w3.org/ns/credentials/v2',
+            'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
+            'https://ctx.learncard.com/boosts/1.0.3.json',
+            'https://ctx.learncard.com/boostIDs/1.0.0.json',
+        ],
+        id: 'urn:uuid:c9d0e1f2-0009-4000-8000-000000000001',
+        type: ['VerifiableCredential', 'OpenBadgeCredential', 'BoostCredential', 'BoostID'],
+        name: 'Scouts Troop 42 Member ID',
+        issuer: { id: 'did:example:troopLeader' },
+        validFrom: '2024-09-01T00:00:00Z',
+        validUntil: '2025-09-01T00:00:00Z',
+        image: 'https://example.com/troop42/badge.png',
+        credentialSubject: {
+            id: 'did:example:scout123',
+            type: ['AchievementSubject'],
+            achievement: {
+                id: 'urn:uuid:c9d0e1f2-0009-4000-8000-000000000002',
+                type: ['Achievement'],
+                achievementType: 'Membership',
+                name: 'Troop 42 Membership',
+                description: 'Active member of Scouts Troop 42.',
+                image: '',
+                criteria: {
+                    narrative: 'Registered and active in the current program year.',
+                },
+            },
+        },
+        display: {
+            backgroundColor: '#16A34A',
+            backgroundImage: '',
+        },
+        boostID: {
+            fontColor: '#FFFFFF',
+            accentColor: '#15803D',
+            idBackgroundColor: '#16A34A',
+            repeatIdBackgroundImage: false,
+        },
+    },
+};

package/src/fixtures/boost/community-award.ts

@@ -0,0 +1,96 @@
+import type { CredentialFixture } from '../../types';
+
+export const boostCommunityAward: CredentialFixture = {
+    id: 'boost/community-award',
+    name: 'Community Leadership Award Boost',
+    description:
+        'A LearnCard Boost credential recognizing community leadership contributions, with skills and evidence. Represents real-world community recognition use cases on the LearnCard network.',
+    spec: 'obv3',
+    profile: 'boost',
+    features: ['evidence', 'skills', 'image'],
+    source: 'synthetic',
+    signed: false,
+    validity: 'valid',
+    tags: ['boost', 'community', 'leadership', 'recognition', 'learncard'],
+
+    credential: {
+        '@context': [
+            'https://www.w3.org/ns/credentials/v2',
+            'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
+        ],
+        id: 'urn:uuid:d8c4f2a1-3b67-4e89-a1d0-5f9e7c2b8a43',
+        type: ['VerifiableCredential', 'OpenBadgeCredential', 'BoostCredential'],
+        name: 'Community Leadership Award',
+        description:
+            'Awarded for outstanding community leadership, demonstrating commitment to mentoring, volunteer coordination, and community engagement over the past year.',
+        image: {
+            id: 'https://network.learncard.com/boosts/community-leadership/badge.png',
+            type: 'Image',
+            caption: 'Community Leadership Award badge',
+        },
+        credentialSubject: {
+            id: 'did:example:community-leader-042',
+            type: ['AchievementSubject'],
+            achievement: {
+                id: 'https://network.learncard.com/boosts/community-leadership',
+                type: ['Achievement'],
+                achievementType: 'Badge',
+                name: 'Community Leadership Award',
+                description:
+                    'Recognizes individuals who have made exceptional contributions to their community through leadership, mentoring, and volunteer coordination. Recipients demonstrate initiative, empathy, and the ability to mobilize others toward shared goals.',
+                criteria: {
+                    id: 'https://network.learncard.com/boosts/community-leadership/criteria',
+                    narrative:
+                        'Nominated by at least 3 community members and approved by the Community Advisory Board. Must demonstrate: (1) Active mentoring of at least 5 community members, (2) Organization of at least 2 community events, (3) Consistent participation over at least 6 months.',
+                },
+                image: {
+                    id: 'https://network.learncard.com/boosts/community-leadership/badge.png',
+                    type: 'Image',
+                    caption: 'Community Leadership Award badge',
+                },
+                creator: {
+                    id: 'did:web:network.learncard.com:organizations:community-hub',
+                    type: ['Profile'],
+                    name: 'LearnCard Community Hub',
+                    url: 'https://network.learncard.com/organizations/community-hub',
+                    description: 'The LearnCard Community Hub connects learners, educators, and community leaders.',
+                },
+                tag: [
+                    'leadership',
+                    'mentoring',
+                    'community-engagement',
+                    'volunteer',
+                    'collaboration',
+                    'communication',
+                    'project-management',
+                ],
+            },
+        },
+        issuer: {
+            id: 'did:web:network.learncard.com:organizations:community-hub',
+            type: ['Profile'],
+            name: 'LearnCard Community Hub',
+            url: 'https://network.learncard.com/organizations/community-hub',
+            image: {
+                id: 'https://network.learncard.com/organizations/community-hub/logo.png',
+                type: 'Image',
+                caption: 'LearnCard Community Hub logo',
+            },
+        },
+        validFrom: '2025-03-01T00:00:00Z',
+        evidence: [
+            {
+                id: 'https://network.learncard.com/evidence/community-leader-042/mentoring-log',
+                type: ['Evidence'],
+                narrative:
+                    'Mentored 8 new community members over 9 months, providing weekly 1-on-1 sessions covering career development, technical skills, and networking strategies.',
+            },
+            {
+                id: 'https://network.learncard.com/evidence/community-leader-042/events',
+                type: ['Evidence'],
+                narrative:
+                    'Organized and led 4 community events: two technical workshops (Introduction to Web3, Building with Verifiable Credentials), one networking mixer, and one community hackathon with 45 participants.',
+            },
+        ],
+    },
+};