@learncard/credential-library 1.0.17 → 2.0.1

package/src/fixtures/index.ts

@@ -1,4 +1,4 @@
-import type { CredentialFixture } from '../types';
+import type { LibraryFixture } from '../types';
 
 // VC v1
 import { vcV1Basic } from './vc-v1/basic';
@@ -56,12 +56,16 @@ import { vcV2LicenseCredential } from './vc-v2/license-credential';
 import { clrGreatPlainsFull } from './clr/great-plains-full';
 import { clrWestbridgeFull } from './clr/westbridge-full';
 import { clrCompetencyAligned } from './clr/competency-aligned';
+import { clrDemoIsdDiplomaAssessments } from './clr/demo-isd-diploma-assessments';
+
+// SD-JWT VC
+import { sdJwtVcCourseCompletion } from './sd-jwt-vc/course-completion';
 
 // ---------------------------------------------------------------------------
 // All fixtures — collected for auto-registration
 // ---------------------------------------------------------------------------
 
-export const ALL_FIXTURES: CredentialFixture[] = [
+export const ALL_FIXTURES: LibraryFixture[] = [
     // VC v1
     vcV1Basic,
     vcV1WithStatus,
@@ -116,6 +120,10 @@ export const ALL_FIXTURES: CredentialFixture[] = [
     clrGreatPlainsFull,
     clrWestbridgeFull,
     clrCompetencyAligned,
+    clrDemoIsdDiplomaAssessments,
+
+    // SD-JWT VC
+    sdJwtVcCourseCompletion,
 ];
 
 // Re-export individual fixtures for direct import
@@ -159,4 +167,6 @@ export {
     clrGreatPlainsFull,
     clrWestbridgeFull,
     clrCompetencyAligned,
+    clrDemoIsdDiplomaAssessments,
+    sdJwtVcCourseCompletion,
 };

package/src/fixtures/sd-jwt-vc/course-completion.ts

@@ -0,0 +1,27 @@
+import type { SdJwtVcFixture } from '../../types';
+
+export const sdJwtVcCourseCompletion: SdJwtVcFixture = {
+    kind: 'sd-jwt-vc',
+    id: 'sd-jwt-vc/course-completion',
+    name: 'SD-JWT VC Course Completion',
+    description:
+        'Synthetic holder-bound course completion credential for Digital Credentials API testing',
+    spec: 'sd-jwt-vc',
+    profile: 'course',
+    features: ['skills', 'selective-disclosure', 'holder-binding'],
+    source: 'synthetic',
+    signed: false,
+    validity: 'valid',
+    tags: ['sd-jwt', 'dcql', 'android-digital-credentials', 'holder-bound'],
+    template: {
+        format: 'dc+sd-jwt',
+        vct: 'https://credentials.learncard.com/vct/course-completion',
+        claims: {
+            learner_name: 'Ada Lovelace',
+            course_name: 'Introduction to Verifiable Credentials',
+            completion_date: '2026-08-25',
+            skills: ['Digital Identity', 'Verifiable Credentials'],
+        },
+        selectivelyDisclosable: ['learner_name', 'course_name', 'completion_date', 'skills'],
+    },
+};

package/src/index.ts

@@ -3,9 +3,14 @@ export type {
     CredentialSpec,
     CredentialProfile,
     CredentialFeature,
+    FixtureKind,
     FixtureSource,
     FixtureValidity,
+    BaseCredentialFixture,
     CredentialFixture,
+    SdJwtVcTemplate,
+    SdJwtVcFixture,
+    LibraryFixture,
     FixtureFilter,
     InvalidCredential,
 } from './types';
@@ -14,8 +19,11 @@ export {
     CREDENTIAL_SPECS,
     CREDENTIAL_PROFILES,
     CREDENTIAL_FEATURES,
+    FIXTURE_KINDS,
     FIXTURE_SOURCES,
     FIXTURE_VALIDITIES,
+    isCredentialFixture,
+    isSdJwtVcFixture,
 } from './types';
 
 // Registry (query API + mutation)
@@ -41,5 +49,14 @@ export { prepareFixture, prepareFixtureById } from './prepare';
 
 export type { PrepareOptions } from './prepare';
 
+// SD-JWT VC materialization
+export { materializeSdJwtVcFixture } from './materialize-sd-jwt-vc';
+
+export type {
+    SdJwtVcSigner,
+    MaterializeSdJwtVcOptions,
+    MaterializedSdJwtVcFixture,
+} from './materialize-sd-jwt-vc';
+
 // Fixtures — importing this module registers all fixtures in the registry
 export * from './fixtures';

package/src/materialize-sd-jwt-vc.ts

@@ -0,0 +1,159 @@
+import { SDJwtVcInstance } from '@sd-jwt/sd-jwt-vc';
+import { randomSalt, sha256Hasher } from '@learncard/sd-jwt-vc-plugin';
+import type { StoredCredentialEnvelope } from '@learncard/types';
+
+import type { SdJwtVcFixture } from './types';
+
+export type SdJwtVcSigner = (signingInput: string) => Promise<string>;
+
+export interface MaterializeSdJwtVcOptions {
+    issuerDid: string;
+    issuerKid: string;
+    issuerSigner: SdJwtVcSigner;
+    holderPublicJwk: Record<string, unknown>;
+    issuedAt?: number;
+}
+
+export interface MaterializedSdJwtVcFixture {
+    compact: string;
+    envelope: StoredCredentialEnvelope;
+    vct: string;
+}
+
+const RESERVED_CLAIMS = new Set(['iss', 'iat', 'nbf', 'exp', 'vct', 'cnf', '_sd', '_sd_alg']);
+
+type MaterializedPayload = Record<string, unknown> & {
+    iss: string;
+    iat: number;
+    vct: string;
+    cnf: { jwk: Record<string, unknown> };
+};
+
+const validateNonEmptyIssuerValue = (value: string, name: string): void => {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+};
+
+const isCanonicalEd25519PublicKey = (value: string): boolean => {
+    if (!/^[A-Za-z0-9_-]+$/.test(value)) return false;
+
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    let buffered = 0;
+    let bufferedBits = 0;
+    let decodedBytes = 0;
+
+    for (const character of value) {
+        buffered = (buffered << 6) | alphabet.indexOf(character);
+        bufferedBits += 6;
+
+        while (bufferedBits >= 8) {
+            bufferedBits -= 8;
+            decodedBytes += 1;
+            buffered &= (1 << bufferedBits) - 1;
+        }
+    }
+
+    return decodedBytes === 32 && buffered === 0;
+};
+
+const validateHolderPublicJwk = (holderPublicJwk: Record<string, unknown>): void => {
+    if (
+        holderPublicJwk &&
+        typeof holderPublicJwk === 'object' &&
+        Object.prototype.hasOwnProperty.call(holderPublicJwk, 'd')
+    ) {
+        throw new Error('holder key must be public and must not include private key material');
+    }
+
+    if (
+        !holderPublicJwk ||
+        typeof holderPublicJwk !== 'object' ||
+        holderPublicJwk.kty !== 'OKP' ||
+        holderPublicJwk.crv !== 'Ed25519' ||
+        typeof holderPublicJwk.x !== 'string' ||
+        !isCanonicalEd25519PublicKey(holderPublicJwk.x)
+    ) {
+        throw new Error(
+            'holderPublicJwk must be an Ed25519 OKP public JWK with a canonical 32-byte x'
+        );
+    }
+};
+
+const validateReservedClaims = (claims: Record<string, unknown>): void => {
+    for (const claim of Object.keys(claims)) {
+        if (RESERVED_CLAIMS.has(claim)) {
+            throw new Error(`SD-JWT fixture claims cannot declare reserved claim "${claim}"`);
+        }
+    }
+};
+
+const validateSelectivelyDisclosableClaims = (
+    claims: Record<string, unknown>,
+    selectivelyDisclosable: string[]
+): void => {
+    const claimKeys = new Set(Object.keys(claims));
+    const unknownClaims = selectivelyDisclosable.filter(claim => !claimKeys.has(claim));
+
+    if (unknownClaims.length > 0) {
+        throw new Error(
+            `SD-JWT fixture declares selectively disclosable claims that do not exist: ${unknownClaims.join(
+                ', '
+            )}`
+        );
+    }
+};
+
+/**
+ * Materializes an SD-JWT VC fixture with a caller-supplied issuer signer and holder key.
+ * The returned compact credential is canonical `dc+sd-jwt` and never includes a KB-JWT.
+ */
+export const materializeSdJwtVcFixture = async (
+    fixture: SdJwtVcFixture,
+    options: MaterializeSdJwtVcOptions
+): Promise<MaterializedSdJwtVcFixture> => {
+    validateNonEmptyIssuerValue(options.issuerDid, 'issuerDid');
+    validateNonEmptyIssuerValue(options.issuerKid, 'issuerKid');
+    validateHolderPublicJwk(options.holderPublicJwk);
+    validateReservedClaims(fixture.template.claims);
+    validateSelectivelyDisclosableClaims(
+        fixture.template.claims,
+        fixture.template.selectivelyDisclosable
+    );
+
+    const instance = new SDJwtVcInstance({
+        hasher: sha256Hasher,
+        hashAlg: 'sha-256',
+        saltGenerator: randomSalt,
+        signer: options.issuerSigner,
+        signAlg: 'EdDSA',
+    });
+
+    const payload: MaterializedPayload = {
+        ...fixture.template.claims,
+        iss: options.issuerDid,
+        iat: options.issuedAt ?? Math.floor(Date.now() / 1000),
+        vct: fixture.template.vct,
+        cnf: { jwk: options.holderPublicJwk },
+    };
+
+    const compact = await instance.issue<MaterializedPayload>(
+        payload,
+        // Fixture claims are intentionally dynamic, so TypeScript cannot statically enumerate
+        // their disclosure-frame keys. Runtime fixture validation and the SD-JWT library do.
+        { _sd: fixture.template.selectivelyDisclosable } as never,
+        {
+            header: {
+                typ: 'dc+sd-jwt',
+                alg: 'EdDSA',
+                kid: options.issuerKid,
+            },
+        }
+    );
+
+    return {
+        compact,
+        envelope: { format: 'dc+sd-jwt', data: compact },
+        vct: fixture.template.vct,
+    };
+};

package/src/prepare.ts

@@ -1,6 +1,6 @@
 import type { UnsignedVC } from '@learncard/types';
 
-import type { CredentialFixture } from './types';
+import { isSdJwtVcFixture, type LibraryFixture } from './types';
 import { getFixture } from './registry';
 
 // ---------------------------------------------------------------------------
@@ -138,7 +138,14 @@ const patchSubject = (subject: unknown, subjectDid: string): unknown => {
  * await wallet.store.LearnCloud.uploadEncrypted(signed);
  * ```
  */
-export const prepareFixture = (fixture: CredentialFixture, options: PrepareOptions): UnsignedVC => {
+export const prepareFixture = (fixture: LibraryFixture, options: PrepareOptions): UnsignedVC => {
+    if (isSdJwtVcFixture(fixture)) {
+        throw new Error(
+            `Fixture "${fixture.id}" is an SD-JWT VC template. ` +
+                'Use materializeSdJwtVcFixture() instead of prepareFixture().'
+        );
+    }
+
     const { issuerDid, subjectDid, validFrom, validUntil, freshIds = true } = options;
 
     // Deep clone

package/src/registry.ts

@@ -1,15 +1,66 @@
 import type { UnsignedVC, VC } from '@learncard/types';
 
-import type { CredentialFixture, FixtureFilter } from './types';
+import {
+    isCredentialFixture,
+    isSdJwtVcFixture,
+    type CredentialFixture,
+    type FixtureFilter,
+    type FixtureKind,
+    type LibraryFixture,
+    type SdJwtVcFixture,
+} from './types';
 import { ALL_FIXTURES } from './fixtures';
 
 // ---------------------------------------------------------------------------
 // Internal store — fixtures register themselves here via `registerFixture`
 // ---------------------------------------------------------------------------
 
-const fixtures: CredentialFixture[] = [];
+const fixtures: LibraryFixture[] = [];
 
-const fixtureIndex = new Map<string, CredentialFixture>();
+const fixtureIndex = new Map<string, LibraryFixture>();
+
+const validateFixtureIdentity = (fixture: LibraryFixture): void => {
+    // Registration is a runtime boundary and may receive untyped fixture data.
+    const runtimeKind = (fixture as { kind?: unknown }).kind;
+    const runtimeSpec = fixture.spec as string;
+
+    if (runtimeKind !== undefined && runtimeKind !== 'w3c-vc' && runtimeKind !== 'sd-jwt-vc') {
+        throw new Error(`Unsupported fixture kind "${String(runtimeKind)}".`);
+    }
+
+    if (isSdJwtVcFixture(fixture)) {
+        if (runtimeSpec !== 'sd-jwt-vc') {
+            throw new Error('SD-JWT VC fixtures must use spec "sd-jwt-vc".');
+        }
+
+        if (!fixture.id.startsWith('sd-jwt-vc/')) {
+            throw new Error('SD-JWT VC fixture IDs must start with "sd-jwt-vc/".');
+        }
+
+        return;
+    }
+
+    if (runtimeSpec === 'sd-jwt-vc') {
+        throw new Error('W3C VC fixtures cannot use spec "sd-jwt-vc".');
+    }
+
+    if (fixture.id.startsWith('sd-jwt-vc/')) {
+        throw new Error('The "sd-jwt-vc/" ID prefix is reserved for SD-JWT VC fixtures.');
+    }
+};
+
+const addFixture = (fixture: LibraryFixture): void => {
+    validateFixtureIdentity(fixture);
+
+    if (fixtureIndex.has(fixture.id)) {
+        throw new Error(
+            `Duplicate fixture ID: "${fixture.id}". Each fixture must have a unique id.`
+        );
+    }
+
+    fixtures.push(fixture);
+    fixtureIndex.set(fixture.id, fixture);
+};
 
 // ---------------------------------------------------------------------------
 // Lazy initialization — populate the registry on first query so consumers
@@ -27,8 +78,7 @@ const ensureInitialized = (): void => {
 
     for (const fixture of ALL_FIXTURES) {
         if (!fixtureIndex.has(fixture.id)) {
-            fixtures.push(fixture);
-            fixtureIndex.set(fixture.id, fixture);
+            addFixture(fixture);
         }
     }
 };
@@ -37,16 +87,11 @@ const ensureInitialized = (): void => {
 // 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 registerFixture = (fixture: LibraryFixture): void => {
+    addFixture(fixture);
 };
 
-export const registerFixtures = (batch: CredentialFixture[]): void => {
+export const registerFixtures = (batch: LibraryFixture[]): void => {
     for (const fixture of batch) {
         registerFixture(fixture);
     }
@@ -68,7 +113,15 @@ export const resetRegistry = (): void => {
 
 const toArray = <T>(value: T | T[]): T[] => (Array.isArray(value) ? value : [value]);
 
-const matchesFilter = (fixture: CredentialFixture, filter: FixtureFilter): boolean => {
+const fixtureKind = (fixture: LibraryFixture): FixtureKind => fixture.kind ?? 'w3c-vc';
+
+const matchesFilter = (fixture: LibraryFixture, filter: FixtureFilter): boolean => {
+    if (filter.kind !== undefined) {
+        const kinds = toArray(filter.kind);
+
+        if (!kinds.includes(fixtureKind(fixture))) return false;
+    }
+
     if (filter.spec !== undefined) {
         const specs = toArray(filter.spec);
 
@@ -122,13 +175,20 @@ const matchesFilter = (fixture: CredentialFixture, filter: FixtureFilter): boole
 // Public query API
 // ---------------------------------------------------------------------------
 
-export const getAllFixtures = (): readonly CredentialFixture[] => {
+export const getAllFixtures = (): readonly LibraryFixture[] => {
     ensureInitialized();
 
     return fixtures;
 };
 
-export const getFixture = (id: string): CredentialFixture => {
+type FixtureForId<Id extends string> = Id extends `sd-jwt-vc/${string}`
+    ? SdJwtVcFixture
+    : string extends Id
+    ? LibraryFixture
+    : CredentialFixture;
+
+export function getFixture<Id extends string>(id: Id): FixtureForId<Id>;
+export function getFixture(id: string): LibraryFixture {
     ensureInitialized();
 
     const fixture = fixtureIndex.get(id);
@@ -140,32 +200,33 @@ export const getFixture = (id: string): CredentialFixture => {
     }
 
     return fixture;
-};
+}
 
-export const findFixture = (id: string): CredentialFixture | undefined => {
+export function findFixture<Id extends string>(id: Id): FixtureForId<Id> | undefined;
+export function findFixture(id: string): LibraryFixture | undefined {
     ensureInitialized();
 
     return fixtureIndex.get(id);
-};
+}
 
-export const getFixtures = (filter: FixtureFilter): CredentialFixture[] => {
+export const getFixtures = (filter: FixtureFilter): LibraryFixture[] => {
     ensureInitialized();
 
     return fixtures.filter(f => matchesFilter(f, filter));
 };
 
-export const getUnsignedFixtures = (
-    filter?: FixtureFilter
-): CredentialFixture<UnsignedVC>[] =>
-    getFixtures({ ...filter, signed: false }) as CredentialFixture<UnsignedVC>[];
+export const getUnsignedFixtures = (filter?: FixtureFilter): CredentialFixture<UnsignedVC>[] =>
+    getFixtures({ ...filter, signed: false }).filter(
+        isCredentialFixture
+    ) as CredentialFixture<UnsignedVC>[];
 
 export const getSignedFixtures = (filter?: FixtureFilter): CredentialFixture<VC>[] =>
-    getFixtures({ ...filter, signed: true }) as CredentialFixture<VC>[];
+    getFixtures({ ...filter, signed: true }).filter(isCredentialFixture) as CredentialFixture<VC>[];
 
-export const getValidFixtures = (filter?: FixtureFilter): CredentialFixture[] =>
+export const getValidFixtures = (filter?: FixtureFilter): LibraryFixture[] =>
     getFixtures({ ...filter, validity: 'valid' });
 
-export const getInvalidFixtures = (filter?: FixtureFilter): CredentialFixture[] =>
+export const getInvalidFixtures = (filter?: FixtureFilter): LibraryFixture[] =>
     getFixtures({ ...filter, validity: ['invalid', 'tampered'] });
 
 // ---------------------------------------------------------------------------

package/src/types.ts

@@ -11,6 +11,7 @@ export const CREDENTIAL_SPECS = [
     'obv3',
     'clr-v2',
     'europass',
+    'sd-jwt-vc',
     'custom',
 ] as const;
 
@@ -63,6 +64,8 @@ export const CREDENTIAL_FEATURES = [
     'attachments',
     'associations',
     'nested-credentials',
+    'selective-disclosure',
+    'holder-binding',
 ] as const;
 
 export type CredentialFeature = (typeof CREDENTIAL_FEATURES)[number];
@@ -71,12 +74,7 @@ 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 const FIXTURE_SOURCES = ['spec-example', 'plugfest', 'real-world', 'synthetic'] as const;
 
 export type FixtureSource = (typeof FIXTURE_SOURCES)[number];
 
@@ -88,14 +86,18 @@ export const FIXTURE_VALIDITIES = ['valid', 'invalid', 'tampered'] as const;
 
 export type FixtureValidity = (typeof FIXTURE_VALIDITIES)[number];
 
+export const FIXTURE_KINDS = ['w3c-vc', 'sd-jwt-vc'] as const;
+
+export type FixtureKind = (typeof FIXTURE_KINDS)[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
+// BaseCredentialFixture — metadata shared by all fixture formats
 // ---------------------------------------------------------------------------
 
-export interface CredentialFixture<T extends UnsignedVC | VC = UnsignedVC> {
+export interface BaseCredentialFixture {
     /** Unique fixture ID, e.g. 'obv3/minimal-badge' */
     id: string;
 
@@ -123,21 +125,60 @@ export interface CredentialFixture<T extends UnsignedVC | VC = UnsignedVC> {
     /** Whether this fixture is intentionally valid, invalid, or tampered */
     validity: FixtureValidity;
 
+    /** Additional free-form tags for ad-hoc filtering */
+    tags?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// CredentialFixture — a W3C Verifiable Credential fixture
+// ---------------------------------------------------------------------------
+
+export interface CredentialFixture<T extends UnsignedVC | VC = UnsignedVC>
+    extends BaseCredentialFixture {
+    /** Omitted for backwards compatibility; W3C VC is the default fixture kind */
+    kind?: 'w3c-vc';
+
+    /** SD-JWT VC uses a separate template fixture variant */
+    spec: Exclude<CredentialSpec, 'sd-jwt-vc'>;
+
     /** 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[];
+export interface SdJwtVcTemplate {
+    format: 'dc+sd-jwt';
+    vct: string;
+    claims: Record<string, unknown>;
+    selectivelyDisclosable: string[];
+}
+
+export interface SdJwtVcFixture extends BaseCredentialFixture {
+    kind: 'sd-jwt-vc';
+    id: `sd-jwt-vc/${string}`;
+    spec: 'sd-jwt-vc';
+    signed: false;
+    template: SdJwtVcTemplate;
 }
 
+export type LibraryFixture = CredentialFixture | SdJwtVcFixture;
+
+export const isSdJwtVcFixture = (fixture: LibraryFixture): fixture is SdJwtVcFixture =>
+    fixture.kind === 'sd-jwt-vc';
+
+export const isCredentialFixture = (fixture: LibraryFixture): fixture is CredentialFixture =>
+    !isSdJwtVcFixture(fixture);
+
 // ---------------------------------------------------------------------------
 // Filter — used to query the registry
 // ---------------------------------------------------------------------------
 
 export interface FixtureFilter {
+    /** Match any of the given fixture kinds (omitted W3C kind is treated as w3c-vc) */
+    kind?: FixtureKind | FixtureKind[];
+
     /** Match any of the given specs */
     spec?: CredentialSpec | CredentialSpec[];