@sd-jwt/sd-jwt-vc 0.17.2-next.4 → 0.17.2-next.7

package/src/sd-jwt-vc-instance.ts

@@ -6,15 +6,21 @@ import {
   type StatusListJWTPayload,
 } from '@sd-jwt/jwt-status-list';
 import type { DisclosureFrame, Hasher, Verifier } from '@sd-jwt/types';
-import { base64urlDecode, SDJWTException } from '@sd-jwt/utils';
+import { SDJWTException } from '@sd-jwt/utils';
+import z from 'zod';
 import type {
   SDJWTVCConfig,
   StatusListFetcher,
   StatusValidator,
 } from './sd-jwt-vc-config';
 import type { SdJwtVcPayload } from './sd-jwt-vc-payload';
-import type { TypeMetadataFormat } from './sd-jwt-vc-type-metadata-format';
-import type { VcTFetcher } from './sd-jwt-vc-vct';
+import {
+  type Claim,
+  type ClaimPath,
+  type ResolvedTypeMetadata,
+  type TypeMetadataFormat,
+  TypeMetadataFormatSchema,
+} from './sd-jwt-vc-type-metadata-format';
 import type { VerificationResult } from './verification-result';
 
 export class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
@@ -121,7 +127,8 @@ export class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
 
     await this.verifyStatus(result, options);
     if (this.userConfig.loadTypeMetadataFormat) {
-      await this.verifyVct(result);
+      const resolvedTypeMetadata = await this.fetchVct(result);
+      result.typeMetadata = resolvedTypeMetadata;
     }
     return result;
   }
@@ -134,7 +141,9 @@ export class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
    * @param encodedSDJwt
    * @returns
    */
-  async getVct(encodedSDJwt: string): Promise<TypeMetadataFormat | undefined> {
+  async getVct(
+    encodedSDJwt: string,
+  ): Promise<ResolvedTypeMetadata | undefined> {
     // Call the parent class's verify method
     const { payload, header } = await SDJwt.extractJwt<
       Record<string, unknown>,
@@ -164,24 +173,24 @@ export class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
     url: string,
     integrity?: string,
   ) {
-    if (integrity) {
-      // validate the integrity of the response according to https://www.w3.org/TR/SRI/
-      const arrayBuffer = await response.arrayBuffer();
-      const alg = integrity.split('-')[0];
-      //TODO: error handling when a hasher is passed that is not supporting the required algorithm according to the spec
-      const hashBuffer = await (this.userConfig.hasher as Hasher)(
-        arrayBuffer,
-        alg,
+    if (!integrity) return;
+
+    // validate the integrity of the response according to https://www.w3.org/TR/SRI/
+    const arrayBuffer = await response.arrayBuffer();
+    const alg = integrity.split('-')[0];
+    //TODO: error handling when a hasher is passed that is not supporting the required algorithm according to the spec
+    const hashBuffer = await (this.userConfig.hasher as Hasher)(
+      arrayBuffer,
+      alg,
+    );
+    const integrityHash = integrity.split('-')[1];
+    const hash = Array.from(new Uint8Array(hashBuffer))
+      .map((byte) => byte.toString(16).padStart(2, '0'))
+      .join('');
+    if (hash !== integrityHash) {
+      throw new Error(
+        `Integrity check for ${url} failed: is ${hash}, but expected ${integrityHash}`,
       );
-      const integrityHash = integrity.split('-')[1];
-      const hash = Array.from(new Uint8Array(hashBuffer))
-        .map((byte) => byte.toString(16).padStart(2, '0'))
-        .join('');
-      if (hash !== integrityHash) {
-        throw new Error(
-          `Integrity check for ${url} failed: is ${hash}, but expected ${integrityHash}`,
-        );
-      }
     }
   }
 
@@ -190,7 +199,10 @@ export class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
    * @param url
    * @returns
    */
-  private async fetch<T>(url: string, integrity?: string): Promise<T> {
+  private async fetchWithIntegrity(
+    url: string,
+    integrity?: string,
+  ): Promise<unknown> {
     try {
       const response = await fetch(url, {
         signal: AbortSignal.timeout(this.userConfig.timeout ?? 10000),
@@ -202,7 +214,9 @@ export class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
         );
       }
       await this.validateIntegrity(response.clone(), url, integrity);
-      return response.json() as Promise<T>;
+      const data = await response.json();
+
+      return data;
     } catch (error) {
       if ((error as Error).name === 'TimeoutError') {
         throw new Error(`Request to ${url} timed out`);
@@ -213,76 +227,266 @@ export class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
 
   /**
    * 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 async verifyVct(
+  private async fetchVct(
     result: VerificationResult,
-  ): Promise<TypeMetadataFormat | undefined> {
-    const typeMetadataFormat = await this.fetchVct(result);
-
-    if (typeMetadataFormat?.extends) {
-      // implement based on https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-08.html#name-extending-type-metadata
-      //TODO: needs to be implemented. Unclear at this point which values will overwrite the values from the extended type metadata format
+  ): Promise<ResolvedTypeMetadata | undefined> {
+    const typeMetadataFormat = await this.fetchSingleVct(
+      result.payload.vct,
+      result.payload['vct#integrity'],
+    );
+
+    if (!typeMetadataFormat) return undefined;
+
+    // If there's no extends
+    if (!typeMetadataFormat.extends) {
+      return {
+        mergedTypeMetadata: typeMetadataFormat,
+        typeMetadataChain: [typeMetadataFormat],
+        vctValues: [typeMetadataFormat.vct],
+      };
     }
 
-    return typeMetadataFormat;
+    // Resolve the full VCT chain if extends is present
+    return this.resolveVctExtendsChain(typeMetadataFormat);
   }
 
   /**
-   * 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 async fetchVct(
-    result: VerificationResult,
-  ): Promise<TypeMetadataFormat | undefined> {
-    if (!result.payload.vct) {
-      throw new SDJWTException('vct claim is required');
+  private claimPathsEqual(path1: ClaimPath, path2: ClaimPath): boolean {
+    if (path1.length !== path2.length) return false;
+    return path1.every((element, index) => element === path2[index]);
+  }
+
+  /**
+   * 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(
+    baseClaim: Claim,
+    extendingClaim: Claim,
+  ): void {
+    // Validate 'sd' property constraints (section 9.5.1)
+    if (baseClaim.sd && extendingClaim.sd) {
+      // Cannot change from 'always' or 'never' to a different value
+      if (
+        (baseClaim.sd === 'always' || baseClaim.sd === 'never') &&
+        baseClaim.sd !== extendingClaim.sd
+      ) {
+        const pathStr = JSON.stringify(extendingClaim.path);
+        throw new SDJWTException(
+          `Cannot change 'sd' property from '${baseClaim.sd}' to '${extendingClaim.sd}' for claim at path ${pathStr}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * 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(
+    base: TypeMetadataFormat,
+    extending: TypeMetadataFormat,
+  ): TypeMetadataFormat {
+    // Start with a shallow copy of the extending metadata
+    // All properties that don't have explicit processing logic for merging
+    // will only be shallow copied, and the extending metadata will take precedence.
+    const merged: TypeMetadataFormat = { ...extending };
+
+    // Merge claims arrays if both exist
+    if (base.claims || extending.claims) {
+      const baseClaims = base.claims ?? [];
+      const extendingClaims = extending.claims ?? [];
+
+      // Validate extending claims that override base claims
+      for (const extendingClaim of extendingClaims) {
+        const matchingBaseClaim = baseClaims.find((baseClaim) =>
+          this.claimPathsEqual(baseClaim.path, extendingClaim.path),
+        );
+
+        if (matchingBaseClaim) {
+          this.validateClaimExtension(matchingBaseClaim, extendingClaim);
+        }
+      }
+
+      // Build final claims array preserving order
+      // Start with base claims, replacing any that are overridden
+      const mergedClaims: typeof baseClaims = [];
+      const extendedClaimsWithoutBase = [...extendingClaims];
+
+      // Add base claims, replacing with extending version if path matches
+      for (const baseClaim of baseClaims) {
+        const extendingClaimIndex = extendedClaimsWithoutBase.findIndex(
+          (extendingClaim) =>
+            this.claimPathsEqual(baseClaim.path, extendingClaim.path),
+        );
+        const extendingClaim =
+          extendingClaimIndex !== -1
+            ? extendedClaimsWithoutBase[extendingClaimIndex]
+            : undefined;
+
+        // Remove item from the array
+        if (extendingClaim) {
+          extendedClaimsWithoutBase.splice(extendingClaimIndex, 1);
+        }
+
+        // Prefer extending claim, otherwise use base claim
+        mergedClaims.push(extendingClaim ?? baseClaim);
+      }
+
+      // Add all remaining claims at the end
+      mergedClaims.push(...extendedClaimsWithoutBase);
+
+      merged.claims = mergedClaims;
     }
 
-    if (result.header?.vctm) {
-      return this.fetchVctFromHeader(result.payload.vct, result);
+    // Handle display metadata (section 8.2)
+    // If extending type doesn't define display, inherit from base
+    if (!extending.display && base.display) {
+      merged.display = base.display;
     }
 
-    const fetcher: VcTFetcher =
-      this.userConfig.vctFetcher ??
-      ((uri, integrity) => this.fetch(uri, integrity));
-    return fetcher(result.payload.vct, result.payload['vct#integrity']);
+    return merged;
   }
 
   /**
-   * 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.
-   * @param result
-   * @param
+   * 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 async fetchVctFromHeader(
-    vct: string,
-    result: VerificationResult,
-  ): Promise<TypeMetadataFormat> {
-    const vctmHeader = result.header?.vctm;
+  private async resolveVctExtendsChain(
+    parentTypeMetadata: TypeMetadataFormat,
+    // We start at one, as the base is already fetched when this method is first called
+    depth: number = 1,
+    // By default include the parent vct, in case of the first call
+    visitedVcts: Set<string> = new Set(parentTypeMetadata.vct),
+  ): Promise<ResolvedTypeMetadata> {
+    const maxDepth = this.userConfig.maxVctExtendsDepth ?? 5;
+
+    // Check max depth (security consideration from spec section 10.3)
+    if (maxDepth !== -1 && depth > maxDepth) {
+      throw new SDJWTException(
+        `Maximum VCT extends depth of ${maxDepth} exceeded`,
+      );
+    }
 
-    if (!vctmHeader || !Array.isArray(vctmHeader)) {
-      throw new Error('vctm claim in SD JWT header is invalid');
+    if (!parentTypeMetadata.extends) {
+      throw new SDJWTException(
+        `Type metadata for vct '${parentTypeMetadata.vct}' has no 'extends' field. Unable to resolve extended type metadata document.`,
+      );
     }
 
-    const typeMetadataFormat = (vctmHeader as unknown[])
-      .map((vctm) => {
-        if (!(typeof vctm === 'string')) {
-          throw new Error('vctm claim in SD JWT header is invalid');
-        }
+    // Check for circular dependencies (security consideration from spec section 10.3)
+    if (visitedVcts.has(parentTypeMetadata.extends)) {
+      throw new SDJWTException(
+        `Circular dependency detected in VCT extends chain: ${parentTypeMetadata.extends}`,
+      );
+    }
 
-        return JSON.parse(base64urlDecode(vctm));
-      })
-      .find((typeMetadataFormat) => {
-        return typeMetadataFormat.vct === vct;
-      });
+    // Mark this VCT as visited
+    visitedVcts.add(parentTypeMetadata.extends);
+
+    const extendedTypeMetadata = await this.fetchSingleVct(
+      parentTypeMetadata.extends,
+      parentTypeMetadata['extends#integrity'],
+    );
+
+    // While top-level vct MAY return null (meaning there's no vct type metadata)
+    // The extends value ALWAYS must resolve to a value. A custom user provided resolver
+    // can return a minimal on-demand type metadata document if it wants to support this use case
+    if (!extendedTypeMetadata) {
+      throw new SDJWTException(
+        `Resolving VCT extends value '${parentTypeMetadata.extends}' resulted in an undefined result.`,
+      );
+    }
 
-    if (!typeMetadataFormat) {
-      throw new Error('could not find VCT Metadata in JWT header');
+    let resolvedTypeMetadata: ResolvedTypeMetadata;
+
+    // If this type extends another, recursively resolve the chain
+    //  We MUST first process the lower level document before processing
+    // the higher level document
+    if (extendedTypeMetadata.extends) {
+      resolvedTypeMetadata = await this.resolveVctExtendsChain(
+        extendedTypeMetadata,
+        depth + 1,
+        visitedVcts,
+      );
+    } else {
+      resolvedTypeMetadata = {
+        mergedTypeMetadata: extendedTypeMetadata,
+        typeMetadataChain: [extendedTypeMetadata],
+        vctValues: [extendedTypeMetadata.vct],
+      };
+    }
+
+    const mergedTypeMetadata = this.mergeTypeMetadata(
+      resolvedTypeMetadata.mergedTypeMetadata,
+      parentTypeMetadata,
+    );
+
+    return {
+      mergedTypeMetadata: mergedTypeMetadata,
+      typeMetadataChain: [
+        parentTypeMetadata,
+        ...resolvedTypeMetadata.typeMetadataChain,
+      ],
+      vctValues: [parentTypeMetadata.vct, ...resolvedTypeMetadata.vctValues],
+    };
+  }
+
+  /**
+   * Fetches and verifies the VCT Metadata for a VCT value.
+   * @param result
+   * @returns
+   */
+  private async fetchSingleVct(
+    vct: string,
+    integrity?: string,
+  ): Promise<TypeMetadataFormat | undefined> {
+    const fetcher =
+      this.userConfig.vctFetcher ??
+      ((uri, integrity) => this.fetchWithIntegrity(uri, integrity));
+
+    // Data may be undefined
+    const data = await fetcher(vct, integrity);
+    if (!data) return undefined;
+
+    const validated = TypeMetadataFormatSchema.safeParse(data);
+    if (!validated.success) {
+      throw new SDJWTException(
+        `Invalid VCT type metadata for vct '${vct}':\n${z.prettifyError(validated.error)}`,
+      );
     }
 
-    return typeMetadataFormat;
+    return validated.data;
   }
 
   /**

package/src/sd-jwt-vc-type-metadata-format.ts

@@ -1,144 +1,196 @@
+import { z } from 'zod';
+
 /**
  * Logo metadata used in rendering a credential.
  */
-export type Logo = {
+export const LogoSchema = z.object({
   /** REQUIRED. A URI pointing to the logo image. */
-  uri: string;
+  uri: z.string(),
   /** OPTIONAL. An "integrity metadata" string as described in Section 7. */
-  'uri#integrity'?: string;
+  'uri#integrity': z.string().optional(),
   /** OPTIONAL. A string containing alternative text for the logo image. */
-  alt_text?: string;
-};
+  alt_text: z.string().optional(),
+});
+
+export type Logo = z.infer<typeof LogoSchema>;
 
 /**
  * The simple rendering method is intended for applications that do not support SVG.
  */
-export type SimpleRendering = {
+export const SimpleRenderingSchema = z.object({
   /** OPTIONAL. Logo metadata to display for the credential. */
-  logo?: Logo;
+  logo: LogoSchema.optional(),
   /** OPTIONAL. RGB color value for the credential background (e.g., "#FFFFFF"). */
-  background_color?: string;
+  background_color: z.string().optional(),
   /** OPTIONAL. RGB color value for the credential text (e.g., "#000000"). */
-  text_color?: string;
-};
+  text_color: z.string().optional(),
+});
+
+export type SimpleRendering = z.infer<typeof SimpleRenderingSchema>;
 
 /** Enum of valid values for rendering orientation. */
-type Orientation = 'portrait' | 'landscape';
+export const OrientationSchema = z.enum(['portrait', 'landscape']);
 
 /** Enum of valid values for rendering color schemes. */
-type ColorScheme = 'light' | 'dark';
+export const ColorSchemeSchema = z.enum(['light', 'dark']);
 
 /** Enum of valid values for rendering contrast. */
-type Contrast = 'normal' | 'high';
+export const ContrastSchema = z.enum(['normal', 'high']);
 
 /**
  * Properties that describe the display preferences for an SVG template rendering.
  */
-export type SvgTemplateProperties = {
+export const SvgTemplatePropertiesSchema = z.object({
   /** OPTIONAL. Orientation optimized for the template. */
-  orientation?: Orientation;
+  orientation: OrientationSchema.optional(),
   /** OPTIONAL. Color scheme optimized for the template. */
-  color_scheme?: ColorScheme;
+  color_scheme: ColorSchemeSchema.optional(),
   /** OPTIONAL. Contrast level optimized for the template. */
-  contrast?: Contrast;
-};
+  contrast: ContrastSchema.optional(),
+});
+
+export type SvgTemplateProperties = z.infer<typeof SvgTemplatePropertiesSchema>;
 
 /**
  * SVG rendering metadata containing URI and optional integrity and properties.
  */
-export type SvgTemplateRendering = {
+export const SvgTemplateRenderingSchema = z.object({
   /** REQUIRED. A URI pointing to the SVG template. */
-  uri: string;
+  uri: z.string(),
   /** OPTIONAL. An "integrity metadata" string as described in Section 7. */
-  'uri#integrity'?: string;
+  'uri#integrity': z.string().optional(),
   /** REQUIRED if more than one SVG template is present. */
-  properties?: SvgTemplateProperties;
-};
+  properties: SvgTemplatePropertiesSchema.optional(),
+});
+
+export type SvgTemplateRendering = z.infer<typeof SvgTemplateRenderingSchema>;
 
 /**
  * Rendering metadata, either simple or SVG-based, for a credential.
  */
-export type Rendering = {
+export const RenderingSchema = z.object({
   /** OPTIONAL. Simple rendering metadata. */
-  simple?: SimpleRendering;
+  simple: SimpleRenderingSchema.optional(),
   /** OPTIONAL. Array of SVG template rendering objects. */
-  svg_template?: SvgTemplateRendering[];
-};
+  svg_template: z.array(SvgTemplateRenderingSchema).optional(),
+});
+
+export type Rendering = z.infer<typeof RenderingSchema>;
 
 /**
  * Display metadata associated with a credential type.
  */
-export type Display = {
+export const DisplaySchema = z.object({
   /** REQUIRED. Language tag according to RFC 5646 (e.g., "en", "de"). */
-  lang: string;
+  lang: z.string(),
   /** REQUIRED. Human-readable name for the credential type. */
-  name: string;
+  name: z.string(),
   /** OPTIONAL. Description of the credential type for end users. */
-  description?: string;
+  description: z.string().optional(),
   /** OPTIONAL. Rendering information (simple or SVG) for the credential. */
-  rendering?: Rendering;
-};
+  rendering: RenderingSchema.optional(),
+});
+
+export type Display = z.infer<typeof DisplaySchema>;
 
 /**
  * Claim path within the credential's JSON structure.
  * Example: ["address", "street_address"]
  */
-export type ClaimPath = Array<string | null>;
+export const ClaimPathSchema = z.array(z.string().nullable());
+
+export type ClaimPath = z.infer<typeof ClaimPathSchema>;
 
 /**
  * Display metadata for a specific claim.
  */
-export type ClaimDisplay = {
+export const ClaimDisplaySchema = z.object({
   /** REQUIRED. Language tag according to RFC 5646. */
-  lang: string;
+  lang: z.string(),
   /** REQUIRED. Human-readable label for the claim. */
-  label: string;
+  label: z.string(),
   /** OPTIONAL. Description of the claim for end users. */
-  description?: string;
-};
+  description: z.string().optional(),
+});
+
+export type ClaimDisplay = z.infer<typeof ClaimDisplaySchema>;
 
 /**
  * Indicates whether a claim is selectively disclosable.
  */
-export type ClaimSelectiveDisclosure = 'always' | 'allowed' | 'never';
+export const ClaimSelectiveDisclosureSchema = z.enum([
+  'always',
+  'allowed',
+  'never',
+]);
+
+export type ClaimSelectiveDisclosure = z.infer<
+  typeof ClaimSelectiveDisclosureSchema
+>;
 
 /**
  * Metadata for individual claims in the credential type.
  */
-export type Claim = {
+export const ClaimSchema = z.object({
   /**
    * 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;
+  path: ClaimPathSchema,
   /** OPTIONAL. Display metadata in multiple languages. */
-  display?: ClaimDisplay[];
+  display: z.array(ClaimDisplaySchema).optional(),
   /** OPTIONAL. Controls whether the claim must, may, or must not be selectively disclosed. */
-  sd?: ClaimSelectiveDisclosure;
+  sd: ClaimSelectiveDisclosureSchema.optional(),
   /**
    * 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;
-};
+  svg_id: z.string().optional(),
+});
+
+export 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
  */
-export type TypeMetadataFormat = {
+export const TypeMetadataFormatSchema = z.object({
   /** REQUIRED. A URI uniquely identifying the credential type. */
-  vct: string;
+  vct: z.string(),
   /** OPTIONAL. Human-readable name for developers. */
-  name?: string;
+  name: z.string().optional(),
   /** OPTIONAL. Human-readable description for developers. */
-  description?: string;
+  description: z.string().optional(),
   /** OPTIONAL. URI of another type that this one extends. */
-  extends?: string;
+  extends: z.string().optional(),
   /** OPTIONAL. Integrity metadata for the 'extends' field. */
-  'extends#integrity'?: string;
+  'extends#integrity': z.string().optional(),
   /** OPTIONAL. Array of localized display metadata for the type. */
-  display?: Display[];
+  display: z.array(DisplaySchema).optional(),
   /** OPTIONAL. Array of claim metadata. */
-  claims?: Claim[];
+  claims: z.array(ClaimSchema).optional(),
+});
+
+/**
+ * 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`
+ */
+export 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[]];
 };
+
+export type TypeMetadataFormat = z.infer<typeof TypeMetadataFormatSchema>;