@learncard/helpers 1.3.0 → 1.3.2

package/dist/helpers.d.ts

@@ -181,6 +181,32 @@ declare const UnsignedVCValidator: z.ZodObject<{
 			audience: z.ZodOptional<z.ZodString>;
 		}, z.core.$catchall<z.ZodAny>>>
 	]>>;
+	renderMethod: z.ZodOptional<z.ZodUnion<readonly [
+		z.ZodUnion<readonly [
+			z.ZodObject<{
+				type: z.ZodLiteral<"TemplateRenderMethod">;
+				renderSuite: z.ZodString;
+				template: z.ZodString;
+				renderProperty: z.ZodOptional<z.ZodArray<z.ZodString>>;
+				outputPreference: z.ZodOptional<z.ZodObject<{
+					mediaType: z.ZodString;
+				}, z.core.$strip>>;
+			}, z.core.$strip>,
+			z.ZodRecord<z.ZodString, z.ZodAny>
+		]>,
+		z.ZodArray<z.ZodUnion<readonly [
+			z.ZodObject<{
+				type: z.ZodLiteral<"TemplateRenderMethod">;
+				renderSuite: z.ZodString;
+				template: z.ZodString;
+				renderProperty: z.ZodOptional<z.ZodArray<z.ZodString>>;
+				outputPreference: z.ZodOptional<z.ZodObject<{
+					mediaType: z.ZodString;
+				}, z.core.$strip>>;
+			}, z.core.$strip>,
+			z.ZodRecord<z.ZodString, z.ZodAny>
+		]>>
+	]>>;
 }, z.core.$catchall<z.ZodAny>>;
 export type UnsignedVC = z.infer<typeof UnsignedVCValidator>;
 declare const VCValidator: z.ZodObject<{
@@ -359,6 +385,32 @@ declare const VCValidator: z.ZodObject<{
 			audience: z.ZodOptional<z.ZodString>;
 		}, z.core.$catchall<z.ZodAny>>>
 	]>>;
+	renderMethod: z.ZodOptional<z.ZodUnion<readonly [
+		z.ZodUnion<readonly [
+			z.ZodObject<{
+				type: z.ZodLiteral<"TemplateRenderMethod">;
+				renderSuite: z.ZodString;
+				template: z.ZodString;
+				renderProperty: z.ZodOptional<z.ZodArray<z.ZodString>>;
+				outputPreference: z.ZodOptional<z.ZodObject<{
+					mediaType: z.ZodString;
+				}, z.core.$strip>>;
+			}, z.core.$strip>,
+			z.ZodRecord<z.ZodString, z.ZodAny>
+		]>,
+		z.ZodArray<z.ZodUnion<readonly [
+			z.ZodObject<{
+				type: z.ZodLiteral<"TemplateRenderMethod">;
+				renderSuite: z.ZodString;
+				template: z.ZodString;
+				renderProperty: z.ZodOptional<z.ZodArray<z.ZodString>>;
+				outputPreference: z.ZodOptional<z.ZodObject<{
+					mediaType: z.ZodString;
+				}, z.core.$strip>>;
+			}, z.core.$strip>,
+			z.ZodRecord<z.ZodString, z.ZodAny>
+		]>>
+	]>>;
 	proof: z.ZodUnion<[
 		z.ZodObject<{
 			type: z.ZodString;
@@ -383,6 +435,81 @@ declare const VCValidator: z.ZodObject<{
 	]>;
 }, z.core.$catchall<z.ZodAny>>;
 export type VC = z.infer<typeof VCValidator>;
+declare const CredentialFormatValidator: z.ZodEnum<{
+	"w3c-vc-2.0": "w3c-vc-2.0";
+	"w3c-vc-1.1": "w3c-vc-1.1";
+	"jwt-vc-json": "jwt-vc-json";
+	"dc+sd-jwt": "dc+sd-jwt";
+	"vc+sd-jwt": "vc+sd-jwt";
+	mso_mdoc: "mso_mdoc";
+}>;
+export type CredentialFormat = z.infer<typeof CredentialFormatValidator>;
+/**
+ * Format-discriminated read view over a stored credential. Returned
+ * by `toStoredCredential(record)` in `@learncard/helpers`.
+ *
+ * The `data` field carries the correct wire-form representation for
+ * the credential's format:
+ *   - W3C VCs: the JSON-LD VC object (also what `record.vc` holds)
+ *   - JWT-VC: the compact JWS string (extracted from `record.vc.proof.jwt`
+ *     if the record uses the legacy LDP-around-JWT envelope, otherwise
+ *     the raw string from `record.rawWireForm`)
+ *   - SD-JWT-VC: the compact `<JWT>~<disclosures>~` string
+ *   - mDoc: base64url-encoded CBOR bytes (stored as a string for
+ *     LearnCloud's JSON-only encrypted store; consumers base64-decode
+ *     when they need raw bytes)
+ *
+ * Format-aware consumers pattern-match on `format` and use `data`.
+ * Legacy consumers continue to read `record.vc` directly — the
+ * projector is opt-in, never required.
+ */
+export type StoredCredential = {
+	format: "w3c-vc-2.0";
+	data: VC;
+} | {
+	format: "w3c-vc-1.1";
+	data: VC;
+} | {
+	format: "jwt-vc-json";
+	data: string;
+} | {
+	format: "dc+sd-jwt";
+	data: string;
+} | {
+	format: "vc+sd-jwt";
+	data: string;
+} | {
+	format: "mso_mdoc";
+	data: string;
+};
+export type CredentialRecord<Metadata extends Record<string, any> = Record<never, never>> = {
+	id: string;
+	uri: string;
+	/**
+	 * Wire-format discriminator for the credential. Optional — when
+	 * absent, legacy readers infer it from `vc` shape (see
+	 * `toStoredCredential` in `@learncard/helpers`). Populated on new
+	 * writes once the consumer is format-aware.
+	 *
+	 * Added in ADR-0001 Phase 1 as additive metadata; existing
+	 * records without this field continue to work unchanged.
+	 */
+	format?: CredentialFormat;
+	/**
+	 * Optional semantic type hint for fast filtering without parsing
+	 * the full credential — `vct` for SD-JWT-VC, last-non-VC type for
+	 * W3C VCs, doctype for mDoc. Added in ADR-0001 Phase 1.
+	 */
+	semanticType?: string;
+	/**
+	 * On-the-wire representation for formats whose `vc` field cannot
+	 * hold the canonical form (SD-JWT compact, JWT-VC compact, base64
+	 * mDoc CBOR). Undefined for W3C VCs (`vc` IS the wire form). Added
+	 * in ADR-0001 Phase 1.
+	 */
+	rawWireForm?: string;
+	[key: string]: any;
+} & Metadata;
 declare const JWEValidator: z.ZodObject<{
 	protected: z.ZodString;
 	iv: z.ZodString;
@@ -717,6 +844,32 @@ export declare const AGE_RATING_TO_MIN_AGE: Record<string, number>;
  * @returns Age in years, or null if the date is invalid
  */
 export declare const calculateAgeFromDob: (dob?: string | null) => number | null;
+/**
+ * Project a `CredentialRecord` into a format-discriminated read view.
+ *
+ * Two paths into the same output:
+ *
+ * 1. **Explicit format**: if the record carries an explicit `format`
+ *    discriminator (and `rawWireForm` where required), the projector
+ *    trusts it. This is the path new format-aware writers take.
+ *
+ * 2. **Inferred from shape** (legacy fallback): for records that
+ *    pre-date ADR-0001 Phase 1, the projector inspects `record.vc` and
+ *    infers the format. W3C VCs → `w3c-vc-2.0` / `w3c-vc-1.1` based
+ *    on `@context`; transitional SD-JWT wrappers (which never shipped
+ *    but exist on branch `lc-1796-3`) → `dc+sd-jwt` with the compact
+ *    extracted from `proof.jwt`; legacy JWT-VC envelopes → `jwt-vc-json`.
+ *
+ * Returns a `StoredCredential` for every conceivable record. Never
+ * throws — credentials with unrecognizable shape fall back to
+ * `w3c-vc-1.1` with `data = record.vc` so legacy consumers keep
+ * something they can read.
+ *
+ * This projector is the SAFETY NET that makes the ADR-0001 migration
+ * non-breaking: writers can adopt format-tagging at their own pace;
+ * readers using this projector see the right discriminator either way.
+ */
+export declare const toStoredCredential: (record: CredentialRecord) => StoredCredential;
 /**
  * Determines whether or not a string is a valid hexadecimal string
  *

package/dist/helpers.esm.js

@@ -141,6 +141,7 @@ var require_types_cjs_development = __commonJS({
       CredentialActivityStatsValidator: /* @__PURE__ */ __name(() => CredentialActivityStatsValidator, "CredentialActivityStatsValidator"),
       CredentialActivityValidator: /* @__PURE__ */ __name(() => CredentialActivityValidator, "CredentialActivityValidator"),
       CredentialActivityWithDetailsValidator: /* @__PURE__ */ __name(() => CredentialActivityWithDetailsValidator, "CredentialActivityWithDetailsValidator"),
+      CredentialFormatValidator: /* @__PURE__ */ __name(() => CredentialFormatValidator, "CredentialFormatValidator"),
       CredentialInfoValidator: /* @__PURE__ */ __name(() => CredentialInfoValidator, "CredentialInfoValidator"),
       CredentialNameRefValidator: /* @__PURE__ */ __name(() => CredentialNameRefValidator, "CredentialNameRefValidator"),
       CredentialRecordValidator: /* @__PURE__ */ __name(() => CredentialRecordValidator, "CredentialRecordValidator"),
@@ -169,6 +170,8 @@ var require_types_cjs_development = __commonJS({
       GetSkillPathResultValidator: /* @__PURE__ */ __name(() => GetSkillPathResultValidator, "GetSkillPathResultValidator"),
       GetTemplateRecipientsEventValidator: /* @__PURE__ */ __name(() => GetTemplateRecipientsEventValidator, "GetTemplateRecipientsEventValidator"),
       GuardianStatusValidator: /* @__PURE__ */ __name(() => GuardianStatusValidator, "GuardianStatusValidator"),
+      HolderExportConsentRecordValidator: /* @__PURE__ */ __name(() => HolderExportConsentRecordValidator, "HolderExportConsentRecordValidator"),
+      HolderExportMetadataValidator: /* @__PURE__ */ __name(() => HolderExportMetadataValidator, "HolderExportMetadataValidator"),
       IdentifierEntryValidator: /* @__PURE__ */ __name(() => IdentifierEntryValidator, "IdentifierEntryValidator"),
       IdentifierTypeValidator: /* @__PURE__ */ __name(() => IdentifierTypeValidator, "IdentifierTypeValidator"),
       IdentityObjectValidator: /* @__PURE__ */ __name(() => IdentityObjectValidator, "IdentityObjectValidator"),
@@ -248,6 +251,7 @@ var require_types_cjs_development = __commonJS({
       RefreshServiceValidator: /* @__PURE__ */ __name(() => RefreshServiceValidator, "RefreshServiceValidator"),
       RegExpValidator: /* @__PURE__ */ __name(() => RegExpValidator, "RegExpValidator"),
       RelatedValidator: /* @__PURE__ */ __name(() => RelatedValidator, "RelatedValidator"),
+      RenderMethodValidator: /* @__PURE__ */ __name(() => RenderMethodValidator, "RenderMethodValidator"),
       ReplaceSkillFrameworkSkillsInputValidator: /* @__PURE__ */ __name(() => ReplaceSkillFrameworkSkillsInputValidator, "ReplaceSkillFrameworkSkillsInputValidator"),
       ReplaceSkillFrameworkSkillsResultValidator: /* @__PURE__ */ __name(() => ReplaceSkillFrameworkSkillsResultValidator, "ReplaceSkillFrameworkSkillsResultValidator"),
       RequestLearnerContextEventValidator: /* @__PURE__ */ __name(() => RequestLearnerContextEventValidator, "RequestLearnerContextEventValidator"),
@@ -290,6 +294,7 @@ var require_types_cjs_development = __commonJS({
       SummaryCredentialKeywordValidator: /* @__PURE__ */ __name(() => SummaryCredentialKeywordValidator, "SummaryCredentialKeywordValidator"),
       SyncFrameworkInputValidator: /* @__PURE__ */ __name(() => SyncFrameworkInputValidator, "SyncFrameworkInputValidator"),
       TagValidator: /* @__PURE__ */ __name(() => TagValidator, "TagValidator"),
+      TemplateRenderMethodValidator: /* @__PURE__ */ __name(() => TemplateRenderMethodValidator, "TemplateRenderMethodValidator"),
       TermsOfUseValidator: /* @__PURE__ */ __name(() => TermsOfUseValidator, "TermsOfUseValidator"),
       UnsignedAchievementCredentialValidator: /* @__PURE__ */ __name(() => UnsignedAchievementCredentialValidator, "UnsignedAchievementCredentialValidator"),
       UnsignedClrCredentialValidator: /* @__PURE__ */ __name(() => UnsignedClrCredentialValidator, "UnsignedClrCredentialValidator"),
@@ -13769,6 +13774,19 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       genre: external_exports.string().optional(),
       audience: external_exports.string().optional()
     }).catchall(external_exports.any());
+    var TemplateRenderMethodValidator = external_exports.object({
+      type: external_exports.literal("TemplateRenderMethod"),
+      renderSuite: external_exports.string(),
+      template: external_exports.string(),
+      renderProperty: external_exports.array(external_exports.string()).optional(),
+      outputPreference: external_exports.object({
+        mediaType: external_exports.string()
+      }).optional()
+    });
+    var RenderMethodValidator = external_exports.union([
+      TemplateRenderMethodValidator,
+      external_exports.record(external_exports.string(), external_exports.any())
+    ]);
     var UnsignedVCValidator = external_exports.object({
       "@context": ContextValidator,
       id: external_exports.string().optional(),
@@ -13792,7 +13810,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       validUntil: external_exports.string().optional(),
       status: CredentialStatusValidator.or(CredentialStatusValidator.array()).optional(),
       termsOfUse: TermsOfUseValidator.or(TermsOfUseValidator.array()).optional(),
-      evidence: external_exports.union([VC2EvidenceValidator, external_exports.array(VC2EvidenceValidator)]).optional()
+      evidence: external_exports.union([VC2EvidenceValidator, external_exports.array(VC2EvidenceValidator)]).optional(),
+      renderMethod: external_exports.union([RenderMethodValidator, external_exports.array(RenderMethodValidator)]).optional()
     }).catchall(external_exports.any());
     var ProofValidator = external_exports.object({
       type: external_exports.string(),
@@ -14100,17 +14119,52 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     var ClrCredentialValidator = UnsignedClrCredentialValidator.extend({
       proof: ProofValidator.or(ProofValidator.array())
     });
+    var CredentialFormatValidator = external_exports.enum([
+      "w3c-vc-2.0",
+      "w3c-vc-1.1",
+      "jwt-vc-json",
+      "dc+sd-jwt",
+      "vc+sd-jwt",
+      "mso_mdoc"
+    ]);
     var StatusCheckEntryValidator = external_exports.object({
+      /**
+       * The `credentialStatus.type` as it appeared on the credential.
+       * One of `BitstringStatusListEntry`, `StatusList2021Entry`,
+       * `RevocationList2020Status`, or any future custom status type.
+       */
       entryType: external_exports.string(),
+      /**
+       * The claimed purpose of the entry. Standard values are
+       * `"revocation"` and `"suspension"`; the spec allows arbitrary
+       * strings.
+       */
       statusPurpose: external_exports.string(),
+      /**
+       * Whether the bit at the credential's index in the status list
+       * bitstring was set.
+       */
       isSet: external_exports.boolean(),
+      /** URL of the status list credential, when known. */
       statusListCredential: external_exports.string().optional(),
+      /** Original (string) index within the status list. */
       statusListIndex: external_exports.string().optional()
     });
     var VerificationCheckValidator = external_exports.object({
       checks: external_exports.string().array(),
       warnings: external_exports.string().array(),
       errors: external_exports.string().array(),
+      /**
+       * Per-entry results for the `credentialStatus` check, populated
+       * by `@learncard/didkit-plugin` when the verified credential
+       * carries one or more `credentialStatus` entries. Empty / absent
+       * for credentials without a status entry.
+       *
+       * Marked `.optional()` because the underlying `ssi-ldp`
+       * serializer omits the field when empty (`skip_serializing_if`),
+       * so older WASM builds that pre-date the structured-status
+       * change still validate against this schema.
+       */
       status: StatusCheckEntryValidator.array().optional()
     });
     var VerificationStatusValidator = external_exports.enum(["Success", "Failed", "Error"]);
@@ -14128,7 +14182,13 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       issuee: ProfileValidator.optional(),
       credentialSubject: CredentialSubjectValidator.optional()
     });
-    var CredentialRecordValidator = external_exports.object({ id: external_exports.string(), uri: external_exports.string() }).catchall(external_exports.any());
+    var CredentialRecordValidator = external_exports.object({
+      id: external_exports.string(),
+      uri: external_exports.string(),
+      format: CredentialFormatValidator.optional(),
+      semanticType: external_exports.string().optional(),
+      rawWireForm: external_exports.string().optional()
+    }).catchall(external_exports.any());
     var PaginationOptionsValidator = external_exports.object({
       limit: external_exports.number(),
       cursor: external_exports.string().optional(),
@@ -14696,6 +14756,22 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       date: external_exports.string(),
       uris: external_exports.string().array().optional()
     });
+    var HolderExportConsentRecordValidator = external_exports.object({
+      termsUri: external_exports.string(),
+      status: ConsentFlowTermsStatusValidator,
+      contract: ConsentFlowContractDetailsValidator,
+      terms: ConsentFlowTermsValidator,
+      transactions: ConsentFlowTransactionValidator.array()
+    });
+    var HolderExportMetadataValidator = external_exports.object({
+      consentRecords: HolderExportConsentRecordValidator.array(),
+      truncated: external_exports.boolean().optional(),
+      warnings: external_exports.string().array().optional(),
+      limits: external_exports.object({
+        maxConsentRecords: external_exports.number(),
+        maxTransactionsPerConsentRecord: external_exports.number()
+      }).optional()
+    });
     var PaginatedConsentFlowTransactionsValidator = PaginationResponseValidator.extend({
       records: ConsentFlowTransactionValidator.array()
     });
@@ -14782,10 +14858,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     var LCNNotificationValidator = external_exports.object({
       type: LCNNotificationTypeEnumValidator,
       to: LCNProfileValidator.partial().and(external_exports.object({ did: external_exports.string() })),
-      from: external_exports.union([
-        external_exports.string(),
-        LCNProfileValidator.partial().and(external_exports.object({ did: external_exports.string() }))
-      ]),
+      from: external_exports.union([external_exports.string(), LCNProfileValidator.partial().and(external_exports.object({ did: external_exports.string() }))]),
       message: LCNNotificationMessageValidator.optional(),
       data: LCNNotificationDataValidator.optional(),
       sent: external_exports.iso.datetime().optional(),
@@ -16495,6 +16568,78 @@ var calculateAgeFromDob = /* @__PURE__ */ __name((dob) => {
   return age;
 }, "calculateAgeFromDob");
 
+// src/credential-format.ts
+var toStoredCredential = /* @__PURE__ */ __name((record) => {
+  if (record.format) {
+    if (record.format === "dc+sd-jwt" || record.format === "vc+sd-jwt" || record.format === "jwt-vc-json" || record.format === "mso_mdoc") {
+      const wireForm = record.rawWireForm ?? extractWireFormFromVc(record.vc);
+      if (typeof wireForm === "string" && wireForm.length > 0) {
+        return { format: record.format, data: wireForm };
+      }
+    }
+    if (record.format === "w3c-vc-2.0" || record.format === "w3c-vc-1.1") {
+      return { format: record.format, data: record.vc };
+    }
+  }
+  const vc = record.vc;
+  if (typeof vc === "string") {
+    if (looksLikeSdJwtCompact(vc)) {
+      return { format: "dc+sd-jwt", data: vc };
+    }
+    if (looksLikeJwsCompact(vc)) {
+      return { format: "jwt-vc-json", data: vc };
+    }
+  }
+  if (vc && typeof vc === "object") {
+    const proof = getWireFormProof(vc, true);
+    const wireFromProof = getWireFormFromProof(proof);
+    if (wireFromProof) {
+      const proofType = proof?.type;
+      if (proofType === "SdJwtCompactProof") {
+        return { format: "dc+sd-jwt", data: wireFromProof };
+      }
+      if (proofType === "JwtProof2020") {
+        return { format: "jwt-vc-json", data: wireFromProof };
+      }
+    }
+    const inferred = inferW3cVersionFromContext(vc);
+    return { format: inferred, data: vc };
+  }
+  return { format: "w3c-vc-1.1", data: vc };
+}, "toStoredCredential");
+var SD_JWT_COMPACT_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+~/;
+var JWS_COMPACT_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+var looksLikeSdJwtCompact = /* @__PURE__ */ __name((value) => SD_JWT_COMPACT_RE.test(value), "looksLikeSdJwtCompact");
+var looksLikeJwsCompact = /* @__PURE__ */ __name((value) => JWS_COMPACT_RE.test(value), "looksLikeJwsCompact");
+var getWireFormProof = /* @__PURE__ */ __name((vc, requireSupportedType = false) => {
+  if (!vc || typeof vc !== "object") return void 0;
+  const proof = vc.proof;
+  if (Array.isArray(proof)) {
+    for (const entry of proof) {
+      const proofObject2 = asWireFormProof(entry);
+      if (proofObject2 && isUsableWireFormProof(proofObject2, requireSupportedType)) {
+        return proofObject2;
+      }
+    }
+    return void 0;
+  }
+  const proofObject = asWireFormProof(proof);
+  return proofObject && isUsableWireFormProof(proofObject, requireSupportedType) ? proofObject : void 0;
+}, "getWireFormProof");
+var asWireFormProof = /* @__PURE__ */ __name((proof) => proof && typeof proof === "object" ? proof : void 0, "asWireFormProof");
+var isUsableWireFormProof = /* @__PURE__ */ __name((proof, requireSupportedType) => typeof proof.jwt === "string" && proof.jwt.length > 0 && (!requireSupportedType || proof.type === "SdJwtCompactProof" || proof.type === "JwtProof2020"), "isUsableWireFormProof");
+var getWireFormFromProof = /* @__PURE__ */ __name((proof) => typeof proof?.jwt === "string" && proof.jwt.length > 0 ? proof.jwt : void 0, "getWireFormFromProof");
+var extractWireFormFromVc = /* @__PURE__ */ __name((vc) => getWireFormFromProof(getWireFormProof(vc)), "extractWireFormFromVc");
+var inferW3cVersionFromContext = /* @__PURE__ */ __name((vc) => {
+  if (!vc || typeof vc !== "object") return "w3c-vc-1.1";
+  const contextRaw = vc["@context"];
+  const contexts = Array.isArray(contextRaw) ? contextRaw : contextRaw !== void 0 ? [contextRaw] : [];
+  const isV2 = contexts.some(
+    (c) => typeof c === "string" && c.includes("w3.org/ns/credentials/v2")
+  );
+  return isV2 ? "w3c-vc-2.0" : "w3c-vc-1.1";
+}, "inferW3cVersionFromContext");
+
 // src/index.ts
 var isHex = /* @__PURE__ */ __name((str) => /^[0-9a-f]+$/i.test(str), "isHex");
 var isEncrypted = /* @__PURE__ */ __name((item) => {
@@ -16586,5 +16731,6 @@ export {
   quantizeValue,
   resizeAndChangeQuality4 as resizeAndChangeQuality,
   setBitstringStatusListBit,
+  toStoredCredential,
   unwrapBoostCredential
 };