@learncard/helpers 1.3.3 → 1.3.5

package/dist/helpers.d.cts

@@ -444,6 +444,11 @@ declare const CredentialFormatValidator: z.ZodEnum<{
 	mso_mdoc: "mso_mdoc";
 }>;
 export type CredentialFormat = z.infer<typeof CredentialFormatValidator>;
+export type StoredCredentialEnvelope = {
+	format: CredentialFormat;
+	data: string | Uint8Array;
+	[key: string]: unknown;
+};
 /**
  * Format-discriminated read view over a stored credential. Returned
  * by `toStoredCredential(record)` in `@learncard/helpers`.
@@ -854,7 +859,7 @@ export declare const calculateAgeFromDob: (dob?: string | null) => number | null
  *    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
+ *    pre-date format-tagging, 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
@@ -865,11 +870,79 @@ export declare const calculateAgeFromDob: (dob?: string | null) => number | null
  * `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.
+ * This projector is the SAFETY NET that makes the format-tagging
+ * 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;
+/**
+ * Extract the meaningful identifying segment from an SD-JWT-VC `vct` claim
+ * so it can be projected onto the W3C-VC `type` array and `name` field.
+ *
+ * Returns `undefined` for vct values where no meaningful name can be
+ * derived (numeric-only URN tails, empty string). Shared between the
+ * receipt-time wrapper synthesizer and the read-time display projector
+ * so SD-JWT credentials produce the same wrapper shape on both paths.
+ */
+export declare const extractVctSegment: (vct: string) => string | undefined;
+/**
+ * PascalCase identifier suitable for the W3C-VC `type` array. Picks acronyms
+ * for short single-word lowercase segments ("pid" → "PID") and otherwise
+ * concatenates capitalized words ("playground-credential" → "PlaygroundCredential").
+ */
+export declare const deriveTypeFromVct: (vct: string | undefined) => string | undefined;
+/**
+ * Human-readable display name for the `name` field. Same input handling
+ * as {@link deriveTypeFromVct} but keeps spaces between words so it reads
+ * naturally in UIs ("Playground Credential" not "PlaygroundCredential").
+ */
+export declare const deriveNameFromVct: (vct: string | undefined) => string | undefined;
+export declare const stripSdJwtReservedClaims: (claims: Record<string, unknown>) => Record<string, unknown>;
+export declare const synthesizeDidJwk: (jwk: Record<string, unknown>) => string | undefined;
+export declare const deriveSdJwtIssuedAtIso: (options: {
+	issuedAt?: Date;
+	notBefore?: Date;
+	iat?: number;
+	nbf?: number;
+}) => string;
+/**
+ * Read-path shim: when a storage plugin returns a `StoredCredentialEnvelope` (because we
+ * wrote a native non-W3C format like SD-JWT-VC), legacy UI components
+ * that read `.credentialSubject` / `.issuer` / `.proof` need a VC-shaped
+ * object. This projector synthesizes a minimal display-only VC from the
+ * envelope so existing consumers keep working without per-component
+ * format awareness.
+ *
+ * For SD-JWT-VC: decodes the unsigned JWS payload (signature is NOT
+ * verified here — verification belongs to the dedicated verify chain),
+ * surfaces the disclosed claims under `credentialSubject`, preserves
+ * the compact form under `proof.jwt` and `proof.type = 'SdJwtCompactProof'`
+ * so anything that already understands the SD-JWT-Compact-Proof shape
+ * keeps working.
+ *
+ * For JWT-VC: decodes the JWS payload, returns its `vc` claim.
+ *
+ * For mDoc / unknown formats: returns `undefined` — the caller MUST
+ * branch on format (`record.format === 'mso_mdoc'`) and use a
+ * format-specific display path. We don't fabricate a fake VC for
+ * binary credentials.
+ *
+ * This projector is intentionally LOSSY for SD-JWT — it produces a
+ * display-only view, NOT a re-issuable credential. Egress paths
+ * (sharing, presenting, re-uploading) MUST go through
+ * `serializeForWire(stored)` (Phase 3) to recover the canonical
+ * compact form from `envelope.data`. NEVER re-serialize from the
+ * projected VC.
+ */
+export declare const projectEnvelopeToDisplayVc: (envelope: StoredCredentialEnvelope) => VC | undefined;
+/**
+ * Convenience: detect an envelope on the wire and return a legacy VC
+ * shape suitable for downstream W3C-only consumers. Returns the input
+ * unchanged if it's not an envelope (so callers can wrap any
+ * `read.get` result without branching themselves).
+ */
+export declare const resolveStorageReadResult: (value: VC | StoredCredentialEnvelope | undefined) => VC | StoredCredentialEnvelope | undefined;
 /**
  * Determines whether or not a string is a valid hexadecimal string
  *

package/dist/helpers.d.ts

@@ -444,6 +444,11 @@ declare const CredentialFormatValidator: z.ZodEnum<{
 	mso_mdoc: "mso_mdoc";
 }>;
 export type CredentialFormat = z.infer<typeof CredentialFormatValidator>;
+export type StoredCredentialEnvelope = {
+	format: CredentialFormat;
+	data: string | Uint8Array;
+	[key: string]: unknown;
+};
 /**
  * Format-discriminated read view over a stored credential. Returned
  * by `toStoredCredential(record)` in `@learncard/helpers`.
@@ -854,7 +859,7 @@ export declare const calculateAgeFromDob: (dob?: string | null) => number | null
  *    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
+ *    pre-date format-tagging, 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
@@ -865,11 +870,79 @@ export declare const calculateAgeFromDob: (dob?: string | null) => number | null
  * `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.
+ * This projector is the SAFETY NET that makes the format-tagging
+ * 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;
+/**
+ * Extract the meaningful identifying segment from an SD-JWT-VC `vct` claim
+ * so it can be projected onto the W3C-VC `type` array and `name` field.
+ *
+ * Returns `undefined` for vct values where no meaningful name can be
+ * derived (numeric-only URN tails, empty string). Shared between the
+ * receipt-time wrapper synthesizer and the read-time display projector
+ * so SD-JWT credentials produce the same wrapper shape on both paths.
+ */
+export declare const extractVctSegment: (vct: string) => string | undefined;
+/**
+ * PascalCase identifier suitable for the W3C-VC `type` array. Picks acronyms
+ * for short single-word lowercase segments ("pid" → "PID") and otherwise
+ * concatenates capitalized words ("playground-credential" → "PlaygroundCredential").
+ */
+export declare const deriveTypeFromVct: (vct: string | undefined) => string | undefined;
+/**
+ * Human-readable display name for the `name` field. Same input handling
+ * as {@link deriveTypeFromVct} but keeps spaces between words so it reads
+ * naturally in UIs ("Playground Credential" not "PlaygroundCredential").
+ */
+export declare const deriveNameFromVct: (vct: string | undefined) => string | undefined;
+export declare const stripSdJwtReservedClaims: (claims: Record<string, unknown>) => Record<string, unknown>;
+export declare const synthesizeDidJwk: (jwk: Record<string, unknown>) => string | undefined;
+export declare const deriveSdJwtIssuedAtIso: (options: {
+	issuedAt?: Date;
+	notBefore?: Date;
+	iat?: number;
+	nbf?: number;
+}) => string;
+/**
+ * Read-path shim: when a storage plugin returns a `StoredCredentialEnvelope` (because we
+ * wrote a native non-W3C format like SD-JWT-VC), legacy UI components
+ * that read `.credentialSubject` / `.issuer` / `.proof` need a VC-shaped
+ * object. This projector synthesizes a minimal display-only VC from the
+ * envelope so existing consumers keep working without per-component
+ * format awareness.
+ *
+ * For SD-JWT-VC: decodes the unsigned JWS payload (signature is NOT
+ * verified here — verification belongs to the dedicated verify chain),
+ * surfaces the disclosed claims under `credentialSubject`, preserves
+ * the compact form under `proof.jwt` and `proof.type = 'SdJwtCompactProof'`
+ * so anything that already understands the SD-JWT-Compact-Proof shape
+ * keeps working.
+ *
+ * For JWT-VC: decodes the JWS payload, returns its `vc` claim.
+ *
+ * For mDoc / unknown formats: returns `undefined` — the caller MUST
+ * branch on format (`record.format === 'mso_mdoc'`) and use a
+ * format-specific display path. We don't fabricate a fake VC for
+ * binary credentials.
+ *
+ * This projector is intentionally LOSSY for SD-JWT — it produces a
+ * display-only view, NOT a re-issuable credential. Egress paths
+ * (sharing, presenting, re-uploading) MUST go through
+ * `serializeForWire(stored)` (Phase 3) to recover the canonical
+ * compact form from `envelope.data`. NEVER re-serialize from the
+ * projected VC.
+ */
+export declare const projectEnvelopeToDisplayVc: (envelope: StoredCredentialEnvelope) => VC | undefined;
+/**
+ * Convenience: detect an envelope on the wire and return a legacy VC
+ * shape suitable for downstream W3C-only consumers. Returns the input
+ * unchanged if it's not an envelope (so callers can wrap any
+ * `read.get` result without branching themselves).
+ */
+export declare const resolveStorageReadResult: (value: VC | StoredCredentialEnvelope | undefined) => VC | StoredCredentialEnvelope | undefined;
 /**
  * Determines whether or not a string is a valid hexadecimal string
  *