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

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,17 +127,23 @@ 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;
   }
 
   /**
    * 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
    */
-  async getVct(encodedSDJwt: string): Promise<TypeMetadataFormat> {
+  async getVct(
+    encodedSDJwt: string,
+  ): Promise<ResolvedTypeMetadata | undefined> {
     // Call the parent class's verify method
     const { payload, header } = await SDJwt.extractJwt<
       Record<string, unknown>,
@@ -161,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 acording 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}`,
-        );
-      }
     }
   }
 
@@ -187,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),
@@ -199,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`);
@@ -210,75 +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);
+  ): 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],
+      };
+    }
+
+    // Resolve the full VCT chain if extends is present
+    return this.resolveVctExtendsChain(typeMetadataFormat);
+  }
 
-    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
+  /**
+   * 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 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}`,
+        );
+      }
     }
-    return 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
+   * 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 async fetchVct(
-    result: VerificationResult,
-  ): Promise<TypeMetadataFormat> {
-    if (!result.payload.vct) {
-      throw new SDJWTException('vct claim is required');
+  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-payload.ts

@@ -13,7 +13,7 @@ export interface SdJwtVcPayload extends SdJwtPayload {
   // REQUIRED. The type of the Verifiable Credential, e.g., https://credentials.example.com/identity_credential, as defined in Section 3.2.2.1.1.
   vct: string;
   // OPTIONAL. If passed, the loaded type metadata format has to be validated according to https://www.w3.org/TR/SRI/
-  'vct#Integrity'?: string;
+  'vct#integrity'?: string;
   // OPTIONAL. The information on how to read the status of the Verifiable Credential. See [https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-02.html] for more information.
   status?: SDJWTVCStatusReference;
   // OPTIONAL. The identifier of the Subject of the Verifiable Credential. The Issuer MAY use it to provide the Subject identifier known by the Issuer. There is no requirement for a binding to exist between sub and cnf claims.