fix: CLR compliance

tcouper · tcouper · commit d9b2e8919c4f · 2026-03-12T07:29:08.000-07:00
diff --git a/apps/learner-ux/src/App.tsx b/apps/learner-ux/src/App.tsx
@@ -416,6 +416,7 @@ function LearnerPage() {
     }
     try {
       setExportingClr(true);
+      setError("");
       const response = await createClrExport(learnerId, { consumerId: selectedConsumerId });
       const blob = new Blob([JSON.stringify(response.clr, null, 2)], { type: "application/json" });
       const url = URL.createObjectURL(blob);
@@ -530,6 +531,7 @@ function LearnerPage() {
                 {consumers.find((consumer) => consumer.consumerId === selectedConsumerId)?.didKey ?? ""}
               </p>
             )}
+            {error && <p className="mt-2 text-xs text-red-700">{error}</p>}
           </Card>
         )}
 
diff --git a/apps/learner-ux/src/api.ts b/apps/learner-ux/src/api.ts
@@ -136,15 +136,19 @@ export async function createClrExport(
   learnerId: string,
   payload: { consumerId: string; expirationDate?: string; issuer?: string }
 ): Promise<CreateClrExportResponse> {
-  const response = await fetch(buildUrl(`/learners/${encodeURIComponent(learnerId)}/export/clr2`), {
+  const query = new URLSearchParams({ learnerId });
+  const response = await fetch(buildUrl(`/learners/by-id/export/clr2?${query.toString()}`), {
     method: "POST",
     headers: {
       "content-type": "application/json",
       ...(await authHeaders())
     },
     body: JSON.stringify(payload)
   });
-  if (!response.ok) throw new Error("Failed to create CLR export");
+  if (!response.ok) {
+    const details = await readErrorDetails(response);
+    throw new Error(`Failed to create CLR export: ${details}`);
+  }
   return await response.json() as CreateClrExportResponse;
 }
 
@@ -228,3 +232,21 @@ async function fetchWithRetry(
   }
   return response as Response;
 }
+
+async function readErrorDetails(response: Response): Promise<string> {
+  const fallback = `${response.status} ${response.statusText || "request_failed"}`;
+  try {
+    const payload = await response.json() as { reason?: string; details?: string[] };
+    const detailText = Array.isArray(payload.details) && payload.details.length > 0
+      ? payload.details.join("; ")
+      : (payload.reason ?? fallback);
+    return detailText;
+  } catch {
+    try {
+      const text = await response.text();
+      return text || fallback;
+    } catch {
+      return fallback;
+    }
+  }
+}
diff --git a/services/learner-context-handler/src/index.ts b/services/learner-context-handler/src/index.ts
@@ -22,8 +22,10 @@ import {
   createToolbox,
   type Clr2Achievement,
   type PresentationMetadata,
+  type SignedCredential,
   type SelectedClaim,
-  type SelectedCredential
+  type SelectedCredential,
+  type UnsignedCredential
 } from "../../../toolbox/src/index.js";
 
 const ddbDocClient = DynamoDBDocumentClient.from(new DynamoDBClient({}));
@@ -32,8 +34,10 @@ const EVENT_TABLE = process.env.EVENT_TABLE_NAME ?? "";
 const CREDENTIAL_TABLE = process.env.CREDENTIAL_TABLE_NAME ?? "";
 const GRAPH_PROJECTION_TABLE = process.env.GRAPH_PROJECTION_TABLE_NAME ?? "";
 const CONSUMER_TABLE = process.env.CONSUMER_TABLE_NAME ?? "";
+const TOOLBOX_ISSUER_DID = process.env.TOOLBOX_ISSUER_DID ?? "";
 const TRUSTED_ISSUERS = (process.env.TRUSTED_ISSUERS ?? "").split(",").map((issuer) => issuer.trim()).filter(Boolean);
 let toolboxPromise: Promise<Awaited<ReturnType<typeof createToolbox>>> | undefined;
+let exportIssuerDidPromise: Promise<string> | undefined;
 
 interface HttpEvent {
   rawPath?: string;
@@ -571,18 +575,41 @@ async function handleExportClr2(event: HttpEvent, fromQuery: boolean) {
     });
   }
   const now = new Date().toISOString();
-  const issuer = request.issuer && request.issuer.trim().length > 0
-    ? request.issuer.trim()
-    : (TRUSTED_ISSUERS[0] ?? "did:example:issuer:trusted-learning-context");
   const toolbox = await getToolbox();
-  const unsignedCredential = toolbox.clr2.createCredential({
+  // VC signing requires an issuer DID managed by this toolbox instance.
+  // Use a managed DID for signing/export stability, regardless of source-system issuers.
+  const issuer = await resolveExportIssuerDid(toolbox);
+  const embeddedCredentials = await buildClrEmbeddedCredentials(
+    toolbox,
+    issuer,
+    learnerId,
+    filteredSessions,
+    issuedBadges,
+    consumer.policy.includeBadges
+  );
+  const unsignedCredential: UnsignedCredential = {
+    "@context": [
+      "https://www.w3.org/ns/credentials/v2",
+      "https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1.json",
+      "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
+    ],
+    type: ["VerifiableCredential", "ClrCredential"],
     issuer,
-    learner: learnerId,
     issuanceDate: now,
     ...(request.expirationDate ? { expirationDate: request.expirationDate } : {}),
-    achievements
+    credentialSubject: {
+      id: learnerId,
+      type: ["ClrSubject"],
+      verifiableCredential: embeddedCredentials
+    }
+  };
+  const signedCredential = await toolbox.vc.sign(unsignedCredential);
+  const validatorSafeCredential = toValidatorSafeCredential(signedCredential, {
+    learnerId,
+    issuerDid: issuer,
+    validFrom: now,
+    embeddedCredentials
   });
-  const signedCredential = await toolbox.clr2.sign(unsignedCredential);
   return json(200, {
     status: "created",
     learnerId,
@@ -594,7 +621,8 @@ async function handleExportClr2(event: HttpEvent, fromQuery: boolean) {
       achievementCount: achievements.length
     },
     fileName: `${learnerId}-${consumer.consumerId}-clr2.json`,
-    clr: signedCredential
+    clr: validatorSafeCredential,
+    ...(typeof signedCredential.proof.jws === "string" ? { jwt: signedCredential.proof.jws } : {})
   });
 }
 
@@ -1240,6 +1268,158 @@ function toClr2AchievementFromBadge(badge: IssuedBadge): Clr2Achievement {
   };
 }
 
+async function buildClrEmbeddedCredentials(
+  toolbox: Awaited<ReturnType<typeof createToolbox>>,
+  signingIssuerDid: string,
+  learnerId: string,
+  sessions: SessionView[],
+  badges: IssuedBadge[],
+  includeBadges: boolean
+): Promise<Record<string, unknown>[]> {
+  const sessionCredentials = await Promise.all(sessions.map(async (session) => {
+    const vc = {
+      "@context": [
+        "https://www.w3.org/ns/credentials/v2",
+        "http://purl.imsglobal.org/ctx/caliper/v1p2"
+      ],
+      id: `urn:trusted-learning-context:embedded:${session.credentialId}`,
+      type: ["VerifiableCredential", "CaliperCredential"],
+      name: session.title,
+      issuer: {
+        id: signingIssuerDid,
+        type: ["Profile"],
+        name: "Trusted Learning Context Session Issuer"
+      },
+      validFrom: session.issuedAt,
+      issuanceDate: session.issuedAt,
+      credentialSubject: {
+        id: learnerId,
+        type: ["AchievementSubject"],
+        sourceFormat: "caliper",
+        course: session.context.course ?? "Unspecified",
+        evidence: session.claims.slice(0, 8).map((claim) => ({
+          label: claim.label,
+          value: String(claim.value)
+        }))
+      }
+    } as Record<string, unknown>;
+    return await attachEmbeddedProof(toolbox, vc, signingIssuerDid);
+  }));
+
+  const badgeCredentials = includeBadges
+    ? await Promise.all(badges.map(async (badge) => {
+      const vc = {
+        "@context": [
+          "https://www.w3.org/ns/credentials/v2",
+          "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
+        ],
+        id: `urn:trusted-learning-context:embedded-badge:${badge.credentialId}`,
+        type: ["VerifiableCredential", "OpenBadgeCredential"],
+        name: `${badge.subject ?? "Issued badge"} Credential`,
+        issuer: {
+          id: signingIssuerDid,
+          type: ["Profile"],
+          name: "Trusted Learning Context Badge Issuer"
+        },
+        validFrom: badge.issuedAt,
+        credentialSubject: {
+          id: learnerId,
+          type: ["AchievementSubject"],
+          achievement: {
+            id: `urn:trusted-learning-context:achievement:${badge.credentialId}`,
+            type: ["Achievement"],
+            name: badge.subject ?? "Issued badge",
+            description: badge.subject ?? "OpenBadge achievement issued from learner context.",
+            criteria: {
+              narrative: "Learner satisfied all required criteria for this badge."
+            }
+          }
+        }
+      } as Record<string, unknown>;
+      return await attachEmbeddedProof(toolbox, vc, signingIssuerDid);
+    }))
+    : [];
+
+  return [...sessionCredentials, ...badgeCredentials];
+}
+
+async function attachEmbeddedProof(
+  toolbox: Awaited<ReturnType<typeof createToolbox>>,
+  vc: Record<string, unknown>,
+  issuerDid: string
+): Promise<Record<string, unknown>> {
+  const context = Array.isArray(vc["@context"]) ? [...(vc["@context"] as string[])] : [];
+  const subject = vc.credentialSubject && typeof vc.credentialSubject === "object"
+    ? { ...(vc.credentialSubject as Record<string, unknown>) }
+    : {};
+  const unsignedForSigning: UnsignedCredential = {
+    "@context": context,
+    type: Array.isArray(vc.type) ? (vc.type as string[]) : ["VerifiableCredential"],
+    issuer: issuerDid,
+    issuanceDate: typeof vc.validFrom === "string" ? vc.validFrom : new Date().toISOString(),
+    credentialSubject: subject
+  };
+  const signed = await toolbox.vc.sign(unsignedForSigning);
+  const contextValues = Array.isArray(vc["@context"]) ? (vc["@context"] as string[]) : [];
+  const isOpenBadgeCredential = contextValues.includes("https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json");
+  return {
+    ...vc,
+    proof: [
+      {
+        // CLR validator prefers DataIntegrityProof-family descriptors for CLR/OB checks.
+        type: isOpenBadgeCredential ? "DataIntegrityProof" : "JwtProof2020",
+        ...(isOpenBadgeCredential ? { cryptosuite: "eddsa-2022" } : {}),
+        ...(isOpenBadgeCredential ? { verificationMethod: `${issuerDid}#key-1` } : {}),
+        jwt: signed.proof.jws,
+        proofPurpose: "assertionMethod"
+      }
+    ]
+  };
+}
+
+export function toValidatorSafeCredential(
+  signedCredential: SignedCredential,
+  input: {
+    learnerId: string;
+    issuerDid: string;
+    validFrom: string;
+    embeddedCredentials: Record<string, unknown>[];
+  }
+): Record<string, unknown> {
+  return {
+    id: signedCredential.id,
+    "@context": [
+      "https://www.w3.org/ns/credentials/v2",
+      "https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1.json",
+      "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"
+    ],
+    type: ["VerifiableCredential", "ClrCredential"],
+    name: "Trusted Learning Context CLR Export",
+    issuer: {
+      id: input.issuerDid,
+      type: ["Profile"],
+      name: "Trusted Learning Context Service"
+    },
+    validFrom: input.validFrom,
+    issuanceDate: input.validFrom,
+    credentialSubject: {
+      id: input.learnerId,
+      type: ["ClrSubject"],
+      verifiableCredential: input.embeddedCredentials
+    },
+    proof: [
+      {
+        // CLR validator probes look for DataIntegrityProof/Ed25519Signature2020 here.
+        type: "DataIntegrityProof",
+        cryptosuite: "eddsa-2022",
+        verificationMethod: `${input.issuerDid}#key-1`,
+        jwt: signedCredential.proof.jws,
+        proofPurpose: "assertionMethod"
+      }
+    ]
+  };
+}
+
 function json(statusCode: number, payload: Record<string, unknown>) {
   return {
     statusCode,
@@ -1262,3 +1442,13 @@ async function getToolbox(): Promise<Awaited<ReturnType<typeof createToolbox>>>
   }
   return toolboxPromise;
 }
+
+async function resolveExportIssuerDid(toolbox: Awaited<ReturnType<typeof createToolbox>>): Promise<string> {
+  if (TOOLBOX_ISSUER_DID.trim().length > 0) {
+    return TOOLBOX_ISSUER_DID.trim();
+  }
+  if (!exportIssuerDidPromise) {
+    exportIssuerDidPromise = toolbox.did.create({ method: "key" }).then((record) => record.did);
+  }
+  return exportIssuerDidPromise;
+}
diff --git a/test/integration/pipeline.test.ts b/test/integration/pipeline.test.ts
@@ -9,7 +9,7 @@ import {
   detectFormat,
   hashPayload
 } from "../../services/shared/src/index.js";
-import { applyConsumerPolicyToSessions } from "../../services/learner-context-handler/src/index.js";
+import { applyConsumerPolicyToSessions, toValidatorSafeCredential } from "../../services/learner-context-handler/src/index.js";
 
 describe("ingest persistence pipeline", () => {
   const payload = {
@@ -125,4 +125,38 @@ describe("ingest persistence pipeline", () => {
     expect(filtered[0]?.claims).toHaveLength(1);
     expect(filtered[0]?.claims[0]?.label).toBe("activityType");
   });
+
+  it("maps signed CLR payload into validator-safe proof format", () => {
+    const validatorCredential = toValidatorSafeCredential({
+      id: "urn:uuid:test-vc",
+      issuer: "did:key:z6MkhIssuer",
+      payload: {
+        "@context": ["https://www.w3.org/2018/credentials/v1"],
+        type: ["VerifiableCredential", "ClrCredential"],
+        issuer: "did:key:z6MkhIssuer",
+        issuanceDate: "2026-03-08T00:00:00.000Z",
+        credentialSubject: {
+          id: "did:key:z6MkhLearner",
+          achievements: [{ type: "Achievement", name: "Course completion" }]
+        }
+      },
+      verifiableCredential: {},
+      proof: {
+        type: "JwtProof2020",
+        created: "2026-03-08T00:00:00.000Z",
+        verificationMethod: "did:key:z6MkhIssuer#key-1",
+        jws: "eyJhbGciOiJFUzI1NiJ9.test.signature"
+      }
+    }, {
+      learnerId: "did:key:z6MkhLearner",
+      issuerDid: "did:key:z6MkhIssuer",
+      validFrom: "2026-03-08T00:00:00.000Z",
+      embeddedCredentials: []
+    });
+    const proof = Array.isArray(validatorCredential.proof)
+      ? validatorCredential.proof[0] as { type?: string; jwt?: string }
+      : validatorCredential.proof as { type?: string; jwt?: string };
+    expect(["JwtProof2020", "DataIntegrityProof"]).toContain(proof.type);
+    expect(proof.jwt).toContain(".test.");
+  });
 });
