@learncard/helpers 1.3.1 → 1.3.3

package/dist/helpers.d.ts

@@ -435,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;
@@ -769,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

@@ -29,9 +29,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// ../learn-card-types/dist/types.cjs.development.js
+// ../learn-card-types/dist/types.cjs.development.cjs
 var require_types_cjs_development = __commonJS({
-  "../learn-card-types/dist/types.cjs.development.js"(exports, module) {
+  "../learn-card-types/dist/types.cjs.development.cjs"(exports, module) {
     "use strict";
     var __defProp2 = Object.defineProperty;
     var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
@@ -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"),
@@ -14116,6 +14119,14 @@ 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.
@@ -14171,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(),
@@ -14739,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()
     });
@@ -14825,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(),
@@ -15588,9 +15618,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
   }
 });
 
-// ../learn-card-types/dist/index.js
+// ../learn-card-types/dist/index.cjs
 var require_dist = __commonJS({
-  "../learn-card-types/dist/index.js"(exports, module) {
+  "../learn-card-types/dist/index.cjs"(exports, module) {
     "use strict";
     if (false) {
       module.exports = null;
@@ -16538,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) => {
@@ -16629,5 +16731,6 @@ export {
   quantizeValue,
   resizeAndChangeQuality4 as resizeAndChangeQuality,
   setBitstringStatusListBit,
+  toStoredCredential,
   unwrapBoostCredential
 };