@learncard/credential-library 1.0.10 → 1.0.11

package/src/fixtures/vc-v2/with-evidence.ts

@@ -0,0 +1,50 @@
+import { UnsignedVCValidator } from '@learncard/types';
+
+import type { CredentialFixture } from '../../types';
+
+export const vcV2WithEvidence: CredentialFixture = {
+    id: 'vc-v2/with-evidence',
+    name: 'VC v2 with Evidence',
+    description: 'W3C VCDM v2 credential with evidence array documenting supporting artifacts',
+    spec: 'vc-v2',
+    profile: 'generic',
+    features: ['evidence'],
+    source: 'synthetic',
+    signed: false,
+    validity: 'valid',
+    validator: UnsignedVCValidator,
+
+    credential: {
+        '@context': [
+            'https://www.w3.org/ns/credentials/v2',
+            'https://www.w3.org/ns/credentials/examples/v2',
+        ],
+        id: 'urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+        type: ['VerifiableCredential'],
+        issuer: {
+            id: 'did:example:issuer123',
+            name: 'Example University',
+        },
+        validFrom: '2023-09-01T00:00:00Z',
+        credentialSubject: {
+            id: 'did:example:student789',
+            degree: {
+                type: 'MasterDegree',
+                name: 'Master of Science in Data Engineering',
+            },
+        },
+        evidence: [
+            {
+                type: ['Evidence', 'DocumentVerification'],
+                name: 'Transcript Review',
+                description: 'Official transcript reviewed and verified by registrar office.',
+            },
+            {
+                type: ['Evidence', 'ThesisDefense'],
+                name: 'Thesis Defense',
+                narrative:
+                    'Student successfully defended thesis titled "Scalable Data Pipelines" on 2023-06-20.',
+            },
+        ],
+    },
+};

package/src/index.ts

@@ -0,0 +1,45 @@
+// Types
+export type {
+    CredentialSpec,
+    CredentialProfile,
+    CredentialFeature,
+    FixtureSource,
+    FixtureValidity,
+    CredentialFixture,
+    FixtureFilter,
+    InvalidCredential,
+} from './types';
+
+export {
+    CREDENTIAL_SPECS,
+    CREDENTIAL_PROFILES,
+    CREDENTIAL_FEATURES,
+    FIXTURE_SOURCES,
+    FIXTURE_VALIDITIES,
+} from './types';
+
+// Registry (query API + mutation)
+export {
+    registerFixture,
+    registerFixtures,
+    resetRegistry,
+    getAllFixtures,
+    getFixture,
+    findFixture,
+    getFixtures,
+    getUnsignedFixtures,
+    getSignedFixtures,
+    getValidFixtures,
+    getInvalidFixtures,
+    getStats,
+} from './registry';
+
+export type { RegistryStats } from './registry';
+
+// Prepare — bridge fixtures to wallet issuance
+export { prepareFixture, prepareFixtureById } from './prepare';
+
+export type { PrepareOptions } from './prepare';
+
+// Fixtures — importing this module registers all fixtures in the registry
+export * from './fixtures';

package/src/prepare.ts

@@ -0,0 +1,212 @@
+import type { UnsignedVC } from '@learncard/types';
+
+import type { CredentialFixture } from './types';
+import { getFixture } from './registry';
+
+// ---------------------------------------------------------------------------
+// PrepareOptions — what to inject into a fixture for real issuance
+// ---------------------------------------------------------------------------
+
+export interface PrepareOptions {
+    /** Issuer DID — e.g. from wallet.id.did() */
+    issuerDid: string;
+
+    /** Recipient DID — who the credential is being issued to */
+    subjectDid?: string;
+
+    /** Override validFrom date (defaults to now) */
+    validFrom?: string;
+
+    /** Override validUntil / expirationDate */
+    validUntil?: string;
+
+    /** Generate fresh UUIDs for id fields (defaults to true) */
+    freshIds?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Deep clone + patch helpers
+// ---------------------------------------------------------------------------
+
+const generateUuid = (): string => {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+
+    throw new Error(
+        'crypto.randomUUID is not available in this environment. ' +
+            'Please use a modern runtime with Web Crypto API support for secure UUID generation.'
+    );
+};
+
+const patchIds = (
+    obj: Record<string, unknown>,
+    idMap: Map<string, string>
+): Record<string, unknown> => {
+    const result: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === 'id' && typeof value === 'string' && value.startsWith('urn:uuid:')) {
+            // Reuse the same replacement for every occurrence of the same source id so
+            // internal CLR references stay aligned after regeneration.
+            const patchedId = idMap.get(value) ?? `urn:uuid:${generateUuid()}`;
+            if (!idMap.has(value)) {
+                idMap.set(value, patchedId);
+            }
+            result[key] = patchedId;
+        } else if (Array.isArray(value)) {
+            result[key] = value.map(item =>
+                item && typeof item === 'object' && !Array.isArray(item)
+                    ? patchIds(item as Record<string, unknown>, idMap)
+                    : item
+            );
+        } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            result[key] = patchIds(value as Record<string, unknown>, idMap);
+        } else {
+            result[key] = value;
+        }
+    }
+
+    return result;
+};
+
+const remapUuidReferences = (value: unknown, idMap: Map<string, string>): unknown => {
+    if (typeof value === 'string') {
+        // Rewrite explicit references that still point at the original ids.
+        return idMap.get(value) ?? value;
+    }
+
+    if (Array.isArray(value)) {
+        return value.map(item => remapUuidReferences(item, idMap));
+    }
+
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value as Record<string, unknown>).map(([key, nestedValue]) => [
+                key,
+                remapUuidReferences(nestedValue, idMap),
+            ])
+        );
+    }
+
+    return value;
+};
+
+const patchIssuer = (issuer: unknown, issuerDid: string): string | Record<string, unknown> => {
+    if (typeof issuer === 'string') {
+        return issuerDid;
+    }
+
+    if (issuer && typeof issuer === 'object') {
+        return { ...(issuer as Record<string, unknown>), id: issuerDid };
+    }
+
+    return issuerDid;
+};
+
+const patchSubject = (subject: unknown, subjectDid: string): unknown => {
+    if (Array.isArray(subject)) {
+        return subject.map(s => patchSubject(s, subjectDid));
+    }
+
+    if (subject && typeof subject === 'object') {
+        return { ...(subject as Record<string, unknown>), id: subjectDid };
+    }
+
+    return subject;
+};
+
+// ---------------------------------------------------------------------------
+// prepareFixture — make a fixture ready for wallet.invoke.issueCredential()
+// ---------------------------------------------------------------------------
+
+/**
+ * Takes a fixture's credential and returns a fresh unsigned VC with real DIDs,
+ * current timestamps, and fresh UUIDs — ready to pass to
+ * `wallet.invoke.issueCredential()`.
+ *
+ * @example
+ * ```typescript
+ * import { getFixture, prepareFixture } from '@learncard/credential-library';
+ *
+ * const fixture = getFixture('obv3/full-badge');
+ * const unsigned = prepareFixture(fixture, {
+ *     issuerDid: wallet.id.did(),
+ *     subjectDid: recipientDid,
+ * });
+ * const signed = await wallet.invoke.issueCredential(unsigned);
+ * await wallet.store.LearnCloud.uploadEncrypted(signed);
+ * ```
+ */
+export const prepareFixture = (fixture: CredentialFixture, options: PrepareOptions): UnsignedVC => {
+    const { issuerDid, subjectDid, validFrom, validUntil, freshIds = true } = options;
+
+    // Deep clone
+    let credential = JSON.parse(JSON.stringify(fixture.credential)) as Record<string, unknown>;
+
+    // Patch UUIDs
+    if (freshIds) {
+        const idMap = new Map<string, string>();
+        // First replace generated ids, then walk the credential again to update
+        // any references that target those ids.
+        credential = patchIds(credential, idMap);
+        credential = remapUuidReferences(credential, idMap) as Record<string, unknown>;
+    }
+
+    // Patch issuer
+    credential.issuer = patchIssuer(credential.issuer, issuerDid);
+
+    // Patch subject DID
+    if (subjectDid && credential.credentialSubject) {
+        credential.credentialSubject = patchSubject(credential.credentialSubject, subjectDid);
+    }
+
+    // Patch dates
+    const now = new Date().toISOString();
+
+    if (credential.validFrom !== undefined || credential.issuanceDate !== undefined) {
+        if (credential.validFrom !== undefined) {
+            credential.validFrom = validFrom ?? now;
+        }
+
+        if (credential.issuanceDate !== undefined) {
+            credential.issuanceDate = validFrom ?? now;
+        }
+    } else {
+        // Default to validFrom for v2-style credentials
+        credential.validFrom = validFrom ?? now;
+    }
+
+    if (validUntil !== undefined) {
+        if (credential.validUntil !== undefined) {
+            credential.validUntil = validUntil;
+        } else if (credential.expirationDate !== undefined) {
+            credential.expirationDate = validUntil;
+        } else {
+            credential.validUntil = validUntil;
+        }
+    }
+
+    return credential as UnsignedVC;
+};
+
+// ---------------------------------------------------------------------------
+// prepareFixtureById — convenience wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Shorthand that combines getFixture + prepareFixture.
+ *
+ * @example
+ * ```typescript
+ * import { prepareFixtureById } from '@learncard/credential-library';
+ *
+ * const unsigned = prepareFixtureById('boost/basic', {
+ *     issuerDid: wallet.id.did(),
+ *     subjectDid: recipientDid,
+ * });
+ * const signed = await wallet.invoke.issueCredential(unsigned);
+ * ```
+ */
+export const prepareFixtureById = (fixtureId: string, options: PrepareOptions): UnsignedVC =>
+    prepareFixture(getFixture(fixtureId), options);

package/src/registry.ts

@@ -0,0 +1,209 @@
+import type { UnsignedVC, VC } from '@learncard/types';
+
+import type { CredentialFixture, FixtureFilter } from './types';
+import { ALL_FIXTURES } from './fixtures';
+
+// ---------------------------------------------------------------------------
+// Internal store — fixtures register themselves here via `registerFixture`
+// ---------------------------------------------------------------------------
+
+const fixtures: CredentialFixture[] = [];
+
+const fixtureIndex = new Map<string, CredentialFixture>();
+
+// ---------------------------------------------------------------------------
+// Lazy initialization — populate the registry on first query so consumers
+// don't need to rely on import side effects (keeps `sideEffects: false`
+// truthful). The ALL_FIXTURES import above is pure data — no mutation
+// happens until ensureInitialized() is called.
+// ---------------------------------------------------------------------------
+
+let initialized = false;
+
+const ensureInitialized = (): void => {
+    if (initialized) return;
+
+    initialized = true;
+
+    for (const fixture of ALL_FIXTURES) {
+        if (!fixtureIndex.has(fixture.id)) {
+            fixtures.push(fixture);
+            fixtureIndex.set(fixture.id, fixture);
+        }
+    }
+};
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+export const registerFixture = <T extends UnsignedVC | VC>(fixture: CredentialFixture<T>): void => {
+    if (fixtureIndex.has(fixture.id)) {
+        throw new Error(`Duplicate fixture ID: "${fixture.id}". Each fixture must have a unique id.`);
+    }
+
+    fixtures.push(fixture as CredentialFixture);
+    fixtureIndex.set(fixture.id, fixture as CredentialFixture);
+};
+
+export const registerFixtures = (batch: CredentialFixture[]): void => {
+    for (const fixture of batch) {
+        registerFixture(fixture);
+    }
+};
+
+// ---------------------------------------------------------------------------
+// Reset — for test isolation (vitest watch, jest --watch)
+// ---------------------------------------------------------------------------
+
+export const resetRegistry = (): void => {
+    fixtures.length = 0;
+    fixtureIndex.clear();
+    initialized = false;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const toArray = <T>(value: T | T[]): T[] => (Array.isArray(value) ? value : [value]);
+
+const matchesFilter = (fixture: CredentialFixture, filter: FixtureFilter): boolean => {
+    if (filter.spec !== undefined) {
+        const specs = toArray(filter.spec);
+
+        if (!specs.includes(fixture.spec)) return false;
+    }
+
+    if (filter.profile !== undefined) {
+        const profiles = toArray(filter.profile);
+
+        if (!profiles.includes(fixture.profile)) return false;
+    }
+
+    if (filter.features !== undefined) {
+        for (const feat of filter.features) {
+            if (!fixture.features.includes(feat)) return false;
+        }
+    }
+
+    if (filter.featuresAny !== undefined) {
+        const hasAny = filter.featuresAny.some(feat => fixture.features.includes(feat));
+
+        if (!hasAny) return false;
+    }
+
+    if (filter.signed !== undefined) {
+        if (fixture.signed !== filter.signed) return false;
+    }
+
+    if (filter.validity !== undefined) {
+        const validities = toArray(filter.validity);
+
+        if (!validities.includes(fixture.validity)) return false;
+    }
+
+    if (filter.source !== undefined) {
+        const sources = toArray(filter.source);
+
+        if (!sources.includes(fixture.source)) return false;
+    }
+
+    if (filter.tags !== undefined) {
+        for (const tag of filter.tags) {
+            if (!fixture.tags?.includes(tag)) return false;
+        }
+    }
+
+    return true;
+};
+
+// ---------------------------------------------------------------------------
+// Public query API
+// ---------------------------------------------------------------------------
+
+export const getAllFixtures = (): readonly CredentialFixture[] => {
+    ensureInitialized();
+
+    return fixtures;
+};
+
+export const getFixture = (id: string): CredentialFixture => {
+    ensureInitialized();
+
+    const fixture = fixtureIndex.get(id);
+
+    if (!fixture) {
+        throw new Error(
+            `Fixture "${id}" not found. Available: ${[...fixtureIndex.keys()].join(', ')}`
+        );
+    }
+
+    return fixture;
+};
+
+export const findFixture = (id: string): CredentialFixture | undefined => {
+    ensureInitialized();
+
+    return fixtureIndex.get(id);
+};
+
+export const getFixtures = (filter: FixtureFilter): CredentialFixture[] => {
+    ensureInitialized();
+
+    return fixtures.filter(f => matchesFilter(f, filter));
+};
+
+export const getUnsignedFixtures = (
+    filter?: FixtureFilter
+): CredentialFixture<UnsignedVC>[] =>
+    getFixtures({ ...filter, signed: false }) as CredentialFixture<UnsignedVC>[];
+
+export const getSignedFixtures = (filter?: FixtureFilter): CredentialFixture<VC>[] =>
+    getFixtures({ ...filter, signed: true }) as CredentialFixture<VC>[];
+
+export const getValidFixtures = (filter?: FixtureFilter): CredentialFixture[] =>
+    getFixtures({ ...filter, validity: 'valid' });
+
+export const getInvalidFixtures = (filter?: FixtureFilter): CredentialFixture[] =>
+    getFixtures({ ...filter, validity: ['invalid', 'tampered'] });
+
+// ---------------------------------------------------------------------------
+// Stats — useful for debugging / README generation
+// ---------------------------------------------------------------------------
+
+export interface RegistryStats {
+    total: number;
+    bySpec: Record<string, number>;
+    byProfile: Record<string, number>;
+    byValidity: Record<string, number>;
+    signed: number;
+    unsigned: number;
+}
+
+export const getStats = (): RegistryStats => {
+    ensureInitialized();
+
+    const stats: RegistryStats = {
+        total: fixtures.length,
+        bySpec: {},
+        byProfile: {},
+        byValidity: {},
+        signed: 0,
+        unsigned: 0,
+    };
+
+    for (const f of fixtures) {
+        stats.bySpec[f.spec] = (stats.bySpec[f.spec] ?? 0) + 1;
+        stats.byProfile[f.profile] = (stats.byProfile[f.profile] ?? 0) + 1;
+        stats.byValidity[f.validity] = (stats.byValidity[f.validity] ?? 0) + 1;
+
+        if (f.signed) {
+            stats.signed++;
+        } else {
+            stats.unsigned++;
+        }
+    }
+
+    return stats;
+};

package/src/types.ts

@@ -0,0 +1,164 @@
+import type { z } from 'zod';
+import type { UnsignedVC, VC } from '@learncard/types';
+
+// ---------------------------------------------------------------------------
+// Credential Spec — which standard does this credential conform to?
+// ---------------------------------------------------------------------------
+
+export const CREDENTIAL_SPECS = [
+    'vc-v1',
+    'vc-v2',
+    'obv3',
+    'clr-v2',
+    'europass',
+    'custom',
+] as const;
+
+export type CredentialSpec = (typeof CREDENTIAL_SPECS)[number];
+
+// ---------------------------------------------------------------------------
+// Credential Profile — what kind of credential is it?
+// ---------------------------------------------------------------------------
+
+export const CREDENTIAL_PROFILES = [
+    'badge',
+    'diploma',
+    'certificate',
+    'id',
+    'membership',
+    'license',
+    'micro-credential',
+    'course',
+    'degree',
+    'boost',
+    'boost-id',
+    'delegate',
+    'endorsement',
+    'learner-record',
+    'generic',
+] as const;
+
+export type CredentialProfile = (typeof CREDENTIAL_PROFILES)[number];
+
+// ---------------------------------------------------------------------------
+// Credential Feature — what optional VC features does this fixture exercise?
+// ---------------------------------------------------------------------------
+
+export const CREDENTIAL_FEATURES = [
+    'evidence',
+    'alignment',
+    'endorsement',
+    'expiration',
+    'status',
+    'multiple-subjects',
+    'multiple-proofs',
+    'refresh-service',
+    'terms-of-use',
+    'credential-schema',
+    'image',
+    'results',
+    'source',
+    'skills',
+    'display',
+    'attachments',
+    'associations',
+    'nested-credentials',
+] as const;
+
+export type CredentialFeature = (typeof CREDENTIAL_FEATURES)[number];
+
+// ---------------------------------------------------------------------------
+// Fixture Source — where did this credential come from?
+// ---------------------------------------------------------------------------
+
+export const FIXTURE_SOURCES = [
+    'spec-example',
+    'plugfest',
+    'real-world',
+    'synthetic',
+] as const;
+
+export type FixtureSource = (typeof FIXTURE_SOURCES)[number];
+
+// ---------------------------------------------------------------------------
+// Fixture Validity — is this intentionally valid or invalid?
+// ---------------------------------------------------------------------------
+
+export const FIXTURE_VALIDITIES = ['valid', 'invalid', 'tampered'] as const;
+
+export type FixtureValidity = (typeof FIXTURE_VALIDITIES)[number];
+
+// Used for intentionally malformed fixtures that violate the UnsignedVC type
+export type InvalidCredential = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// CredentialFixture — the core type wrapping a credential with metadata
+// ---------------------------------------------------------------------------
+
+export interface CredentialFixture<T extends UnsignedVC | VC = UnsignedVC> {
+    /** Unique fixture ID, e.g. 'obv3/minimal-badge' */
+    id: string;
+
+    /** Human-readable name */
+    name: string;
+
+    /** What this fixture tests or demonstrates */
+    description: string;
+
+    /** Which spec it conforms to */
+    spec: CredentialSpec;
+
+    /** What kind of credential this represents */
+    profile: CredentialProfile;
+
+    /** Which optional VC features this fixture exercises */
+    features: CredentialFeature[];
+
+    /** Where this credential came from */
+    source: FixtureSource;
+
+    /** Whether this is a signed (VC with proof) or unsigned credential */
+    signed: boolean;
+
+    /** Whether this fixture is intentionally valid, invalid, or tampered */
+    validity: FixtureValidity;
+
+    /** The actual credential JSON */
+    credential: T;
+
+    /** Zod validator this credential should pass (if valid) or fail (if invalid) */
+    validator?: z.ZodType;
+
+    /** Additional free-form tags for ad-hoc filtering */
+    tags?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Filter — used to query the registry
+// ---------------------------------------------------------------------------
+
+export interface FixtureFilter {
+    /** Match any of the given specs */
+    spec?: CredentialSpec | CredentialSpec[];
+
+    /** Match any of the given profiles */
+    profile?: CredentialProfile | CredentialProfile[];
+
+    /** Must have ALL of these features */
+    features?: CredentialFeature[];
+
+    /** Must have ANY of these features */
+    featuresAny?: CredentialFeature[];
+
+    /** Filter by signed status */
+    signed?: boolean;
+
+    /** Filter by validity */
+    validity?: FixtureValidity | FixtureValidity[];
+
+    /** Match any of the given sources */
+    source?: FixtureSource | FixtureSource[];
+
+    /** Must have ALL of these tags */
+    tags?: string[];
+}