feat: add parser and type for SD-JWT VCDM

packages/vcdm/package.json

@@ -44,5 +44,10 @@
       "cjs",
       "esm"
     ]
+  },
+  "dependencies": {
+    "@sd-jwt/decode": "^0.9.2",
+    "@sd-jwt/hash": "^0.9.2",
+    "@sd-jwt/sd-jwt-vc": "^0.9.2"
   }
 }

packages/vcdm/src/index.ts

@@ -0,0 +1,2 @@
+export * from './parser';
+export * from './type';

packages/vcdm/src/parser.ts

@@ -0,0 +1,43 @@
+import { Vcdm, VcType } from './type';
+import {
+  decodeJwt,
+  decodeSdJwtSync,
+  getClaimsSync,
+  splitSdJwt,
+} from '@sd-jwt/decode';
+import { hasher } from '@sd-jwt/hash';
+import { SdJwtVcPayload } from '@sd-jwt/sd-jwt-vc';
+
+/**
+ * Parses an SD-JWT VCDM from a SD-JWT or JWT string.
+ *
+ * @param sdjwtOrjwt - The SD-JWT or JWT string to parse.
+ * @returns The parsed VCDM object or parsed SD-JWT VC object with type property set to SD-JWT VC or W3C VCDM.
+ */
+export const parseSdJwtVcdm = (sdjwtOrjwt: string) => {
+  const { jwt } = splitSdJwt(sdjwtOrjwt);
+  const { payload } = decodeJwt(jwt);
+
+  if (payload.vct === undefined) {
+    throw new Error('vct claim is required');
+  }
+
+  if (payload.vcdm !== undefined) {
+    return {
+      type: VcType.W3C_VCDM,
+      payload: payload.vcdm as Vcdm,
+    };
+  }
+
+  const decodedSdJwt = decodeSdJwtSync(sdjwtOrjwt, hasher);
+  const claims = getClaimsSync(
+    decodedSdJwt.jwt.payload,
+    decodedSdJwt.disclosures,
+    hasher,
+  );
+
+  return {
+    type: VcType.SD_JWT_VC,
+    payload: claims as SdJwtVcPayload,
+  };
+};

packages/vcdm/src/test/parser.spec.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { parseSdJwtVcdm } from '../parser';
+import { VcType } from '../type';
+
+/**
+ * header: {
+    "alg": "HS256",
+    "typ": "dc+sdjwt"
+  },
+  payload: {
+    "vct": "ExampleCredentials",
+    "vcdm": {
+      "@context": ["https://www.w3.org/2018/credentials/v1"],
+      "type": ["VerifiableCredential", "ExampleCredentials"],
+      "credentialSubject": {
+        "id": "urn:example-id:123",
+        "name": "John Doe"
+      }
+    }
+  }
+ */
+const exampleVcdmJwt =
+  'eyJhbGciOiJIUzI1NiIsInR5cCI6ImRjK3Nkand0In0.eyJ2Y3QiOiJFeGFtcGxlQ3JlZGVudGlhbHMiLCJ2Y2RtIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJFeGFtcGxlQ3JlZGVudGlhbHMiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJ1cm46ZXhhbXBsZS1pZDoxMjMiLCJuYW1lIjoiSm9obiBEb2UifX19.nQ0ppfHDwxXEvQ1w-Ym0lLE-ifW2pnNVUBFbok_iVtE';
+
+/**
+ * header: { typ: 'dc+sd-jwt', alg: 'ES256' },
+ * payload: {
+    iss: 'Issuer',
+    iat: 1739949212870,
+    vct: 'ExampleCredentials',
+    lastname: 'Doe',
+    ssn: '123-45-6789',
+    data: { firstname: 'John', lastname: 'Doe', ssn: '123-45-6789' },
+    firstname: 'John',
+    id: '1234'
+  }
+ */
+const exampleSdJwtVcJwt =
+  'eyJ0eXAiOiJkYytzZC1qd3QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJJc3N1ZXIiLCJpYXQiOjE3Mzk5NDg5Nzg3NjYsInZjdCI6IkV4YW1wbGVDcmVkZW50aWFscyIsImxhc3RuYW1lIjoiRG9lIiwic3NuIjoiMTIzLTQ1LTY3ODkiLCJkYXRhIjp7ImZpcnN0bmFtZSI6IkpvaG4iLCJsYXN0bmFtZSI6IkRvZSIsInNzbiI6IjEyMy00NS02Nzg5IiwiX3NkIjpbIkZNQzdBS1BwNTJjazctU1hWVURoWEdpandqUEtkQWtNem9tUmV5dF81YW8iLCJsaGthVFltUDFGdHgyT3RPMkdZa1BsaWpTeEpBTkt6M192QV96YkF5azI4IiwieGFMalpTMzJ1NXdtbjh5UHdSWktUX3Jwb0J4WTJpajZJQXRnWTZ5TXBnZyJdfSwiX3NkIjpbIjZDWXVhdFZEUXRsVHBNTkdfVWQxdy1sdW0yTnZkOGJ4TktRRUVJWkRWWjQiLCJNNEFNVTNyMnRKUG1PYnFIVlo3dUZVY2dxX3lIMzNOWVJiZzJFRW5rVW1rIiwiaE1BTDlmTjRfVjRQVV9LelhFU3lQaHF3RGhvVXNsV0RyLWFsOTQxOWk1WSJdLCJfc2RfYWxnIjoic2hhLTI1NiJ9.tZ3D-AFoNfZLWLwyr76dM8UnUd0na7CjeAAgKS925K0b_bTw7zPACWGfme9POfwELlBLsWiZGOo-SnoJ0doxag~WyJkMGNiZjI1OTBkNWVlOGNjIiwiZmlyc3RuYW1lIiwiSm9obiJd~WyI1NDFjY2JhNmQyYmZjMGJjIiwiaWQiLCIxMjM0Il0~';
+
+describe('parse', () => {
+  it('should parse VCDM JWT correctly', () => {
+    const result = parseSdJwtVcdm(exampleVcdmJwt);
+    expect(result.type).toEqual(VcType.W3C_VCDM);
+    expect(result.payload).toEqual({
+      '@context': ['https://www.w3.org/2018/credentials/v1'],
+      type: ['VerifiableCredential', 'ExampleCredentials'],
+      credentialSubject: {
+        id: 'urn:example-id:123',
+        name: 'John Doe',
+      },
+    });
+  });
+
+  it('should parse SD-JWT VC correctly', () => {
+    const result = parseSdJwtVcdm(exampleSdJwtVcJwt);
+    expect(result.type).toEqual(VcType.SD_JWT_VC);
+    expect(result.payload).toEqual({
+      iss: 'Issuer',
+      iat: 1739948978766,
+      firstname: 'John',
+      lastname: 'Doe',
+      ssn: '123-45-6789',
+      data: { firstname: 'John', lastname: 'Doe', ssn: '123-45-6789' },
+      id: '1234',
+      vct: 'ExampleCredentials',
+    });
+  });
+});

packages/vcdm/src/type.ts

@@ -0,0 +1,49 @@
+/**
+ * Implementaters of SD-JWT VCDM MUST use valid values for both vct Claim defined in IETF SD-JWT VC [@!I-D.ietf-oauth-sd-jwt-vc] and type proprty defined in W3C VCDM [@!W3C.VCDM1.1] or [@!W3C.VCDM2.0].
+
+  For backward compatibility with JWT processors, the following registered JWT claims MUST be used, instead of their respective counterpart properties in W3C VCDM [@!W3C.VCDM1.1] or [@!W3C.VCDM2.0]:
+
+    - To represent the validity period of SD-JWT VCDM (i.e., cryptographic signature), exp/iat Claims encoded as a UNIX timestamp (NumericDate) MUST be used, and not expirationDate and issuanceDate properties defined in [@!W3C.VCDM1.1], validFrom and validTo properties defined in [@!W3C.VCDM2.0].
+    - iss Claim MUST represent the identifier of the issuer property, i.e., the issuer property value if issuer is a String, or the id property of the issuer object if issuer is an object. issuer property MUST be ignored if present.
+    - status Claim MUST represent credentialStatus property. credentialStatus property MUST be ignored if present.
+    - sub Claim MUST represent the id property of credentialSubject property. credentialSubject property MUST be ignored if present.
+
+  IETF SD-JWT VC is extended with the following claims:
+
+    - vcdm: OPTIONAL. Contains properties defined in [@!W3C.VCDM1.1] or [@!W3C.VCDM2.0] that are not represented by their counterpart JWT Claims as defined above.
+
+  The following outlines a suggested non-normative processing steps for SD-JWT VCDM:
+
+    - SD-JWT VC Processing:
+
+      A receiver (holder or verifier) of an SD-JWT VCDM applies the processing rules outlined in Section 4 of [@!I-D.ietf-oauth-sd-jwt-vc], including verifying signatures, validity periods, status information, etc.
+      If the vct value is associated with any SD-JWT VC Type Metadata, schema validation of the entire SD-JWT VCDM is performed, including the nested vcdm claim.
+      Additionally, trust framework rules are applied, such as ensuring the issuer is authorized to issue SD-JWT VCDMs for the specified vct value.
+
+    - Business Logic Processing:
+
+      Once the SD-JWT VC is verified and trusted by the SD-JWT VC processor, and if the vcdm claim is present, the receiver extracts the VCDM (1.1 or 2.0) object from the vcdm claim and uses this for the business logic object. If the vcdm claim is not present, the entire SD-JWT VC is considered to represent the business logic object.
+      The business logic object is then passed on for further use case-specific processing and validation. The business logic assumes that all security-critical functions (e.g., signature verification, trusted issuer) have already been performed during the previous step. Additional schema validation is applied if provided in the vcdm claim, e.g., to support SHACL schemas. Note that while a vct claim is required, SD-JWT VC type metadata resolution and related schema validation is optional in certain cases.
+
+ */
+
+import { SdJwtVcPayload } from '@sd-jwt/sd-jwt-vc';
+
+export type SDJwtVcdmPayload =
+  | {
+      vct: string;
+      vcdm: Vcdm;
+    }
+  | SdJwtVcPayload;
+
+export enum VcType {
+  SD_JWT_VC = 'sd-jwt-vc',
+  W3C_VCDM = 'w3c-vcdm',
+}
+
+export type Vcdm = {
+  '@context': string[];
+  type: string[];
+  credentialSubject: Record<string, unknown>;
+  [key: string]: unknown;
+};