@sd-jwt/sd-jwt-vc 0.1.0

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

@@ -0,0 +1,679 @@
+import {
+  getListFromStatusListJWT,
+  SLException,
+  type StatusListJWTHeaderParameters,
+  type StatusListJWTPayload,
+} from '@owf/token-status-list';
+import {
+  type DisclosureFrame,
+  ensureError,
+  Jwt,
+  type SafeVerifyResult,
+  SDJWTException,
+  SDJwt,
+  SDJwtInstance,
+  type VerificationError,
+  type VerificationErrorCode,
+  type VerifierOptions,
+} from '@sd-jwt/core';
+import z from 'zod';
+import type {
+  SDJWTVCConfig,
+  StatusListFetcher,
+  StatusValidator,
+} from './sd-jwt-vc-config';
+import type { SdJwtVcPayload } from './sd-jwt-vc-payload';
+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> {
+  /**
+   * The type of the SD-JWT-VC set in the header.typ field.
+   */
+  protected type = 'dc+sd-jwt';
+
+  protected userConfig: SDJWTVCConfig = {};
+
+  constructor(userConfig?: SDJWTVCConfig) {
+    super(userConfig);
+    if (userConfig) {
+      this.userConfig = userConfig;
+    }
+  }
+
+  /**
+   * Validates if the disclosure frame attempts to selectively disclose protected SD-JWT-VC claims.
+   * @param disclosureFrame
+   */
+  protected validateDisclosureFrame(
+    disclosureFrame?: DisclosureFrame<SdJwtVcPayload>,
+  ): void {
+    if (
+      disclosureFrame?._sd &&
+      Array.isArray(disclosureFrame._sd) &&
+      disclosureFrame._sd.length > 0
+    ) {
+      const reservedNames = ['iss', 'nbf', 'exp', 'cnf', 'vct', 'status'];
+      const reservedNamesInDisclosureFrame = disclosureFrame._sd.filter((key) =>
+        reservedNames.includes(String(key)),
+      );
+      if (reservedNamesInDisclosureFrame.length > 0) {
+        throw new SDJWTException('Cannot disclose protected field');
+      }
+    }
+  }
+
+  /**
+   * Fetches the status list from the uri with a timeout of 10 seconds.
+   * @param uri The URI to fetch from.
+   * @returns A promise that resolves to a compact JWT.
+   */
+  private async statusListFetcher(uri: string): Promise<string> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 10000);
+
+    try {
+      const response = await fetch(uri, {
+        signal: controller.signal,
+        headers: { Accept: 'application/statuslist+jwt' },
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Error fetching status list: ${
+            response.status
+          } ${await response.text()}`,
+        );
+      }
+
+      // according to the spec the content type should be application/statuslist+jwt
+      if (
+        !response.headers
+          .get('content-type')
+          ?.includes('application/statuslist+jwt')
+      ) {
+        throw new Error('Invalid content type');
+      }
+
+      return response.text();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Validates the status, throws an error if the status is not 0.
+   * @param status
+   * @returns
+   */
+  private async statusValidator(status: number): Promise<void> {
+    if (status !== 0) throw new SDJWTException('Status is not valid');
+    return Promise.resolve();
+  }
+
+  /**
+   * Verifies the SD-JWT-VC. It will validate the signature, the keybindings when required, the status, and the VCT.
+   * @param currentDate current time in seconds
+   */
+  async verify(encodedSDJwt: string, options?: VerifierOptions) {
+    // Call the parent class's verify method
+    const result: VerificationResult = await super
+      .verify(encodedSDJwt, options)
+      .then((res) => {
+        return {
+          payload: res.payload as SdJwtVcPayload,
+          header: res.header,
+          kb: res.kb,
+        };
+      });
+
+    await this.verifyStatus(result, options);
+    if (this.userConfig.loadTypeMetadataFormat) {
+      const resolvedTypeMetadata = await this.fetchVct(result);
+      result.typeMetadata = resolvedTypeMetadata;
+    }
+    return result;
+  }
+
+  /**
+   * Safe verification that collects all errors instead of failing fast.
+   * Returns a result object with either the verified data or an array of all errors.
+   * This includes SD-JWT-VC specific validations like status and VCT metadata.
+   *
+   * @param encodedSDJwt - The encoded SD-JWT-VC to verify
+   * @param options - Verification options
+   * @returns A SafeVerifyResult containing either success data or collected errors
+   */
+  async safeVerify(
+    encodedSDJwt: string,
+    options?: VerifierOptions,
+  ): Promise<SafeVerifyResult<VerificationResult>> {
+    const errors: VerificationError[] = [];
+
+    // Helper to add errors
+    const addError = (
+      code: VerificationErrorCode,
+      message: string,
+      details?: unknown,
+    ) => {
+      errors.push({ code, message, details });
+    };
+
+    // First, call the parent's safeVerify to get base verification results
+    const baseResult = await super.safeVerify(encodedSDJwt, options);
+
+    // Collect errors from base verification
+    if (!baseResult.success) {
+      errors.push(...baseResult.errors);
+    }
+
+    // Build partial result for additional verifications
+    let result: VerificationResult | undefined;
+    if (baseResult.success) {
+      result = {
+        payload: baseResult.data.payload as SdJwtVcPayload,
+        header: baseResult.data.header,
+        kb: baseResult.data.kb as VerificationResult['kb'],
+      };
+    } else {
+      // Try to extract payload even if verification failed for status/vct checks
+      try {
+        const { payload, header } = await SDJwt.extractJwt<
+          Record<string, unknown>,
+          SdJwtVcPayload
+        >(encodedSDJwt);
+        if (payload) {
+          result = {
+            payload,
+            header,
+            kb: undefined,
+          };
+        }
+      } catch {
+        // Cannot extract payload, skip additional checks
+      }
+    }
+
+    // Verify status (if payload is available)
+    if (result) {
+      try {
+        await this.verifyStatus(result, options);
+      } catch (e) {
+        const error = ensureError(e);
+        const errorMessage = error.message;
+        if (errorMessage.includes('Status is not valid')) {
+          addError('STATUS_INVALID', errorMessage, error);
+        } else {
+          addError(
+            'STATUS_VERIFICATION_FAILED',
+            `Status verification failed: ${errorMessage}`,
+            error,
+          );
+        }
+      }
+
+      // Verify VCT metadata (if configured)
+      if (this.userConfig.loadTypeMetadataFormat) {
+        try {
+          const resolvedTypeMetadata = await this.fetchVct(result);
+          if (result) {
+            result.typeMetadata = resolvedTypeMetadata;
+          }
+        } catch (e) {
+          addError(
+            'VCT_VERIFICATION_FAILED',
+            `VCT verification failed: ${ensureError(e).message}`,
+            e,
+          );
+        }
+      }
+    }
+
+    // Return result
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+
+    if (!result) {
+      return {
+        success: false,
+        errors: [
+          {
+            code: 'INVALID_SD_JWT',
+            message: 'Failed to construct verification result',
+          },
+        ],
+      };
+    }
+
+    return {
+      success: true,
+      data: 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<ResolvedTypeMetadata | undefined> {
+    // Call the parent class's verify method
+    const { payload, header } = await SDJwt.extractJwt<
+      Record<string, unknown>,
+      SdJwtVcPayload
+    >(encodedSDJwt);
+
+    if (!payload) {
+      throw new SDJWTException('JWT payload is missing');
+    }
+
+    const result: VerificationResult = {
+      payload,
+      header,
+      kb: undefined,
+    };
+
+    return this.fetchVct(result);
+  }
+
+  /**
+   * Validates the integrity of the response if the integrity is passed. If the integrity does not match, an error is thrown.
+   * @param integrity
+   * @param response
+   */
+  private async validateIntegrity(
+    response: Response,
+    url: string,
+    integrity?: string,
+  ) {
+    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
+    if (!this.userConfig.hasher) {
+      throw new SDJWTException('Hasher not found');
+    }
+    const hashBuffer = await this.userConfig.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}`,
+      );
+    }
+  }
+
+  /**
+   * Fetches the content from the url with a timeout of 10 seconds.
+   * @param url
+   * @returns
+   */
+  private async fetchWithIntegrity(
+    url: string,
+    integrity?: string,
+  ): Promise<unknown> {
+    try {
+      const response = await fetch(url, {
+        signal: AbortSignal.timeout(this.userConfig.timeout ?? 10000),
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(
+          `Error fetching ${url}: ${response.status} ${response.statusText} - ${errorText}`,
+        );
+      }
+      await this.validateIntegrity(response.clone(), url, integrity);
+      const data = await response.json();
+
+      return data;
+    } catch (e) {
+      const error = ensureError(e);
+      if (error.name === 'TimeoutError') {
+        throw new Error(`Request to ${url} timed out`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * 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 fetchVct(
+    result: VerificationResult,
+  ): 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);
+  }
+
+  /**
+   * 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}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * 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;
+    }
+
+    // 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;
+    }
+
+    return merged;
+  }
+
+  /**
+   * 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 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 (!parentTypeMetadata.extends) {
+      throw new SDJWTException(
+        `Type metadata for vct '${parentTypeMetadata.vct}' has no 'extends' field. Unable to resolve extended type metadata document.`,
+      );
+    }
+
+    // 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}`,
+      );
+    }
+
+    // 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.`,
+      );
+    }
+
+    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 validated.data;
+  }
+
+  /**
+   * Verifies the status of the SD-JWT-VC.
+   * @param result
+   * @param options
+   */
+  private async verifyStatus(
+    result: VerificationResult,
+    options?: VerifierOptions,
+  ): Promise<void> {
+    if (options?.disableStatusVerification) {
+      return;
+    }
+
+    if (result.payload.status) {
+      //checks if a status field is present in the payload based on https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-02.html
+      if (result.payload.status.status_list) {
+        // fetch the status list from the uri
+        const fetcher: StatusListFetcher =
+          this.userConfig.statusListFetcher ??
+          this.statusListFetcher.bind(this);
+        // fetch the status list from the uri
+        const statusListJWT = await fetcher(
+          result.payload.status.status_list.uri,
+        );
+
+        const slJWT = Jwt.fromEncode<
+          StatusListJWTHeaderParameters,
+          StatusListJWTPayload
+        >(statusListJWT);
+        // check if the status list has a valid signature. The presence of the verifier is checked in the parent class.
+        if (!this.userConfig.verifier || !this.userConfig.statusVerifier) {
+          throw new SDJWTException('Verifier not found for status list JWT');
+        }
+        await slJWT
+          .verify(
+            this.userConfig.statusVerifier ?? this.userConfig.verifier,
+            options,
+          )
+          .catch((err: SLException) => {
+            throw new SLException(
+              `Status List JWT verification failed: ${err.message}`,
+              err.details,
+            );
+          });
+
+        // get the status list from the status list JWT
+        const statusList = getListFromStatusListJWT(statusListJWT);
+        const status = statusList.getStatus(
+          result.payload.status.status_list.idx,
+        );
+
+        // validate the status
+        const statusValidator: StatusValidator =
+          this.userConfig.statusValidator ?? this.statusValidator.bind(this);
+        await statusValidator(status);
+      }
+    }
+  }
+
+  public config(newConfig: SDJWTVCConfig) {
+    super.config(newConfig);
+  }
+}

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

@@ -0,0 +1,23 @@
+import type { SdJwtPayload } from '@sd-jwt/core';
+import type { SDJWTVCStatusReference } from './sd-jwt-vc-status-reference';
+
+export interface SdJwtVcPayload extends SdJwtPayload {
+  // OPTIONAL. The Issuer of the Verifiable Credential. The value is a case-sensitive string containing a StringOrURI value. See [RFC7519] for more information.
+  iss?: string;
+  // OPTIONAL. The time before which the Verifiable Credential MUST NOT be accepted before validating. See [RFC7519] for more information.
+  nbf?: number;
+  // OPTIONAL. The expiry time of the Verifiable Credential after which the Verifiable Credential is no longer valid. See [RFC7519] for more information.
+  exp?: number;
+  // OPTIONAL unless cryptographic Key Binding is to be supported, in which case it is REQUIRED. Contains the confirmation method identifying the proof of possession key as defined in [RFC7800]. It is RECOMMENDED that this contains a JWK as defined in Section 3.2 of [RFC7800]. For proof of cryptographic Key Binding, the Key Binding JWT in the presentation of the SD-JWT MUST be signed by the key identified in this claim.
+  cnf?: unknown;
+  // 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;
+  // 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.
+  sub?: string;
+  // OPTIONAL. The time of issuance of the Verifiable Credential. See [RFC7519] for more information.
+  iat?: number;
+}

package/src/sd-jwt-vc-status-reference.ts

@@ -0,0 +1,9 @@
+export interface SDJWTVCStatusReference {
+  // REQUIRED. implenentation according to https://www.ietf.org/archive/id/draft-ietf-oauth-status-list-02.html
+  status_list: {
+    // REQUIRED. index in the list of statuses
+    idx: number;
+    // REQUIRED. the reference to fetch the status list
+    uri: string;
+  };
+}