@learncard/ler-rs-plugin 0.1.15 → 0.1.17

package/package.json

@@ -1,57 +1,59 @@
 {
-  "name": "@learncard/ler-rs-plugin",
-  "version": "0.1.15",
-  "description": "LER-RS plugin for LearnCard: create, package, and verify Learning & Employment Record Resumes",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/ler-rs-plugin.esm.js",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/ler-rs-plugin.esm.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+    "name": "@learncard/ler-rs-plugin",
+    "version": "0.1.17",
+    "description": "LER-RS plugin for LearnCard: create, package, and verify Learning & Employment Record Resumes",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/ler-rs-plugin.esm.js",
+    "exports": {
+        ".": {
+            "development": "./src/index.ts",
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/ler-rs-plugin.esm.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "scripts": {
+        "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
+        "test": "jest --passWithNoTests",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
+    },
+    "author": "Learning Economy Foundation (www.learningeconomy.io)",
+    "license": "MIT",
+    "homepage": "https://github.com/learningeconomy/LearnCard#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/learningeconomy/LearnCard.git"
+    },
+    "bugs": {
+        "url": "https://github.com/learningeconomy/LearnCard/issues"
+    },
+    "devDependencies": {
+        "@types/jest": "^29.2.2",
+        "@types/node": "^17.0.31",
+        "aqu": "0.4.3",
+        "esbuild": "^0.14.38",
+        "esbuild-jest": "^0.5.0",
+        "esbuild-plugin-copy": "^1.3.0",
+        "jest": "^29.3.0",
+        "rimraf": "^3.0.2",
+        "shx": "^0.3.4",
+        "ts-jest": "^29.0.3"
+    },
+    "types": "./dist/index.d.ts",
+    "dependencies": {
+        "@learncard/core": "9.4.26",
+        "@learncard/types": "5.17.5",
+        "@learncard/vc-plugin": "1.5.6"
     }
-  },
-  "files": [
-    "dist"
-  ],
-  "author": "Learning Economy Foundation (www.learningeconomy.io)",
-  "license": "MIT",
-  "homepage": "https://github.com/learningeconomy/LearnCard#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/learningeconomy/LearnCard.git"
-  },
-  "bugs": {
-    "url": "https://github.com/learningeconomy/LearnCard/issues"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.2.2",
-    "@types/node": "^17.0.31",
-    "aqu": "0.4.3",
-    "esbuild": "^0.14.38",
-    "esbuild-jest": "^0.5.0",
-    "esbuild-plugin-copy": "^1.3.0",
-    "jest": "^29.3.0",
-    "rimraf": "^3.0.2",
-    "shx": "^0.3.4",
-    "ts-jest": "^29.0.3"
-  },
-  "types": "./dist/index.d.ts",
-  "dependencies": {
-    "@learncard/core": "9.4.24",
-    "@learncard/vc-plugin": "1.5.4",
-    "@learncard/types": "5.17.4"
-  },
-  "scripts": {
-    "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
-    "test": "jest --passWithNoTests",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
-  }
-}
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { getLerRsPlugin } from './ler-rs';
+export * from './types';

package/src/ler-rs.ts

@@ -0,0 +1,554 @@
+import {
+    VC as VerifiableCredential,
+    UnsignedVC,
+    VP as VerifiablePresentation,
+    UnsignedVP,
+} from '@learncard/types';
+import {
+    LERRSDependentLearnCard,
+    LERRSPlugin,
+    CreateLerRecordParams,
+    CreateLerPresentationParams,
+    VerifyLerPresentationParams,
+    VerificationResult,
+    LerRsRecord,
+    LER_RS_CREDENTIAL_CONTEXT_V2,
+    LER_RS_TYPE_URI_V45,
+    LEGACY_LER_RS_TYPE_URI_V44,
+    LEGACY_LER_RS_TYPE_TOKEN,
+    TCP_WRAPPER_TYPE,
+} from './types';
+
+/**
+ * Normalizes verification containers from either:
+ * - `verifications: VC[]`
+ * - `verifiableCredential: VC`
+ */
+const getItemVerifications = (item: {
+    verifiableCredential?: VerifiableCredential;
+    verifications?: VerifiableCredential[];
+}): VerifiableCredential[] => {
+    if (item.verifications?.length) return item.verifications;
+    if (item.verifiableCredential) return [item.verifiableCredential];
+    return [];
+};
+
+/**
+ * Converts scalar-or-array values into a normalized array.
+ */
+const toArray = <T>(maybe: T | T[] | undefined): T[] =>
+    maybe == null ? [] : Array.isArray(maybe) ? maybe : [maybe];
+
+/**
+ * Inline LER-RS JSON-LD context used for signing stability.
+ *
+ * The published HR Open URL is schema-oriented and can trigger additional remote
+ * context resolution during expansion. Inlining this base context avoids network
+ * dependency at issue time while preserving deterministic term expansion.
+ */
+const inlineLerRsContext = {
+    '@version': 1.1,
+    hrrec: 'http://schema.hropenstandards.org/recruiting/',
+    '@vocab': 'http://schema.hropenstandards.org/recruiting/',
+};
+
+/**
+ * Determines whether a VC represents a LER-RS credential (legacy and current forms).
+ *
+ * Checks:
+ * - VC `type` array/token values
+ * - `credentialSubject.type`
+ * - nested `credentialSubject.lerrsType.type`
+ */
+const credentialHasLerRsType = (credential: VerifiableCredential): boolean => {
+    const typeList = Array.isArray(credential.type) ? credential.type : [credential.type];
+    if (
+        typeList.some(type =>
+            [LEGACY_LER_RS_TYPE_TOKEN, LEGACY_LER_RS_TYPE_URI_V44, LER_RS_TYPE_URI_V45].includes(
+                type
+            )
+        )
+    )
+        return true;
+
+    const credentialSubject = credential.credentialSubject as Record<string, unknown> | undefined;
+    if (!credentialSubject) return false;
+
+    const inlineType = credentialSubject.type;
+    if (
+        typeof inlineType === 'string' &&
+        [LEGACY_LER_RS_TYPE_URI_V44, LER_RS_TYPE_URI_V45].includes(inlineType)
+    )
+        return true;
+
+    const nestedType = (credentialSubject.lerrsType as Record<string, unknown> | undefined)?.type;
+    return (
+        typeof nestedType === 'string' &&
+        [LEGACY_LER_RS_TYPE_URI_V44, LER_RS_TYPE_URI_V45].includes(nestedType)
+    );
+};
+
+/**
+ * Maps application work history items to LER-RS `employmentHistories` shape.
+ */
+const buildEmploymentHistories = (
+    items: NonNullable<CreateLerRecordParams['workHistory']>
+): LerRsRecord['employmentHistories'] => {
+    return items.map(item => {
+        const {
+            narrative,
+            descriptions,
+            verifiableCredential,
+            verifications,
+            position,
+            employer,
+            start,
+            end,
+            current,
+            ...rest
+        } = item;
+
+        const container: Record<string, unknown> = { ...rest };
+        if (typeof current === 'boolean') container.current = current;
+
+        if (employer) container.organization = { tradeName: employer };
+        if (position || start || end || typeof current === 'boolean') {
+            const ph: Record<string, unknown> = {};
+            if (position) ph.title = position;
+            if (start) ph.start = start;
+            if (end) ph.end = end;
+            if (typeof current === 'boolean') ph.current = current;
+            if (descriptions?.length) ph.descriptions = descriptions;
+            container.positionHistories = [ph];
+        }
+        if (narrative) container.narrative = narrative;
+        if (descriptions?.length && !container.positionHistories) container.descriptions = descriptions;
+
+        const containerVerifications = getItemVerifications({
+            verifiableCredential,
+            verifications,
+        });
+        return {
+            ...container,
+            ...(containerVerifications.length ? { verifications: containerVerifications } : {}),
+        };
+    });
+};
+
+/**
+ * Maps education source items into LER-RS `educationAndLearnings`.
+ */
+const buildEducationAndLearnings = (
+    items: NonNullable<CreateLerRecordParams['educationHistory']>
+): LerRsRecord['educationAndLearnings'] => {
+    return items.map(item => {
+        const {
+            narrative,
+            descriptions,
+            verifiableCredential,
+            verifications,
+            institution,
+            start,
+            end,
+            current,
+            degree,
+            specializations,
+            ...rest
+        } = item;
+
+        const container: Record<string, unknown> = { ...rest };
+        if (institution) container.institution = { name: institution };
+        if (start) container.start = start;
+        if (end) container.end = end;
+        if (typeof current === 'boolean') container.current = current;
+        if (descriptions?.length) container.descriptions = descriptions;
+        if (degree || specializations) {
+            container.educationDegrees = [
+                {
+                    ...(degree ? { name: degree } : {}),
+                    ...(specializations
+                        ? {
+                              specializations: specializations.map(specialization => ({
+                                  name: specialization,
+                              })),
+                          }
+                        : {}),
+                },
+            ];
+        }
+        if (narrative) container.narrative = narrative;
+
+        const containerVerifications = getItemVerifications({
+            verifiableCredential,
+            verifications,
+        });
+        return {
+            ...container,
+            ...(containerVerifications.length ? { verifications: containerVerifications } : {}),
+        };
+    });
+};
+
+/**
+ * Maps certification source items to LER-RS `certifications`.
+ */
+const buildCertifications = (
+    items: NonNullable<CreateLerRecordParams['certifications']>
+): LerRsRecord['certifications'] => {
+    return items.map(item => {
+        const {
+            narrative,
+            descriptions,
+            start,
+            end,
+            effectiveTimePeriod,
+            verifiableCredential,
+            verifications,
+            ...rest
+        } = item;
+
+        const container: Record<string, unknown> = { ...rest };
+        if (narrative) container.narrative = narrative;
+        if (descriptions?.length) container.descriptions = descriptions;
+        if (effectiveTimePeriod || start || end) {
+            container.effectiveTimePeriod = {
+                ...(effectiveTimePeriod ?? {}),
+                ...(start ? { validFrom: start } : {}),
+                ...(end ? { validTo: end } : {}),
+            };
+        }
+
+        const containerVerifications = getItemVerifications({
+            verifiableCredential,
+            verifications,
+        });
+        return {
+            ...container,
+            ...(containerVerifications.length ? { verifications: containerVerifications } : {}),
+        };
+    });
+};
+
+/**
+ * Returns the LearnCard LER-RS plugin with methods for:
+ * - issuing LER-RS VCs
+ * - packaging/verifying LER presentations
+ * - issuing TCP wrapper VCs for resume packages
+ */
+export const getLerRsPlugin = (initLearnCard: LERRSDependentLearnCard): LERRSPlugin => {
+    return {
+        name: 'LER-RS',
+        displayName: 'LER-RS',
+        description:
+            'Create, package, and verify Learning & Employment Record Resume (LER-RS) credentials',
+        methods: {
+            /**
+             * Issues a signed LER-RS VC from normalized person/work/education/certification data.
+             *
+             * The method:
+             * 1. Builds a compliant LER-RS `credentialSubject`
+             * 2. Applies VC + LER-RS contexts
+             * 3. Signs via `invoke.issueCredential`
+             */
+            createLerRecord: async (_learnCard, params): Promise<VerifiableCredential> => {
+                const signer = params.learnCard ?? _learnCard;
+                const did = signer.id.did();
+                const issuedAt = new Date().toISOString();
+                const documentId = crypto.randomUUID();
+
+                const personSection: LerRsRecord['person'] = {
+                    name: {
+                        given: params.person.givenName,
+                        family: params.person.familyName,
+                        formattedName:
+                            params.person.formattedName ??
+                            `${params.person.givenName} ${params.person.familyName}`,
+                    },
+                };
+
+                const hasAddress =
+                    !!params.person.address?.formattedAddress ||
+                    !!params.person.address?.line ||
+                    !!params.person.address?.city ||
+                    !!params.person.address?.postalCode ||
+                    !!params.person.address?.countryCode;
+                const webEntries = (params.person.web || []).filter(entry => entry?.url);
+                const socialEntries = (params.person.social || []).filter(entry => entry?.uri);
+
+                const communication: LerRsRecord['communication'] | undefined =
+                    params.person.email ||
+                    params.person.phone ||
+                    hasAddress ||
+                    webEntries.length > 0 ||
+                    socialEntries.length > 0
+                        ? {
+                              ...(params.person.email
+                                  ? { email: [{ address: params.person.email }] }
+                                  : {}),
+                              ...(params.person.phone
+                                  ? { phone: [{ formattedNumber: params.person.phone }] }
+                                  : {}),
+                              ...(webEntries.length
+                                  ? { web: webEntries.map(entry => ({ url: entry.url, name: entry.name })) }
+                                  : {}),
+                              ...(socialEntries.length
+                                  ? {
+                                        social: socialEntries.map(entry => ({
+                                            uri: entry.uri,
+                                            ...(entry.name ? { name: entry.name } : {}),
+                                        })),
+                                    }
+                                  : {}),
+                              ...(hasAddress
+                                  ? {
+                                        address: [
+                                            {
+                                                ...(params.person.address?.formattedAddress
+                                                    ? {
+                                                          formattedAddress:
+                                                              params.person.address.formattedAddress,
+                                                      }
+                                                    : {}),
+                                                ...(params.person.address?.line
+                                                    ? { line: params.person.address.line }
+                                                    : {}),
+                                                ...(params.person.address?.city
+                                                    ? { city: params.person.address.city }
+                                                    : {}),
+                                                ...(params.person.address?.postalCode
+                                                    ? { postalCode: params.person.address.postalCode }
+                                                    : {}),
+                                                ...(params.person.address?.countryCode
+                                                    ? {
+                                                          countryCode:
+                                                              params.person.address.countryCode,
+                                                      }
+                                                    : {}),
+                                            },
+                                        ],
+                                    }
+                                  : {}),
+                          }
+                        : undefined;
+
+                const lerRecord: LerRsRecord = {
+                    type: LER_RS_TYPE_URI_V45,
+                    documentId: { value: documentId },
+                    person: personSection,
+                    ...(communication ? { communication } : {}),
+                    skills: (params.skills || []).map(s => ({ name: s })),
+                    narratives: params.narratives,
+                    employmentHistories: params.workHistory
+                        ? buildEmploymentHistories(params.workHistory)
+                        : undefined,
+                    educationAndLearnings: params.educationHistory
+                        ? buildEducationAndLearnings(params.educationHistory)
+                        : undefined,
+                    certifications: params.certifications
+                        ? buildCertifications(params.certifications)
+                        : undefined,
+                    attachments: params.attachments,
+                };
+
+                const unsignedVC: UnsignedVC = {
+                    '@context': [LER_RS_CREDENTIAL_CONTEXT_V2, inlineLerRsContext],
+                    id: `urn:uuid:${documentId}`,
+                    type: ['VerifiableCredential', LER_RS_TYPE_URI_V45],
+                    issuer: did,
+                    validFrom: issuedAt,
+                    credentialSubject: {
+                        id: params.person.id,
+                        ...lerRecord,
+                    },
+                };
+
+                return initLearnCard.invoke.issueCredential(unsignedVC, {
+                    proofPurpose: 'assertionMethod',
+                });
+            },
+
+            /**
+             * Issues a VP containing at least one LER-RS credential.
+             *
+             * Throws if:
+             * - credentials list is empty
+             * - none of the credentials match LER-RS type checks
+             */
+            createLerPresentation: async (_learnCard, params): Promise<VerifiablePresentation> => {
+                const signer = params.learnCard ?? _learnCard;
+                const did = signer.id.did();
+
+                if (!params.credentials.length)
+                    throw new Error(
+                        'createLerPresentation: credentials array must contain at least one credential'
+                    );
+                const containsLer = params.credentials.some(credentialHasLerRsType);
+                if (!containsLer)
+                    throw new Error(
+                        'createLerPresentation: credentials must include at least one LER-RS credential'
+                    );
+
+                const vp: UnsignedVP = {
+                    '@context': [LER_RS_CREDENTIAL_CONTEXT_V2],
+                    type: ['VerifiablePresentation'],
+                    holder: did,
+                    verifiableCredential:
+                        params.credentials.length === 1
+                            ? params.credentials[0]
+                            : params.credentials,
+                };
+
+                return initLearnCard.invoke.issuePresentation(vp, {
+                    ...(params.domain ? { domain: params.domain } : {}),
+                    ...(params.challenge ? { challenge: params.challenge } : {}),
+                });
+            },
+
+            /**
+             * Verifies a LER-focused VP and returns structured result details.
+             *
+             * Overall `verified` allows explicitly self-issued items when determining
+             * final status, while still surfacing per-credential verification results.
+             */
+            verifyLerPresentation: async (
+                _learnCard,
+                { presentation, domain, challenge }: VerifyLerPresentationParams
+            ): Promise<VerificationResult> => {
+                const presCheck = await initLearnCard.invoke.verifyPresentation(presentation, {
+                    ...(domain ? { domain } : {}),
+                    ...(challenge ? { challenge } : {}),
+                });
+
+                const presentationResult = {
+                    verified: presCheck.errors.length === 0,
+                    errors: presCheck.errors.length ? presCheck.errors : undefined,
+                };
+
+                const credentialResults: VerificationResult['credentialResults'] = [];
+
+                if (typeof presentation !== 'string') {
+                    const holder = presentation.holder;
+                    const vcs = toArray<VerifiableCredential>(
+                        presentation.verifiableCredential as any
+                    );
+
+                    for (const credential of vcs) {
+                        try {
+                            const credCheck = await initLearnCard.invoke.verifyCredential(
+                                credential
+                            );
+                            const issuerDid =
+                                typeof credential.issuer === 'string'
+                                    ? credential.issuer
+                                    : credential.issuer?.id;
+                            const isSelfIssued =
+                                credentialHasLerRsType(credential) ||
+                                (!!holder && !!issuerDid && issuerDid === holder);
+
+                            credentialResults.push({
+                                credential,
+                                verified: credCheck.errors.length === 0,
+                                isSelfIssued,
+                                errors: credCheck.errors.length ? credCheck.errors : undefined,
+                            });
+                        } catch (err) {
+                            credentialResults.push({
+                                credential,
+                                verified: false,
+                                isSelfIssued: false,
+                                errors: [
+                                    err instanceof Error
+                                        ? err.message
+                                        : 'Unknown error verifying credential',
+                                ],
+                            });
+                        }
+                    }
+                }
+
+                return {
+                    verified:
+                        presentationResult.verified &&
+                        credentialResults.every(r => r.verified || r.isSelfIssued),
+                    presentationResult,
+                    credentialResults,
+                };
+            },
+
+            /**
+             * Issues a signed TrustedCareerProfile wrapper VC for resume package publishing.
+             *
+             * Includes:
+             * - public PDF URL
+             * - PDF SHA-256 hash
+             * - included credential references
+             * - generation timestamp
+             *
+             * Co-sign fields are intentionally stubbed for MVP and currently rejected.
+             */
+            createTcpWrapperVc: async (_learnCard, params): Promise<VerifiableCredential> => {
+                const signer = params.learnCard ?? _learnCard;
+                const did = signer.id.did();
+                const issuedAt = params.issuanceDate ?? new Date().toISOString();
+                const generatedAt = params.generatedAt ?? issuedAt;
+                const subjectDid = params.subjectDid ?? did;
+
+                if (params.enableCoSign) {
+                    throw new Error('createTcpWrapperVc: co-signing is not enabled in MVP');
+                }
+
+                if (params.coSignerDid) {
+                    throw new Error(
+                        'createTcpWrapperVc: coSignerDid is reserved for future co-sign support'
+                    );
+                }
+
+                // NOTE: We inline the TCP context for local testing while the hosted
+                // context URL is not yet available in all environments.
+                const inlineTcpContext = {
+                    '@version': 1.1,
+                    id: '@id',
+                    type: '@type',
+                    TrustedCareerProfile: 'https://ctx.learncard.com/tcp#TrustedCareerProfile',
+                    ResumePackage: 'https://ctx.learncard.com/tcp#ResumePackage',
+                    pdfUrl: {
+                        '@id': 'https://ctx.learncard.com/tcp#pdfUrl',
+                        '@type': '@id',
+                    },
+                    pdfHash: 'https://ctx.learncard.com/tcp#pdfHash',
+                    hashAlgorithm: 'https://ctx.learncard.com/tcp#hashAlgorithm',
+                    includedCredentials: {
+                        '@id': 'https://ctx.learncard.com/tcp#includedCredentials',
+                        '@container': '@set',
+                    },
+                    category: 'https://ctx.learncard.com/tcp#category',
+                    generatedAt: {
+                        '@id': 'https://ctx.learncard.com/tcp#generatedAt',
+                        '@type': 'http://www.w3.org/2001/XMLSchema#dateTime',
+                    },
+                };
+
+                const unsignedVC: UnsignedVC = {
+                    '@context': [LER_RS_CREDENTIAL_CONTEXT_V2, inlineTcpContext],
+                    type: ['VerifiableCredential', TCP_WRAPPER_TYPE],
+                    id: params.wrapperId,
+                    issuer: did,
+                    validFrom: issuedAt,
+                    credentialSubject: {
+                        id: subjectDid,
+                        type: 'ResumePackage',
+                        pdfUrl: params.pdfUrl,
+                        pdfHash: params.pdfHash,
+                        hashAlgorithm: 'SHA-256',
+                        includedCredentials: params.includedCredentials,
+                        generatedAt,
+                    },
+                };
+
+                return initLearnCard.invoke.issueCredential(unsignedVC, {
+                    proofPurpose: 'assertionMethod',
+                });
+            },
+        },
+    };
+};

package/src/types.ts

@@ -0,0 +1,298 @@
+import { Plugin, LearnCard } from '@learncard/core';
+import {
+    VC as VerifiableCredential,
+    VP as VerifiablePresentation,
+    UnsignedVC,
+    UnsignedVP,
+    VerificationCheck,
+} from '@learncard/types';
+import type { VCPluginMethods, VCPluginDependentMethods } from '@learncard/vc-plugin';
+
+/**
+ * Legacy W3C VC v1 context kept for interop with previously issued records.
+ */
+export const LER_RS_CREDENTIAL_CONTEXT_V1 = 'https://www.w3.org/2018/credentials/v1';
+/**
+ * Base W3C VC v2 context used by newly issued LER-RS credentials and presentations.
+ */
+export const LER_RS_CREDENTIAL_CONTEXT_V2 = 'https://www.w3.org/ns/credentials/v2';
+/**
+ * HR Open Standards VC wrapper context for LER-RS v4.5.
+ */
+export const LER_RS_VC_CONTEXT_V45 =
+    'http://schema.hropenstandards.org/4.5/recruiting/json/VerifiableCredentialLER-RSType.json';
+/**
+ * Canonical LER-RS type URI for v4.5.
+ */
+export const LER_RS_TYPE_URI_V45 =
+    'http://schema.hropenstandards.org/4.5/recruiting/json/LER-RSType.json';
+/**
+ * Legacy LER-RS type URI for v4.4 interop.
+ */
+export const LEGACY_LER_RS_TYPE_URI_V44 =
+    'http://schema.hropenstandards.org/4.4/recruiting/json/ler-rs/LER-RSType.json';
+/**
+ * Legacy short type token used by older issuers.
+ */
+export const LEGACY_LER_RS_TYPE_TOKEN = 'LERRS';
+/**
+ * Hosted TCP JSON-LD context URL.
+ *
+ * Note: current local wrapper issuance can inline context during local testing.
+ */
+export const TCP_CONTEXT_V1 = 'https://ctx.learncard.com/tcp/1.0.0.json';
+/**
+ * LearnCard-defined wrapper VC type for TCP resume package artifacts.
+ *
+ * This is intentionally NOT a canonical HR Open Standards LER-RS type;
+ * it is a custom wrapper used to bind PDF URL/hash + included credential refs.
+ */
+export const TCP_WRAPPER_TYPE = 'TrustedCareerProfile';
+
+/**
+ * Identity details used to populate `credentialSubject.person`.
+ */
+export interface PersonProfile {
+    /** Subject DID for the issued LER-RS record. */
+    id: string;
+    /** Given/first name. */
+    givenName: string;
+    /** Family/last name. */
+    familyName: string;
+    /** Optional display name override. */
+    formattedName?: string;
+    /** Optional contact email to include in communication block. */
+    email?: string;
+    /** Optional contact phone to include in communication block. */
+    phone?: string;
+    /** Optional physical/mailing address to include in communication block. */
+    address?: {
+        formattedAddress?: string;
+        line?: string;
+        city?: string;
+        postalCode?: string;
+        countryCode?: string;
+    };
+    /** Optional website URLs to include in communication block. */
+    web?: Array<{ url: string; name?: string }>;
+    /** Optional social profile URLs to include in communication block. */
+    social?: Array<{ uri: string; name?: string }>;
+}
+
+/**
+ * Skill item structure used inside generated LER-RS records.
+ */
+export interface LerSkill {
+    name: string;
+    comments?: string[];
+    description?: string;
+    yearsOfExperience?: number;
+    endorsers?: Array<{
+        person?: { name?: { formattedName?: string } };
+        organization?: { name?: string };
+    }>;
+}
+
+/**
+ * Source work history entry. Can be self-asserted fields and/or third-party verification VCs.
+ */
+export interface WorkHistoryItem {
+    narrative?: string;
+    descriptions?: string[];
+    verifiableCredential?: VerifiableCredential;
+    verifications?: VerifiableCredential[];
+    // Common self-asserted fields
+    position?: string;
+    employer?: string;
+    start?: string;
+    end?: string;
+    current?: boolean;
+    [key: string]: unknown;
+}
+
+/**
+ * Source education entry. Can include freeform fields and optional verification VCs.
+ */
+export interface EducationHistoryItem {
+    narrative?: string;
+    descriptions?: string[];
+    verifiableCredential?: VerifiableCredential;
+    verifications?: VerifiableCredential[];
+    institution?: string;
+    start?: string;
+    end?: string;
+    current?: boolean;
+    degree?: string;
+    specializations?: string[];
+    [key: string]: unknown;
+}
+
+/**
+ * Source certification entry for `credentialSubject.certifications`.
+ */
+export interface CertificationItem {
+    narrative?: string;
+    descriptions?: string[];
+    verifiableCredential?: VerifiableCredential;
+    verifications?: VerifiableCredential[];
+    name?: string;
+    issuingAuthority?: string | Record<string, unknown>;
+    status?: string;
+    start?: string;
+    end?: string;
+    effectiveTimePeriod?: { validFrom?: string; validTo?: string };
+    [key: string]: unknown;
+}
+
+/**
+ * Narrative section block supported by LER-RS schema.
+ */
+export interface LerNarrative {
+    name: string;
+    texts: Array<{
+        name: string;
+        lines: string[];
+    }>;
+}
+
+/**
+ * Typed shape of the LER-RS object embedded into `credentialSubject`.
+ */
+export interface LerRsRecord {
+    type: string;
+    documentId?: { value: string };
+    person: {
+        name: {
+            given: string;
+            family: string;
+            formattedName?: string;
+        };
+    };
+    communication?: {
+        email?: { address: string }[];
+        web?: { url: string; name?: string }[];
+        phone?: Array<Record<string, unknown>>;
+        address?: Array<Record<string, unknown>>;
+        social?: Array<Record<string, unknown>>;
+    };
+    skills?: LerSkill[];
+    narratives?: LerNarrative[];
+    educationAndLearnings?: Array<
+        { verifications?: VerifiableCredential[] } & Record<string, unknown>
+    >;
+    employmentHistories?: Array<
+        { verifications?: VerifiableCredential[] } & Record<string, unknown>
+    >;
+    licenses?: Array<{ verifications?: VerifiableCredential[] } & Record<string, unknown>>;
+    certifications?: Array<{ verifications?: VerifiableCredential[] } & Record<string, unknown>>;
+    employmentPreferences?: Array<Record<string, unknown>>;
+    positionPreferences?: Array<Record<string, unknown>>;
+    attachments?: Array<Record<string, unknown>>;
+}
+
+/**
+ * Parameters for issuing a signed LER-RS VC from normalized source data.
+ */
+export interface CreateLerRecordParams {
+    learnCard: LearnCard<any, 'id', VCPluginMethods & VCPluginDependentMethods>;
+    person: PersonProfile;
+    workHistory?: WorkHistoryItem[];
+    educationHistory?: EducationHistoryItem[];
+    certifications?: CertificationItem[];
+    skills?: string[];
+    narratives?: LerNarrative[];
+    attachments?: Array<Record<string, unknown>>;
+}
+
+/**
+ * Parameters for issuing a VP that packages one or more credentials including at least one LER-RS credential.
+ */
+export interface CreateLerPresentationParams {
+    learnCard: LearnCard<any, 'id', VCPluginMethods & VCPluginDependentMethods>;
+    credentials: VerifiableCredential[];
+    domain?: string;
+    challenge?: string;
+}
+
+/**
+ * Parameters for verifying a LER-focused VP and nested credentials.
+ */
+export interface VerifyLerPresentationParams {
+    presentation: VerifiablePresentation | string;
+    domain?: string;
+    challenge?: string;
+}
+
+/**
+ * Credential reference stored in TCP wrapper VC.
+ */
+export interface TcpIncludedCredentialRef {
+    /** Resolved VC id when available; falls back to URI if id is unavailable. */
+    id: string;
+    /** Category label used for UI grouping and downstream filtering. */
+    category: string;
+}
+
+/**
+ * Parameters for issuing TrustedCareerProfile wrapper VCs.
+ */
+export interface CreateTcpWrapperVcParams {
+    learnCard: LearnCard<any, 'id', VCPluginMethods & VCPluginDependentMethods>;
+    wrapperId: string;
+    subjectDid?: string;
+    pdfUrl: string;
+    pdfHash: string;
+    includedCredentials: TcpIncludedCredentialRef[];
+    generatedAt?: string;
+    /** Timestamp used as the issued credential's `validFrom` value. */
+    issuanceDate?: string;
+    coSignerDid?: string;
+    enableCoSign?: boolean;
+}
+
+/**
+ * Structured verification output for LER presentation verification.
+ */
+export interface VerificationResult {
+    verified: boolean; // Overall status
+    presentationResult: {
+        verified: boolean;
+        errors?: string[];
+    };
+    credentialResults: {
+        credential: VerifiableCredential;
+        verified: boolean;
+        isSelfIssued: boolean;
+        errors?: string[];
+    }[];
+}
+
+/**
+ * LearnCard dependency contract required by this plugin.
+ */
+export type LERRSDependentLearnCard = LearnCard<
+    any,
+    'id',
+    VCPluginMethods & VCPluginDependentMethods
+>;
+
+/**
+ * Public invoke methods exposed by the LER-RS plugin.
+ */
+export type LERRSPluginMethods = {
+    createLerRecord: (params: CreateLerRecordParams) => Promise<VerifiableCredential>;
+    createLerPresentation: (params: CreateLerPresentationParams) => Promise<VerifiablePresentation>;
+    verifyLerPresentation: (params: VerifyLerPresentationParams) => Promise<VerificationResult>;
+    createTcpWrapperVc: (params: CreateTcpWrapperVcParams) => Promise<VerifiableCredential>;
+};
+
+/**
+ * Plugin type definition for registration in LearnCard.
+ */
+export type LERRSPlugin = Plugin<
+    'LER-RS',
+    never,
+    LERRSPluginMethods,
+    'id',
+    VCPluginMethods & VCPluginDependentMethods
+>;

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Learning Economy Foundation <sdk@learningeconomy.io>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.