@sd-jwt/sd-jwt-vc 0.17.2-next.0 → 0.17.2-next.10

package/dist/index.d.mts

@@ -1,139 +1,278 @@
 import { SDJWTConfig, Verifier, kbPayload, kbHeader, DisclosureFrame } from '@sd-jwt/types';
+import { z } from 'zod';
 import { SdJwtPayload, SDJwtInstance, VerifierOptions } from '@sd-jwt/core';
 
 /**
  * Logo metadata used in rendering a credential.
  */
-type Logo = {
-    /** REQUIRED. A URI pointing to the logo image. */
-    uri: string;
-    /** OPTIONAL. An "integrity metadata" string as described in Section 7. */
-    'uri#integrity'?: string;
-    /** OPTIONAL. A string containing alternative text for the logo image. */
-    alt_text?: string;
-};
+declare const LogoSchema: z.ZodObject<{
+    uri: z.ZodString;
+    'uri#integrity': z.ZodOptional<z.ZodString>;
+    alt_text: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Logo = z.infer<typeof LogoSchema>;
 /**
  * The simple rendering method is intended for applications that do not support SVG.
  */
-type SimpleRendering = {
-    /** OPTIONAL. Logo metadata to display for the credential. */
-    logo?: Logo;
-    /** OPTIONAL. RGB color value for the credential background (e.g., "#FFFFFF"). */
-    background_color?: string;
-    /** OPTIONAL. RGB color value for the credential text (e.g., "#000000"). */
-    text_color?: string;
-};
+declare const SimpleRenderingSchema: z.ZodObject<{
+    logo: z.ZodOptional<z.ZodObject<{
+        uri: z.ZodString;
+        'uri#integrity': z.ZodOptional<z.ZodString>;
+        alt_text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    background_color: z.ZodOptional<z.ZodString>;
+    text_color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SimpleRendering = z.infer<typeof SimpleRenderingSchema>;
 /** Enum of valid values for rendering orientation. */
-type Orientation = 'portrait' | 'landscape';
+declare const OrientationSchema: z.ZodEnum<{
+    portrait: "portrait";
+    landscape: "landscape";
+}>;
 /** Enum of valid values for rendering color schemes. */
-type ColorScheme = 'light' | 'dark';
+declare const ColorSchemeSchema: z.ZodEnum<{
+    light: "light";
+    dark: "dark";
+}>;
 /** Enum of valid values for rendering contrast. */
-type Contrast = 'normal' | 'high';
+declare const ContrastSchema: z.ZodEnum<{
+    normal: "normal";
+    high: "high";
+}>;
 /**
  * Properties that describe the display preferences for an SVG template rendering.
  */
-type SvgTemplateProperties = {
-    /** OPTIONAL. Orientation optimized for the template. */
-    orientation?: Orientation;
-    /** OPTIONAL. Color scheme optimized for the template. */
-    color_scheme?: ColorScheme;
-    /** OPTIONAL. Contrast level optimized for the template. */
-    contrast?: Contrast;
-};
+declare const SvgTemplatePropertiesSchema: z.ZodObject<{
+    orientation: z.ZodOptional<z.ZodEnum<{
+        portrait: "portrait";
+        landscape: "landscape";
+    }>>;
+    color_scheme: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+    }>>;
+    contrast: z.ZodOptional<z.ZodEnum<{
+        normal: "normal";
+        high: "high";
+    }>>;
+}, z.core.$strip>;
+type SvgTemplateProperties = z.infer<typeof SvgTemplatePropertiesSchema>;
 /**
  * SVG rendering metadata containing URI and optional integrity and properties.
  */
-type SvgTemplateRendering = {
-    /** REQUIRED. A URI pointing to the SVG template. */
-    uri: string;
-    /** OPTIONAL. An "integrity metadata" string as described in Section 7. */
-    'uri#integrity'?: string;
-    /** REQUIRED if more than one SVG template is present. */
-    properties?: SvgTemplateProperties;
-};
+declare const SvgTemplateRenderingSchema: z.ZodObject<{
+    uri: z.ZodString;
+    'uri#integrity': z.ZodOptional<z.ZodString>;
+    properties: z.ZodOptional<z.ZodObject<{
+        orientation: z.ZodOptional<z.ZodEnum<{
+            portrait: "portrait";
+            landscape: "landscape";
+        }>>;
+        color_scheme: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+        }>>;
+        contrast: z.ZodOptional<z.ZodEnum<{
+            normal: "normal";
+            high: "high";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type SvgTemplateRendering = z.infer<typeof SvgTemplateRenderingSchema>;
 /**
  * Rendering metadata, either simple or SVG-based, for a credential.
  */
-type Rendering = {
-    /** OPTIONAL. Simple rendering metadata. */
-    simple?: SimpleRendering;
-    /** OPTIONAL. Array of SVG template rendering objects. */
-    svg_template?: SvgTemplateRendering[];
-};
+declare const RenderingSchema: z.ZodObject<{
+    simple: z.ZodOptional<z.ZodObject<{
+        logo: z.ZodOptional<z.ZodObject<{
+            uri: z.ZodString;
+            'uri#integrity': z.ZodOptional<z.ZodString>;
+            alt_text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        background_color: z.ZodOptional<z.ZodString>;
+        text_color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    svg_template: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+        'uri#integrity': z.ZodOptional<z.ZodString>;
+        properties: z.ZodOptional<z.ZodObject<{
+            orientation: z.ZodOptional<z.ZodEnum<{
+                portrait: "portrait";
+                landscape: "landscape";
+            }>>;
+            color_scheme: z.ZodOptional<z.ZodEnum<{
+                light: "light";
+                dark: "dark";
+            }>>;
+            contrast: z.ZodOptional<z.ZodEnum<{
+                normal: "normal";
+                high: "high";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type Rendering = z.infer<typeof RenderingSchema>;
 /**
  * Display metadata associated with a credential type.
  */
-type Display = {
-    /** REQUIRED. Language tag according to RFC 5646 (e.g., "en", "de"). */
-    lang: string;
-    /** REQUIRED. Human-readable name for the credential type. */
-    name: string;
-    /** OPTIONAL. Description of the credential type for end users. */
-    description?: string;
-    /** OPTIONAL. Rendering information (simple or SVG) for the credential. */
-    rendering?: Rendering;
-};
+declare const DisplaySchema: z.ZodObject<{
+    lang: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    rendering: z.ZodOptional<z.ZodObject<{
+        simple: z.ZodOptional<z.ZodObject<{
+            logo: z.ZodOptional<z.ZodObject<{
+                uri: z.ZodString;
+                'uri#integrity': z.ZodOptional<z.ZodString>;
+                alt_text: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            background_color: z.ZodOptional<z.ZodString>;
+            text_color: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        svg_template: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            uri: z.ZodString;
+            'uri#integrity': z.ZodOptional<z.ZodString>;
+            properties: z.ZodOptional<z.ZodObject<{
+                orientation: z.ZodOptional<z.ZodEnum<{
+                    portrait: "portrait";
+                    landscape: "landscape";
+                }>>;
+                color_scheme: z.ZodOptional<z.ZodEnum<{
+                    light: "light";
+                    dark: "dark";
+                }>>;
+                contrast: z.ZodOptional<z.ZodEnum<{
+                    normal: "normal";
+                    high: "high";
+                }>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type Display = z.infer<typeof DisplaySchema>;
 /**
  * Claim path within the credential's JSON structure.
  * Example: ["address", "street_address"]
  */
-type ClaimPath = Array<string | null>;
+declare const ClaimPathSchema: z.ZodArray<z.ZodNullable<z.ZodString>>;
+type ClaimPath = z.infer<typeof ClaimPathSchema>;
 /**
  * Display metadata for a specific claim.
  */
-type ClaimDisplay = {
-    /** REQUIRED. Language tag according to RFC 5646. */
-    lang: string;
-    /** REQUIRED. Human-readable label for the claim. */
-    label: string;
-    /** OPTIONAL. Description of the claim for end users. */
-    description?: string;
-};
+declare const ClaimDisplaySchema: z.ZodObject<{
+    lang: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ClaimDisplay = z.infer<typeof ClaimDisplaySchema>;
 /**
  * Indicates whether a claim is selectively disclosable.
  */
-type ClaimSelectiveDisclosure = 'always' | 'allowed' | 'never';
+declare const ClaimSelectiveDisclosureSchema: z.ZodEnum<{
+    never: "never";
+    always: "always";
+    allowed: "allowed";
+}>;
+type ClaimSelectiveDisclosure = z.infer<typeof ClaimSelectiveDisclosureSchema>;
 /**
  * Metadata for individual claims in the credential type.
  */
-type Claim = {
-    /**
-     * REQUIRED. Array of one or more paths to the claim in the credential subject.
-     * Each path is an array of strings (or null for array elements).
-     */
-    path: ClaimPath;
-    /** OPTIONAL. Display metadata in multiple languages. */
-    display?: ClaimDisplay[];
-    /** OPTIONAL. Controls whether the claim must, may, or must not be selectively disclosed. */
-    sd?: ClaimSelectiveDisclosure;
-    /**
-     * OPTIONAL. Unique string identifier for referencing the claim in an SVG template.
-     * Must consist of alphanumeric characters or underscores and must not start with a digit.
-     */
-    svg_id?: string;
-};
+declare const ClaimSchema: z.ZodObject<{
+    path: z.ZodArray<z.ZodNullable<z.ZodString>>;
+    display: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        lang: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    sd: z.ZodOptional<z.ZodEnum<{
+        never: "never";
+        always: "always";
+        allowed: "allowed";
+    }>>;
+    svg_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Claim = z.infer<typeof ClaimSchema>;
 /**
  * Type metadata for a specific Verifiable Credential (VC) type.
  * Reference: https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-09.html#name-type-metadata-format
  */
-type TypeMetadataFormat = {
-    /** REQUIRED. A URI uniquely identifying the credential type. */
-    vct: string;
-    /** OPTIONAL. Human-readable name for developers. */
-    name?: string;
-    /** OPTIONAL. Human-readable description for developers. */
-    description?: string;
-    /** OPTIONAL. URI of another type that this one extends. */
-    extends?: string;
-    /** OPTIONAL. Integrity metadata for the 'extends' field. */
-    'extends#Integrity'?: string;
-    /** OPTIONAL. Array of localized display metadata for the type. */
-    display?: Display[];
-    /** OPTIONAL. Array of claim metadata. */
-    claims?: Claim[];
+declare const TypeMetadataFormatSchema: z.ZodObject<{
+    vct: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    extends: z.ZodOptional<z.ZodString>;
+    'extends#integrity': z.ZodOptional<z.ZodString>;
+    display: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        lang: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        rendering: z.ZodOptional<z.ZodObject<{
+            simple: z.ZodOptional<z.ZodObject<{
+                logo: z.ZodOptional<z.ZodObject<{
+                    uri: z.ZodString;
+                    'uri#integrity': z.ZodOptional<z.ZodString>;
+                    alt_text: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                background_color: z.ZodOptional<z.ZodString>;
+                text_color: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            svg_template: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                uri: z.ZodString;
+                'uri#integrity': z.ZodOptional<z.ZodString>;
+                properties: z.ZodOptional<z.ZodObject<{
+                    orientation: z.ZodOptional<z.ZodEnum<{
+                        portrait: "portrait";
+                        landscape: "landscape";
+                    }>>;
+                    color_scheme: z.ZodOptional<z.ZodEnum<{
+                        light: "light";
+                        dark: "dark";
+                    }>>;
+                    contrast: z.ZodOptional<z.ZodEnum<{
+                        normal: "normal";
+                        high: "high";
+                    }>>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    claims: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodArray<z.ZodNullable<z.ZodString>>;
+        display: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            lang: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        sd: z.ZodOptional<z.ZodEnum<{
+            never: "never";
+            always: "always";
+            allowed: "allowed";
+        }>>;
+        svg_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * The resolved type metadata. If you just want to use the type metadata, you should use `typeMetadata`.
+ * In case additional processing is needed (e.g. for extensions in type metadata), you can use the `typeMetadataChain`
+ */
+type ResolvedTypeMetadata = {
+    /**
+     * The merged type metadata based on the resolved `vct` document and all `extends` values.
+     */
+    mergedTypeMetadata: TypeMetadataFormat;
+    /**
+     * The original type metadata documents, ordered from the extending type to the last extended type.
+     */
+    typeMetadataChain: [TypeMetadataFormat, ...TypeMetadataFormat[]];
+    /**
+     * The vct values present in the type metadata chain. This can be used for matching against e.g.
+     * DCQL queries which can query an underlying type.
+     */
+    vctValues: [string, ...string[]];
 };
+type TypeMetadataFormat = z.infer<typeof TypeMetadataFormatSchema>;
 
-type VcTFetcher = (uri: string, integrity?: string) => Promise<TypeMetadataFormat>;
+type VcTFetcher = (uri: string, integrity?: string) => Promise<TypeMetadataFormat | undefined>;
 
 type StatusListFetcher = (uri: string) => Promise<string>;
 type StatusValidator = (status: number) => Promise<void>;
@@ -147,6 +286,7 @@ type SDJWTVCConfig = SDJWTConfig & {
     statusVerifier?: Verifier;
     loadTypeMetadataFormat?: boolean;
     timeout?: number;
+    maxVctExtendsDepth?: number;
 };
 
 interface SDJWTVCStatusReference {
@@ -162,7 +302,7 @@ interface SdJwtVcPayload extends SdJwtPayload {
     exp?: number;
     cnf?: unknown;
     vct: string;
-    'vct#Integrity'?: string;
+    'vct#integrity'?: string;
     status?: SDJWTVCStatusReference;
     sub?: string;
     iat?: number;
@@ -175,7 +315,7 @@ type VerificationResult = {
         payload: kbPayload;
         header: kbHeader;
     } | undefined;
-    typeMetadataFormat?: TypeMetadataFormat;
+    typeMetadata?: ResolvedTypeMetadata;
 };
 
 declare class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
@@ -209,10 +349,13 @@ declare class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
     verify(encodedSDJwt: string, options?: VerifierOptions): Promise<VerificationResult>;
     /**
      * Gets VCT Metadata of the raw SD-JWT-VC. Returns the type metadata format. If the SD-JWT-VC is invalid or does not contain a vct claim, an error is thrown.
+     *
+     * It may return `undefined` if the fetcher returned an undefined value (instead of throwing an error).
+     *
      * @param encodedSDJwt
      * @returns
      */
-    getVct(encodedSDJwt: string): Promise<TypeMetadataFormat>;
+    getVct(encodedSDJwt: string): Promise<ResolvedTypeMetadata | undefined>;
     /**
      * Validates the integrity of the response if the integrity is passed. If the integrity does not match, an error is thrown.
      * @param integrity
@@ -224,25 +367,63 @@ declare class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
      * @param url
      * @returns
      */
-    private fetch;
+    private fetchWithIntegrity;
     /**
      * Verifies the VCT of the SD-JWT-VC. Returns the type metadata format.
+     * Resolves the full extends chain according to spec sections 6.4, 8.2, and 9.5.
      * @param result
      * @returns
      */
-    private verifyVct;
+    private fetchVct;
     /**
-     * Fetches VCT Metadata of the SD-JWT-VC. Returns the type metadata format. If the SD-JWT-VC does not contain a vct claim, an error is thrown.
-     * @param result
-     * @returns
+     * Checks if two claim paths are equal by comparing each element.
+     * @param path1 First claim path
+     * @param path2 Second claim path
+     * @returns True if paths are equal, false otherwise
      */
-    private fetchVct;
+    private claimPathsEqual;
+    /**
+     * Validates that extending claim metadata respects the constraints from spec section 9.5.1.
+     * @param baseClaim The base claim metadata
+     * @param extendingClaim The extending claim metadata
+     * @throws SDJWTException if validation fails
+     */
+    private validateClaimExtension;
+    /**
+     * Merges two type metadata formats, with the extending metadata overriding the base metadata.
+     * According to spec section 9.5:
+     * - All claim metadata from the extended type are inherited
+     * - The child type can add new claims or properties
+     * - If the child type defines claim metadata with the same path as the extended type,
+     *   the child type's object will override the corresponding object from the extended type
+     * According to spec section 9.5.1:
+     * - sd property can only be changed from 'allowed' (or omitted) to 'always' or 'never'
+     * - sd property cannot be changed from 'always' or 'never' to a different value
+     * According to spec section 8.2:
+     * - If the extending type defines its own display property, the original display metadata is ignored
+     * Note: The spec also mentions 'mandatory' property constraints, but this is not currently
+     * defined in the Claim type and will be validated when that property is added to the type.
+     * @param base The base type metadata format
+     * @param extending The extending type metadata format
+     * @returns The merged type metadata format
+     */
+    private mergeTypeMetadata;
+    /**
+     * Resolves the full VCT chain by recursively fetching extended type metadata.
+     * Implements security considerations from spec section 10.3 for circular dependencies.
+     * @param vct The VCT URI to resolve
+     * @param integrity Optional integrity metadata for the VCT
+     * @param depth Current depth in the chain
+     * @param visitedVcts Set of already visited VCT URIs to detect circular dependencies
+     * @returns The fully resolved and merged type metadata format
+     */
+    private resolveVctExtendsChain;
     /**
-     * Fetches VCT Metadata from the header of the SD-JWT-VC. Returns the type metadata format. If the SD-JWT-VC does not contain a vct claim, an error is thrown.
+     * Fetches and verifies the VCT Metadata for a VCT value.
      * @param result
-     * @param
+     * @returns
      */
-    private fetchVctFromHeader;
+    private fetchSingleVct;
     /**
      * Verifies the status of the SD-JWT-VC.
      * @param result
@@ -251,4 +432,4 @@ declare class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
     private verifyStatus;
 }
 
-export { type Claim, type ClaimDisplay, type ClaimPath, type ClaimSelectiveDisclosure, type Display, type Logo, type Rendering, type SDJWTVCConfig, type SDJWTVCStatusReference, SDJwtVcInstance, type SdJwtVcPayload, type SimpleRendering, type StatusListFetcher, type StatusValidator, type SvgTemplateProperties, type SvgTemplateRendering, type TypeMetadataFormat, type VcTFetcher, type VerificationResult };
+export { type Claim, type ClaimDisplay, ClaimDisplaySchema, type ClaimPath, ClaimPathSchema, ClaimSchema, type ClaimSelectiveDisclosure, ClaimSelectiveDisclosureSchema, ColorSchemeSchema, ContrastSchema, type Display, DisplaySchema, type Logo, LogoSchema, OrientationSchema, type Rendering, RenderingSchema, type ResolvedTypeMetadata, type SDJWTVCConfig, type SDJWTVCStatusReference, SDJwtVcInstance, type SdJwtVcPayload, type SimpleRendering, SimpleRenderingSchema, type StatusListFetcher, type StatusValidator, type SvgTemplateProperties, SvgTemplatePropertiesSchema, type SvgTemplateRendering, SvgTemplateRenderingSchema, type TypeMetadataFormat, TypeMetadataFormatSchema, type VcTFetcher, type VerificationResult };