@idos-network/credentials 1.2.0 → 2.2.0

package/dist/utils/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/utils/index.ts"],"sourcesContent":["import { Ed25519VerificationKey2020 } from \"@digitalbazaar/ed25519-verification-key-2020\";\nimport { base64Decode, base64Encode, hexEncode, utf8Encode } from \"@idos-network/utils/codecs\";\nimport * as base85 from \"base85\";\nimport { every, get } from \"es-toolkit/compat\";\nimport invariant from \"tiny-invariant\";\nimport nacl from \"tweetnacl\";\n\nimport type {\n  AvailableIssuerType,\n  CredentialFields,\n  CredentialResidentialAddress,\n  CredentialSubject,\n  CredentialSubjectFaceId,\n  CustomIssuerType,\n  InsertableIDOSCredential,\n} from \"../types\";\n\nexport function fileToBase85(file: Buffer): string {\n  return base85.encode(file, \"ascii85\");\n}\n\nexport function base85ToFile(data: string): Buffer | false {\n  return base85.decode(data);\n}\n\nexport function capitalizeFirstLetter(str: string): string {\n  return str[0].toUpperCase() + str.slice(1);\n}\n\nfunction isIssuerKey(issuer: AvailableIssuerType): issuer is Ed25519VerificationKey2020 {\n  return (\n    typeof issuer === \"object\" &&\n    issuer !== null &&\n    \"type\" in issuer &&\n    \"id\" in issuer &&\n    \"controller\" in issuer\n  );\n}\n\nfunction isCustomIssuerType(issuer: AvailableIssuerType): issuer is CustomIssuerType {\n  return (\n    typeof issuer === \"object\" &&\n    issuer !== null &&\n    \"issuer\" in issuer &&\n    \"publicKeyMultibase\" in issuer\n  );\n}\n\nexport async function issuerToKey(\n  issuer: AvailableIssuerType,\n): Promise<Ed25519VerificationKey2020> {\n  if (isIssuerKey(issuer)) {\n    return issuer;\n  }\n\n  if (isCustomIssuerType(issuer)) {\n    return await Ed25519VerificationKey2020.from({\n      id: `${issuer.issuer}/keys/1`,\n      controller: `${issuer.issuer}/issuers/1`,\n      publicKeyMultibase: issuer.publicKeyMultibase,\n      privateKeyMultibase: issuer.privateKeyMultibase,\n      type: \"Ed25519VerificationKey2020\",\n    });\n  }\n\n  return await Ed25519VerificationKey2020.from({ ...issuer, type: \"Ed25519VerificationKey2020\" });\n}\n\nexport function convertValues<\n  K extends\n    | CredentialFields\n    | CredentialSubject\n    | CredentialResidentialAddress\n    | CredentialSubjectFaceId,\n>(fields: K, prefix?: string): Record<string, unknown> {\n  const acc: Record<string, unknown> = {};\n\n  for (const key in fields) {\n    if (Object.hasOwn(fields, key)) {\n      const value = fields[key];\n      const name = prefix ? `${prefix}${capitalizeFirstLetter(key)}` : key;\n      if (value instanceof Date) {\n        acc[name] = value.toISOString();\n      } else if (value instanceof Buffer) {\n        // Convert file to base85\n        acc[name] = fileToBase85(value);\n      } else {\n        acc[name] = value;\n      }\n    }\n  }\n\n  return acc;\n}\n\ntype BaseLevel = \"basic\" | \"plus\";\ntype Addon = \"liveness\" | \"email\" | \"phoneNumber\";\n\nexport function deriveLevel(credential: CredentialSubject): string {\n  let level: BaseLevel = \"basic\";\n\n  // Address is a sign for plus+\n  const address = credential.residentialAddress;\n  if (address?.proofFile && address?.city && address?.proofCategory) {\n    level = \"plus\";\n  }\n\n  const addons: Addon[] = [];\n  if (credential.selfieFile) {\n    addons.push(\"liveness\");\n  }\n\n  if (credential.email) {\n    addons.push(\"email\");\n  }\n\n  if (credential.phoneNumber) {\n    addons.push(\"phoneNumber\");\n  }\n\n  return [level, ...addons].join(\"+\");\n}\n\nexport function parseLevel(level: string): {\n  base: BaseLevel;\n  addons: Addon[];\n} {\n  const [base, ...addons] = level.split(\"+\") as [BaseLevel, ...Addon[]];\n  return { base, addons };\n}\n\nexport function matchLevelOrHigher(\n  level: BaseLevel,\n  requiredAddons: Addon[],\n  currentLevel: string,\n): boolean {\n  const { base: currentBaseLevel, addons: currentAddons } = parseLevel(currentLevel);\n\n  // TODO: Consider pop+ or uniqueness+ scenarios\n  if (level === \"plus\" && currentBaseLevel !== \"plus\") {\n    return false;\n  }\n\n  return requiredAddons.every((addon) => currentAddons.includes(addon));\n}\n\nexport function levelScore(level: string): number {\n  const { base, addons } = parseLevel(level);\n  let score = 0;\n\n  if (base === \"plus\") {\n    score += 100;\n  }\n\n  score += addons.length * 10;\n\n  return score;\n}\n\nexport function pickHighestMatchingLevel(\n  levels: string[],\n  requiredLevel: BaseLevel,\n  requiredAddons: Addon[],\n): string | null {\n  return (\n    levels\n      .filter((currentLevel) => matchLevelOrHigher(requiredLevel, requiredAddons, currentLevel))\n      .sort((a, b) => {\n        const aAddons = levelScore(a);\n        const bAddons = levelScore(b);\n        return bAddons - aAddons; // descending\n      })[0] ?? null\n  );\n}\n\nexport function highestMatchingCredential<K extends { public_notes: string }>(\n  credentials: K[],\n  requiredLevel: BaseLevel,\n  {\n    addons: requiredAddons = [],\n    publicNotesConstraint = {},\n  }: {\n    addons?: Addon[];\n    publicNotesConstraint?: Record<string, number | string>;\n  },\n): K | undefined {\n  const matchingCredentials = credentials\n    .map((credential) => {\n      const publicNotes = JSON.parse(credential.public_notes || \"{}\");\n      return {\n        credential,\n        publicNotes,\n      };\n    })\n    .filter(({ publicNotes }) => {\n      const level = publicNotes.level;\n\n      if (!level) {\n        return false;\n      }\n\n      if (!matchLevelOrHigher(requiredLevel, requiredAddons, level)) {\n        return false;\n      }\n\n      for (const key in publicNotesConstraint) {\n        if (publicNotes[key] !== publicNotesConstraint[key]) {\n          return false;\n        }\n      }\n\n      return true;\n    })\n    .sort((a, b) => {\n      const aLevel = a.publicNotes.level;\n      const bLevel = b.publicNotes.level;\n      return levelScore(bLevel) - levelScore(aLevel); // descending\n    })\n    .map(({ credential }) => credential);\n\n  return matchingCredentials[0];\n}\n\nexport function recordFilter(\n  rec: Record<string, unknown>,\n  pick: Record<string, unknown[]>,\n  omit: Record<string, unknown[]>,\n): boolean {\n  const matchCriteria = (content: Record<string, unknown>, criteria: Record<string, unknown[]>) =>\n    every(Object.entries(criteria), ([path, targetSet]) => targetSet.includes(get(content, path)));\n\n  if (Object.keys(pick).length > 0 && !matchCriteria(rec, pick)) {\n    // Fast fail on pick criteria\n    return false;\n  }\n\n  if (Object.keys(omit).length > 0 && matchCriteria(rec, omit)) {\n    // Fast fail on omit criteria\n    return false;\n  }\n\n  return true;\n}\n\nexport function buildInsertableIDOSCredential(\n  userId: string,\n  publicNotes: string,\n  content: string,\n  encryptorPublicKey: string,\n): InsertableIDOSCredential {\n  invariant(encryptorPublicKey, \"Missing `encryptorPublicKey`\");\n\n  const ephemeralAuthenticationKeyPair = nacl.sign.keyPair();\n\n  const publicNotesSignature = nacl.sign.detached(\n    utf8Encode(publicNotes),\n    ephemeralAuthenticationKeyPair.secretKey,\n  );\n\n  return {\n    user_id: userId,\n    content,\n\n    public_notes: publicNotes,\n    public_notes_signature: base64Encode(publicNotesSignature),\n\n    broader_signature: base64Encode(\n      nacl.sign.detached(\n        Uint8Array.from([...publicNotesSignature, ...base64Decode(content)]),\n        ephemeralAuthenticationKeyPair.secretKey,\n      ),\n    ),\n\n    issuer_auth_public_key: hexEncode(ephemeralAuthenticationKeyPair.publicKey, true),\n    encryptor_public_key: encryptorPublicKey,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/utils/issuer.ts","../../src/utils/index.ts"],"sourcesContent":["import { Ed25519VerificationKey2020 } from \"@digitalbazaar/ed25519-verification-key-2020\";\n\nimport type { AvailableIssuerType, CustomIssuerType } from \"../types\";\n\nfunction isIssuerKey(issuer: AvailableIssuerType): issuer is Ed25519VerificationKey2020 {\n  return (\n    typeof issuer === \"object\" &&\n    issuer !== null &&\n    \"type\" in issuer &&\n    \"id\" in issuer &&\n    \"controller\" in issuer\n  );\n}\n\nfunction isCustomIssuerType(issuer: AvailableIssuerType): issuer is CustomIssuerType {\n  return (\n    typeof issuer === \"object\" &&\n    issuer !== null &&\n    \"issuer\" in issuer &&\n    \"publicKeyMultibase\" in issuer\n  );\n}\n\nexport async function issuerToKey(\n  issuer: AvailableIssuerType,\n): Promise<Ed25519VerificationKey2020> {\n  if (isIssuerKey(issuer)) {\n    return issuer;\n  }\n\n  if (isCustomIssuerType(issuer)) {\n    return await Ed25519VerificationKey2020.from({\n      id: `${issuer.issuer}/keys/1`,\n      controller: `${issuer.issuer}/issuers/1`,\n      publicKeyMultibase: issuer.publicKeyMultibase,\n      privateKeyMultibase: issuer.privateKeyMultibase,\n      type: \"Ed25519VerificationKey2020\",\n    });\n  }\n\n  return await Ed25519VerificationKey2020.from({ ...issuer, type: \"Ed25519VerificationKey2020\" });\n}\n","import { createBlobContentReference } from \"@idos-network/utils/blob-gateway\";\nimport { base64Encode, hexEncode, utf8Encode } from \"@idos-network/utils/codecs\";\nimport { encryptContent } from \"@idos-network/utils/cryptography\";\nimport { every, get } from \"es-toolkit/compat\";\nimport nacl from \"tweetnacl\";\n\nimport type { idOSCredential, SignedCredentialContentReference } from \"../types\";\n\n// Proxying functions\nexport * from \"./issuer\";\n\nexport type BaseLevel = \"unverified\" | \"basic\" | \"plus\";\nexport type Addon =\n  | \"liveness\"\n  | \"email\"\n  | \"phoneNumber\"\n  | \"edd\"\n  | \"sow\"\n  | \"screening\"\n  | \"onboarding\";\n\nexport function parseLevel(level: string): {\n  base: BaseLevel;\n  addons: Addon[];\n} {\n  const [base, ...addons] = level.split(\"+\") as [BaseLevel, ...Addon[]];\n  return { base, addons };\n}\n\nexport function assertNoExtraFields(\n  section: string,\n  expectedFields: ReadonlySet<string>,\n  value: object | undefined,\n): void {\n  const extraFields = Object.keys(value ?? {}).filter((field) => !expectedFields.has(field));\n\n  if (extraFields.length > 0) {\n    throw new Error(`Unexpected ${section} fields: ${extraFields.join(\", \")}`);\n  }\n}\n\nexport function matchLevelOrHigher(\n  level: BaseLevel,\n  requiredAddons: Addon[],\n  currentLevel: string,\n): boolean {\n  const { base: currentBaseLevel, addons: currentAddons } = parseLevel(currentLevel);\n\n  // Basic can only match basic or plus not unverified\n  if (level === \"basic\" && currentBaseLevel === \"unverified\") {\n    return false;\n  }\n\n  // Plus can only match plus\n  if (level === \"plus\" && currentBaseLevel !== \"plus\") {\n    return false;\n  }\n\n  return requiredAddons.every((addon) => currentAddons.includes(addon));\n}\n\nexport function levelScore(level: string): number {\n  const { base, addons } = parseLevel(level);\n  let score = 0;\n\n  if (base === \"basic\") {\n    score += 50;\n  }\n\n  if (base === \"plus\") {\n    score += 100;\n  }\n\n  score += addons.length * 10;\n\n  return score;\n}\n\nexport function pickHighestMatchingLevel(\n  levels: string[],\n  requiredLevel: BaseLevel,\n  requiredAddons: Addon[],\n): string | null {\n  return (\n    levels\n      .filter((currentLevel) => matchLevelOrHigher(requiredLevel, requiredAddons, currentLevel))\n      .sort((a, b) => {\n        const aAddons = levelScore(a);\n        const bAddons = levelScore(b);\n        return bAddons - aAddons; // descending\n      })[0] ?? null\n  );\n}\n\nexport function highestMatchingCredential<K extends { public_notes: string }>(\n  credentials: K[],\n  requiredLevel: BaseLevel,\n  {\n    addons: requiredAddons = [],\n    publicNotesConstraint = {},\n  }: {\n    addons?: Addon[];\n    publicNotesConstraint?: Record<string, number | string>;\n  },\n): K | undefined {\n  const matchingCredentials = credentials\n    .map((credential) => {\n      const publicNotes = JSON.parse(credential.public_notes || \"{}\");\n      return {\n        credential,\n        publicNotes,\n      };\n    })\n    .filter(({ publicNotes }) => {\n      const level = publicNotes.level;\n\n      if (!level) {\n        return false;\n      }\n\n      if (!matchLevelOrHigher(requiredLevel, requiredAddons, level)) {\n        return false;\n      }\n\n      for (const key in publicNotesConstraint) {\n        if (publicNotes[key] !== publicNotesConstraint[key]) {\n          return false;\n        }\n      }\n\n      return true;\n    })\n    .sort((a, b) => {\n      const aLevel = a.publicNotes.level;\n      const bLevel = b.publicNotes.level;\n      return levelScore(bLevel) - levelScore(aLevel); // descending\n    })\n    .map(({ credential }) => credential);\n\n  return matchingCredentials[0];\n}\n\nexport function recordFilter(\n  rec: Record<string, unknown>,\n  pick: Record<string, unknown[]>,\n  omit: Record<string, unknown[]>,\n): boolean {\n  const matchCriteria = (content: Record<string, unknown>, criteria: Record<string, unknown[]>) =>\n    every(Object.entries(criteria), ([path, targetSet]) => targetSet.includes(get(content, path)));\n\n  if (Object.keys(pick).length > 0 && !matchCriteria(rec, pick)) {\n    // Fast fail on pick criteria\n    return false;\n  }\n\n  if (Object.keys(omit).length > 0 && matchCriteria(rec, omit)) {\n    // Fast fail on omit criteria\n    return false;\n  }\n\n  return true;\n}\n\nexport function buildSignedCredentialContentReference(\n  publicNotes: string,\n  contentUri: string,\n  issuerSigningSecretKey: Uint8Array,\n): SignedCredentialContentReference {\n  const { publicKey, secretKey } = nacl.sign.keyPair.fromSecretKey(issuerSigningSecretKey);\n\n  const publicNotesSignature = nacl.sign.detached(utf8Encode(publicNotes), secretKey);\n\n  return {\n    public_notes: publicNotes,\n    public_notes_signature: base64Encode(publicNotesSignature),\n\n    broader_signature: base64Encode(\n      nacl.sign.detached(\n        Uint8Array.from([...publicNotesSignature, ...utf8Encode(contentUri)]),\n        secretKey,\n      ),\n    ),\n\n    issuer_auth_public_key: hexEncode(publicKey, true),\n  };\n}\n\n/** User-issued share copy: sign with a fresh ephemeral key (need not match original issuer). */\nexport function buildEphemeralSignedCredentialContentReference(\n  publicNotes: string,\n  contentUri: string,\n): SignedCredentialContentReference {\n  return buildSignedCredentialContentReference(\n    publicNotes,\n    contentUri,\n    nacl.sign.keyPair().secretKey,\n  );\n}\n\nexport type PreliminaryIDOSCredential = {\n  id: string;\n  contentUri: string;\n  contentSize: number;\n  encryptedContent: Uint8Array;\n  publicNotes: string;\n  publicNotesSignature: string;\n  broaderSignature: string;\n  issuerAuthPublicKey: string;\n  encryptorPublicKey: string;\n};\n\nexport function mapPreliminaryToIDOSCredential(\n  preliminaryCredential: PreliminaryIDOSCredential,\n): Omit<idOSCredential, \"user_id\"> {\n  return {\n    id: preliminaryCredential.id,\n    content_uri: preliminaryCredential.contentUri,\n    content_size: preliminaryCredential.contentSize,\n    public_notes: preliminaryCredential.publicNotes,\n    issuer_auth_public_key: preliminaryCredential.issuerAuthPublicKey,\n    encryptor_public_key: preliminaryCredential.encryptorPublicKey,\n  };\n}\n\nexport interface BuildPreliminaryIDOSCredentialArgs {\n  publicNotes: string;\n  plaintextContent: Uint8Array;\n  recipientEncryptionPublicKey: Uint8Array;\n  issuerSigningSecretKey?: Uint8Array;\n  /** When set (MM / `ukyc://`), skip IPFS CID hashing. */\n  contentUri?: string;\n}\n\nexport async function buildPreliminaryIDOSCredential({\n  publicNotes,\n  plaintextContent,\n  recipientEncryptionPublicKey,\n  // For user-issued credentials, use a fresh ephemeral key for the signed reference\n  // For issuer-side, use the signing key pair\n  issuerSigningSecretKey = nacl.sign.keyPair().secretKey,\n  contentUri,\n}: BuildPreliminaryIDOSCredentialArgs): Promise<Omit<PreliminaryIDOSCredential, \"id\">> {\n  const ephemeralKeyPair = nacl.box.keyPair();\n  const encryptedContent = encryptContent(\n    plaintextContent,\n    recipientEncryptionPublicKey, // user or dwg recipient\n    ephemeralKeyPair.secretKey,\n  );\n\n  const contentReference = contentUri\n    ? { uri: contentUri, size: encryptedContent.byteLength }\n    : await createBlobContentReference(encryptedContent);\n  const signedReference = buildSignedCredentialContentReference(\n    publicNotes,\n    contentReference.uri,\n    issuerSigningSecretKey,\n  );\n\n  return {\n    contentUri: contentReference.uri,\n    contentSize: contentReference.size,\n    encryptedContent,\n    publicNotes,\n    publicNotesSignature: signedReference.public_notes_signature,\n    broaderSignature: signedReference.broader_signature,\n    issuerAuthPublicKey: signedReference.issuer_auth_public_key,\n    encryptorPublicKey: base64Encode(ephemeralKeyPair.publicKey),\n  };\n}\n"],"mappings":"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"}

package/dist/verifier/index.d.mts

@@ -0,0 +1,8 @@
+import { i as VerifiableCredential, t as AvailableIssuerType } from "../index-WW372Tf5.mjs";
+import * as vc from "@digitalbazaar/vc";
+import { JsonLDDocumentLoaderInstance } from "jsonld-document-loader";
+//#region src/verifier/index.d.ts
+export type VerifyCredentialResult = [boolean, Map<AvailableIssuerType, vc.VerifyCredentialResult>];
+export declare function verifyCredential<K>(credential: VerifiableCredential<K>, issuers: AvailableIssuerType[], customDocumentLoader?: JsonLDDocumentLoaderInstance): Promise<VerifyCredentialResult>;
+//#endregion
+//# sourceMappingURL=index.d.mts.map

package/dist/verifier/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/verifier/index.ts"],"mappings":";;;;YAUY,mCAAmC,IAAI,qBAAqB,GAAG;wBAErD,iBAAiB,GACrC,YAAY,qBAAqB,IACjC,SAAS,uBACT,uBAAuB,+BACtB,QAAQ"}

package/dist/verifier/index.mjs

@@ -0,0 +1,2 @@
+import{issuerToKey as e}from"../utils/index.mjs";import{u as t}from"../loader-Cg6hs1-P.mjs";import{Ed25519Signature2020 as n}from"@digitalbazaar/ed25519-signature-2020";import*as r from"@digitalbazaar/vc";async function i(i,a,o){let s=new Map;for(let c of a){let a=await e(c),l=new n({key:a,verificationMethod:a.id}),u={"@context":`https://w3id.org/security/v2`,id:a.controller,assertionMethod:[a.id],authentication:[a.id]},d=await r.verifyCredential({credential:i,suite:l,controller:u,documentLoader:o??t});if(s.set(c,d),d.verified)return[!0,s]}return[!1,s]}export{i as verifyCredential};
+//# sourceMappingURL=index.mjs.map

package/dist/verifier/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/verifier/index.ts"],"sourcesContent":["import type { JsonLDDocumentLoaderInstance } from \"jsonld-document-loader\";\n\nimport { Ed25519Signature2020 } from \"@digitalbazaar/ed25519-signature-2020\";\nimport * as vc from \"@digitalbazaar/vc\";\n\nimport type { AvailableIssuerType, VerifiableCredential } from \"../types\";\n\nimport { issuerToKey } from \"../utils\";\nimport { defaultDocumentLoader } from \"../utils/loader\";\n\nexport type VerifyCredentialResult = [boolean, Map<AvailableIssuerType, vc.VerifyCredentialResult>];\n\nexport async function verifyCredential<K>(\n  credential: VerifiableCredential<K>,\n  issuers: AvailableIssuerType[],\n  customDocumentLoader?: JsonLDDocumentLoaderInstance,\n): Promise<VerifyCredentialResult> {\n  const resultsByIssuer: Map<AvailableIssuerType, vc.VerifyCredentialResult> = new Map();\n\n  for (const issuer of issuers) {\n    const publicKey = await issuerToKey(issuer);\n\n    const vcVerifyingSuite = new Ed25519Signature2020({\n      key: publicKey,\n      verificationMethod: publicKey.id,\n    });\n\n    const controller = {\n      \"@context\": \"https://w3id.org/security/v2\",\n      id: publicKey.controller,\n      assertionMethod: [publicKey.id],\n      authentication: [publicKey.id],\n    };\n\n    // Verify the signature\n    const verifyCredentialResult = await vc.verifyCredential<K>({\n      credential,\n      suite: vcVerifyingSuite,\n      controller,\n      documentLoader: customDocumentLoader ?? defaultDocumentLoader,\n    });\n\n    resultsByIssuer.set(issuer, verifyCredentialResult);\n\n    if (verifyCredentialResult.verified) {\n      return [true, resultsByIssuer];\n    }\n  }\n\n  return [false, resultsByIssuer];\n}\n"],"mappings":"6MAYA,eAAsB,EACpB,EACA,EACA,EACiC,CACjC,IAAM,EAAuE,IAAI,IAEjF,IAAK,IAAM,KAAU,EAAS,CAC5B,IAAM,EAAY,MAAM,EAAY,CAAM,EAEpC,EAAmB,IAAI,EAAqB,CAChD,IAAK,EACL,mBAAoB,EAAU,EAChC,CAAC,EAEK,EAAa,CACjB,WAAY,+BACZ,GAAI,EAAU,WACd,gBAAiB,CAAC,EAAU,EAAE,EAC9B,eAAgB,CAAC,EAAU,EAAE,CAC/B,EAGM,EAAyB,MAAM,EAAG,iBAAoB,CAC1D,aACA,MAAO,EACP,aACA,eAAgB,GAAwB,CAC1C,CAAC,EAID,GAFA,EAAgB,IAAI,EAAQ,CAAsB,EAE9C,EAAuB,SACzB,MAAO,CAAC,GAAM,CAAe,CAEjC,CAEA,MAAO,CAAC,GAAO,CAAe,CAChC"}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@idos-network/credentials",
-  "version": "1.2.0",
+  "version": "2.2.0",
   "description": "idOS Credentials JavaScript SDK",
   "homepage": "https://idos.network",
   "license": "MIT",
-  "repository": "github:idos-network/idos-sdk-js",
+  "repository": {
+    "type": "git",
+    "url": "github:idos-network/idos-sdk-js"
+  },
   "files": [
     "assets/**/*",
     "dist/**/*",
@@ -25,13 +28,21 @@
       "types": "./dist/utils/index.d.mts",
       "import": "./dist/utils/index.mjs"
     },
-    "./builder": {
-      "types": "./dist/builder/index.d.mts",
-      "import": "./dist/builder/index.mjs"
+    "./verifier": {
+      "types": "./dist/verifier/index.d.mts",
+      "import": "./dist/verifier/index.mjs"
+    },
+    "./parser": {
+      "types": "./dist/parser/index.d.mts",
+      "import": "./dist/parser/index.mjs"
     },
     "./types": {
       "types": "./dist/types/index.d.mts",
       "import": "./dist/types/index.mjs"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.mts",
+      "import": "./dist/schemas/index.mjs"
     }
   },
   "publishConfig": {
@@ -40,24 +51,27 @@
   "dependencies": {
     "@digitalbazaar/ed25519-signature-2020": "^5.4.0",
     "@digitalbazaar/ed25519-verification-key-2020": "^4.2.0",
-    "@digitalbazaar/vc": "^7.2.0",
-    "base85": "^3.1.0",
-    "es-toolkit": "^1.39.0",
+    "@digitalbazaar/vc": "^7.3.0",
+    "@idos-network/utils": "2.2.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "es-toolkit": "^1.50.0",
     "jsonld-document-loader": "^2.3.0",
+    "reflect-metadata": "^0.2.2",
     "tiny-invariant": "^1.3.3",
     "tweetnacl": "^1.0.3",
-    "zod": "4.4.3",
-    "@idos-network/utils": "1.2.0"
+    "zod": "4.5.4"
   },
   "devDependencies": {
-    "@types/node": "25.6.2",
-    "tsdown": "^0.22.0",
-    "typescript": "^5.8.3",
-    "vitest": "4.1.5",
+    "@types/node": "25.9.5",
+    "@vitest/coverage-v8": "4.1.11",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.11",
     "web-streams-polyfill": "3.3.3"
   },
   "peerDependencies": {
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.3"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -65,9 +79,11 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown  --watch",
+    "generate:schemas": "pnpm build && node ./cli/generate-schemas.mjs",
     "publint": "pnpx publint --strict",
     "test": "vitest",
     "test:watch": "vitest --watch",
+    "coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit"
   }
 }

package/src/parser/index.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it } from "vitest";
+
+import type { VerifiableCredential } from "../types";
+
+import { parseCredential } from ".";
+import {
+  VerifiableCredentialEddV1,
+  VerifiableCredentialFaceIdV1,
+  VerifiableCredentialKycV1,
+  VerifiableCredentialKycV2,
+  VerifiableCredentialKycV3,
+} from "../schemas";
+import { CredentialValidationError } from "../schemas/utils";
+
+const ISSUER = "https://vc-issuers.cool.id/idos";
+const CRED_ID = `${ISSUER}/credentials/z6MkszZtxCmA2Ce4vUV132PCuLQmwnaDD5mw2L23fGNnsiX3`;
+const CREDENTIALS_V1_CONTEXT =
+  "https://idos-network.github.io/idos-sdk-js/credentials/idos-credentials-v1.json";
+const CREDENTIALS_V2_CONTEXT =
+  "https://idos-network.github.io/idos-sdk-js/credentials/idos-credentials-v2.json";
+const FACE_ID_V1_SUBJECT_CONTEXT =
+  "https://idos-network.github.io/idos-sdk-js/credentials/idos-credential-subject-face-id-v1.json";
+const KYC_V1_SUBJECT_CONTEXT =
+  "https://idos-network.github.io/idos-sdk-js/credentials/idos-credential-subject-v1.json";
+const KYC_V2_SUBJECT_CONTEXT =
+  "https://idos-network.github.io/idos-sdk-js/credentials/idos-credential-subject-v2.json";
+const KYC_V3_SUBJECT_CONTEXT =
+  "https://idos-network.github.io/idos-sdk-js/credentials/idos-credential-subject-v3.json";
+const EDD_V1_SUBJECT_CONTEXT =
+  "https://idos-network.github.io/idos-sdk-js/credentials/idos-credential-subject-edd-v1.json";
+const FRONT_FILE = "<~7WNEbF8~>";
+const PROOF_FILE = "<~:i^JmAc~>";
+const SELFIE_FILE = "<~;e9cWBk7~>";
+const envelopeFields = {
+  id: CRED_ID,
+  level: "human",
+  kycLevel: 1,
+  issued: new Date("2022-01-01").toISOString(),
+  approvedAt: new Date("2022-01-01").toISOString(),
+  expirationDate: new Date("2030-01-01").toISOString(),
+};
+
+const proof = {
+  type: "Ed25519Signature2020",
+  created: new Date("2022-01-01").toISOString(),
+  verificationMethod: `${ISSUER}/keys/1`,
+  proofValue: "proof",
+  proofPurpose: "assertionMethod",
+};
+
+function credential<TSubject>(
+  envelopeContext: string,
+  credentialSubject: TSubject,
+): VerifiableCredential<TSubject> & typeof envelopeFields {
+  return {
+    "@context": ["https://www.w3.org/2018/credentials/v1", envelopeContext],
+    type: ["VerifiableCredential"],
+    issuer: ISSUER,
+    ...envelopeFields,
+    credentialSubject,
+    issuanceDate: envelopeFields.issued,
+    proof,
+  };
+}
+
+describe("parseCredential", () => {
+  it("returns a deserialized KYC v3 container", async () => {
+    const parsed = await parseCredential(
+      credential(CREDENTIALS_V2_CONTEXT, {
+        "@context": [KYC_V3_SUBJECT_CONTEXT],
+        id: "uuid:abc",
+        personFirstName: "John",
+        personFamilyName: "Lennon",
+        personGender: "M",
+        personNationality: "US",
+        personDateOfBirth: "1980-01-01T00:00:00.000Z",
+        personPlaceOfBirth: "New York, NY",
+        idDocumentCountry: "US",
+        idDocumentNumber: "123456789",
+        idDocumentType: "PASSPORT",
+        idDocumentDateOfIssue: "2022-01-01T00:00:00.000Z",
+        idDocumentDateOfExpiry: "2025-01-01T00:00:00.000Z",
+        idDocumentFrontFile: FRONT_FILE,
+        idDocumentFrontFileType: "image/jpeg",
+        idDocumentFrontFileName: "front.jpg",
+        contactEmail: "john@example.com",
+        contactPhoneNumber: "+1234567890",
+        biometricSelfieFile: SELFIE_FILE,
+        residentialAddressSource: "PROOF_OF_ADDRESS",
+        residentialAddressStreet: "Main St",
+        residentialAddressCity: "New York",
+        residentialAddressCountry: "US",
+        residentialAddressProofCategory: "UTILITY_BILL",
+        residentialAddressProofFile: PROOF_FILE,
+        residentialAddressProofFileType: "image/jpeg",
+        residentialAddressProofFileName: "proof.jpg",
+        screeningSanctionsCheckResult: "CLEAR",
+        screeningPepCheckResult: "CLEAR",
+        sourceOfWealthType: "SALARY",
+        sourceOfWealthYearlyGrossIncome: "LESS_THAN_20000",
+        sourceOfWealthYearlyGrossIncomeCurrency: "EUR",
+        sourceOfWealthApproximateNetWorth: "UP_TO_25000",
+        sourceOfWealthApproximateNetWorthCurrency: "EUR",
+        sourceOfWealthSourceOfWealthProofFile: PROOF_FILE,
+      }),
+    );
+
+    expect(parsed).toBeInstanceOf(VerifiableCredentialKycV3);
+    if (!(parsed instanceof VerifiableCredentialKycV3)) throw new Error("expected kyc v3");
+    expect(parsed.subject.id).toBe("uuid:abc");
+    expect(parsed.subject.person).toEqual({
+      firstName: "John",
+      familyName: "Lennon",
+      gender: "M",
+      nationality: "US",
+      dateOfBirth: new Date("1980-01-01T00:00:00.000Z"),
+      placeOfBirth: "New York, NY",
+    });
+    expect(parsed.subject.idDocument).toMatchObject({
+      country: "US",
+      number: "123456789",
+      type: "PASSPORT",
+      dateOfIssue: new Date("2022-01-01T00:00:00.000Z"),
+      dateOfExpiry: new Date("2025-01-01T00:00:00.000Z"),
+    });
+    expect(parsed.subject.idDocument?.frontFile?.toString()).toBe("Front");
+    expect(parsed.subject.contact).toEqual({
+      email: "john@example.com",
+      phoneNumber: "+1234567890",
+    });
+    expect(parsed.subject.biometric?.selfieFile.toString()).toBe("Selfie");
+    expect(parsed.subject.residentialAddress).toMatchObject({
+      street: "Main St",
+      city: "New York",
+      country: "US",
+      proofCategory: "UTILITY_BILL",
+    });
+    expect(parsed.subject.residentialAddress?.proofFile?.toString()).toBe("Proof");
+    expect(parsed.subject.screening).toEqual({
+      sanctionsCheckResult: "CLEAR",
+      pepCheckResult: "CLEAR",
+    });
+    expect(parsed.subject.sourceOfWealth).toMatchObject({
+      type: "SALARY",
+      yearlyGrossIncome: "LESS_THAN_20000",
+      approximateNetWorth: "UP_TO_25000",
+    });
+    expect(parsed.subject.sourceOfWealth?.sourceOfWealthProofFile?.toString()).toBe("Proof");
+  });
+
+  it("returns a deserialized FaceId v1 container", async () => {
+    const parsed = await parseCredential(
+      credential(CREDENTIALS_V1_CONTEXT, {
+        "@context": [FACE_ID_V1_SUBJECT_CONTEXT],
+        faceSignUserId: "11111111-1111-1111-1111-111111111111",
+      }),
+    );
+
+    expect(parsed).toBeInstanceOf(VerifiableCredentialFaceIdV1);
+    if (!(parsed instanceof VerifiableCredentialFaceIdV1)) throw new Error("expected faceId");
+    expect(parsed.subject.faceSignUserId).toBe("11111111-1111-1111-1111-111111111111");
+  });
+
+  it("returns a deserialized KYC v1 container", async () => {
+    const parsed = await parseCredential(
+      credential(CREDENTIALS_V1_CONTEXT, {
+        "@context": [KYC_V1_SUBJECT_CONTEXT],
+        id: "uuid:v1",
+        firstName: "Ada",
+        idDocumentCountry: "US",
+        idDocumentNumber: "123456789",
+        idDocumentType: "PASSPORT",
+        idDocumentFrontFile: FRONT_FILE,
+      }),
+    );
+
+    expect(parsed).toBeInstanceOf(VerifiableCredentialKycV1);
+    if (!(parsed instanceof VerifiableCredentialKycV1)) throw new Error("expected kyc v1");
+    expect(parsed.subject.id).toBe("uuid:v1");
+    expect(parsed.subject.firstName).toBe("Ada");
+    expect(parsed.subject.idDocument).toMatchObject({
+      country: "US",
+      number: "123456789",
+      type: "PASSPORT",
+    });
+    expect(parsed.subject.idDocument?.frontFile?.toString()).toBe("Front");
+  });
+
+  it("returns a deserialized KYC v2 container", async () => {
+    const parsed = await parseCredential(
+      credential(CREDENTIALS_V1_CONTEXT, {
+        "@context": [KYC_V2_SUBJECT_CONTEXT],
+        id: "uuid:v2",
+        firstName: "Grace",
+        dateOfBirth: "1906-12-09T00:00:00.000Z",
+        selfieFile: SELFIE_FILE,
+      }),
+    );
+
+    expect(parsed).toBeInstanceOf(VerifiableCredentialKycV2);
+    if (!(parsed instanceof VerifiableCredentialKycV2)) throw new Error("expected kyc v2");
+    expect(parsed.subject.id).toBe("uuid:v2");
+    expect(parsed.subject.firstName).toBe("Grace");
+    expect(parsed.subject.dateOfBirth).toEqual(new Date("1906-12-09T00:00:00.000Z"));
+    expect(parsed.subject.selfieFile).toEqual(Buffer.from("Selfie"));
+  });
+
+  it("returns a deserialized EDD v1 container", async () => {
+    const parsed = await parseCredential(
+      credential(CREDENTIALS_V1_CONTEXT, {
+        "@context": [EDD_V1_SUBJECT_CONTEXT],
+        id: "uuid:edd",
+        eddOccupation: "AGRICULTURE",
+        eddSourceOfFundsCategory: "SALARY",
+        eddSourceOfFundsProofFile: PROOF_FILE,
+      }),
+    );
+
+    expect(parsed).toBeInstanceOf(VerifiableCredentialEddV1);
+    if (!(parsed instanceof VerifiableCredentialEddV1)) throw new Error("expected edd v1");
+    expect(parsed.subject.id).toBe("uuid:edd");
+    expect(parsed.subject.edd?.occupation).toBe("AGRICULTURE");
+    expect(parsed.subject.edd?.sourceOfFundsProofFile?.toString()).toBe("Proof");
+  });
+
+  it("throws for an unknown subject context", async () => {
+    await expect(
+      parseCredential(credential("unknown-envelope", { "@context": "unknown-subject" })),
+    ).rejects.toThrow("Unknown credential");
+  });
+
+  it("rejects a matching KYC v3 context with invalid subject data", async () => {
+    await expect(
+      parseCredential(
+        credential(CREDENTIALS_V2_CONTEXT, {
+          "@context": [KYC_V3_SUBJECT_CONTEXT],
+          id: "uuid:abc",
+          personFirstName: "John",
+          personNationality: "US",
+          personDateOfBirth: "1980-01-01T00:00:00.000Z",
+          personGender: "MALE", // invalid: enum is M | F | OTHER
+          // invalid: mandatory idDocument section is missing entirely
+        }),
+      ),
+    ).rejects.toThrow(CredentialValidationError);
+  });
+
+  it("rejects a subject field the matched context does not define", async () => {
+    await expect(
+      parseCredential(
+        credential(CREDENTIALS_V2_CONTEXT, {
+          "@context": [KYC_V3_SUBJECT_CONTEXT],
+          id: "uuid:abc",
+          personFirstName: "John",
+          personNationality: "US",
+          personDateOfBirth: "1980-01-01T00:00:00.000Z",
+          idDocumentType: "PASSPORT",
+          idDocumentNumber: "123456789",
+          idDocumentCountry: "US",
+          idDocumentFrontFile: FRONT_FILE,
+          unexpectedJsonLdField: "breaks-json-ld",
+        }),
+      ),
+    ).rejects.toThrow("Unexpected subject fields: unexpectedJsonLdField");
+  });
+});

package/src/parser/index.ts

@@ -0,0 +1,69 @@
+import type { VerifiableCredential } from "../types";
+
+import {
+  VerifiableCredentialEddV1,
+  VerifiableCredentialFaceIdV1,
+  VerifiableCredentialKycV1,
+  VerifiableCredentialKycV2,
+  VerifiableCredentialKycV3,
+} from "../schemas";
+
+type CredentialWithContext = VerifiableCredential<unknown>;
+
+/** Every version `parseCredential` can return. */
+export type ParsedCredential =
+  | VerifiableCredentialEddV1
+  | VerifiableCredentialFaceIdV1
+  | VerifiableCredentialKycV1
+  | VerifiableCredentialKycV2
+  | VerifiableCredentialKycV3;
+
+/*
+ * Matched on the subject `@context`, which is unique per version — several versions share an
+ * envelope context, so that one cannot tell them apart.
+ */
+const VERSIONS: { readonly subjectContext: string; new (): ParsedCredential }[] = [
+  VerifiableCredentialEddV1,
+  VerifiableCredentialFaceIdV1,
+  VerifiableCredentialKycV1,
+  VerifiableCredentialKycV2,
+  VerifiableCredentialKycV3,
+];
+
+function hasContext(input: CredentialWithContext, context: string): boolean {
+  if (
+    typeof input.credentialSubject !== "object" ||
+    input.credentialSubject === null ||
+    Array.isArray(input.credentialSubject)
+  ) {
+    return false;
+  }
+
+  const value = (input.credentialSubject as Record<string, unknown>)["@context"];
+  return Array.isArray(value) ? value.includes(context) : value === context;
+}
+
+/**
+ * Deserializes a credential into its typed version by matching the subject `@context`, then
+ * validates it. A credential that does not match the context it claims is rejected here rather
+ * than at the first property access: a subject field the context does not define throws, and one
+ * it promises but the credential omits fails with `CredentialValidationError`.
+ *
+ * SECURITY: this does NOT verify the credential's signature. The returned version reflects
+ * whatever was in `input`, signed or forged. For untrusted input, call `verifyCredential()`
+ * (from `@idos-network/credentials/verifier`) first and only parse once it reports verified.
+ */
+export async function parseCredential(input: CredentialWithContext): Promise<ParsedCredential> {
+  for (const Version of VERSIONS) {
+    if (!hasContext(input, Version.subjectContext)) continue;
+
+    const credential = new Version();
+
+    await credential.deserialize(input);
+    credential.checkValidity();
+
+    return credential;
+  }
+
+  throw new Error("Unknown credential");
+}

package/src/schemas/EddV1/index.test.ts

@@ -0,0 +1,40 @@
+import { base85ToFile } from "@idos-network/utils/codecs";
+import { describe, expect, it } from "vitest";
+
+import { EddV1 } from "./index";
+
+describe("EddV1", () => {
+  it("serializes the edd section with its prefix", () => {
+    const credential = new EddV1()
+      .setEnvelope({ id: "https://issuer.example/credentials/edd1-123" })
+      .setSubject({ id: "https://issuer.example/credentials/edd1-123" })
+      .addSection("edd", {
+        occupation: "AGRICULTURE",
+        sourceOfFundsCategory: "BUSINESS_OWNER",
+        sourceOfFundsProofFile: Buffer.from("proof of source of funds"),
+      });
+
+    expect(credential.level()).toBe("edd");
+    expect(credential.publicNotes()).toEqual({ type: "edd", level: "edd" });
+
+    const serialized = credential.serializeSubject();
+    expect(serialized.eddOccupation).toBe("AGRICULTURE");
+    expect(serialized.eddSourceOfFundsCategory).toBe("BUSINESS_OWNER");
+    expect(base85ToFile(serialized.eddSourceOfFundsProofFile as string)?.toString()).toBe(
+      "proof of source of funds",
+    );
+  });
+
+  it("requires the edd section, and rejects an unknown occupation", () => {
+    expect(() =>
+      new EddV1()
+        .setEnvelope({ id: "https://issuer.example/credentials/edd1-123" })
+        .setSubject({ id: "uuid:abc" })
+        .checkValidity(),
+    ).toThrow(/edd/);
+
+    expect(() => new EddV1().addSection("edd", { occupation: "ASTRONAUT" as never })).toThrow(
+      /occupation/,
+    );
+  });
+});

package/src/schemas/EddV1/index.ts

@@ -0,0 +1,53 @@
+import { IsDefined, IsIn, IsOptional, IsString } from "class-validator";
+
+import type { PublicNotes } from "../types";
+
+import { CONTEXT_IDOS_CREDENTIAL_V1, CONTEXT_IDOS_CREDENTIAL_V1_EDD } from "../../utils/loader";
+import { Occupations, type Occupation } from "../enums";
+import { EnvelopeV1 } from "../Envelope";
+import { Base85FileField, Section } from "../utils";
+import { VerifiableCredentialBase } from "../VerifiableCredential";
+
+/** The same fields as KycV3's `edd` section, here as a credential of its own. */
+export class EDD {
+  /* The person's occupation or job title. */
+  @IsOptional()
+  @IsIn(Occupations)
+  occupation?: Occupation;
+
+  /* The origin of money used in transactions (e.g. salary, business income, savings). */
+  @IsOptional()
+  @IsString()
+  sourceOfFundsCategory?: string;
+
+  /* A file containing proof of the person's source of funds. */
+  @IsOptional()
+  @Base85FileField()
+  sourceOfFundsProofFile?: Buffer;
+}
+
+export class Subject {
+  @IsString()
+  id: string;
+
+  @Section(() => EDD)
+  @IsDefined()
+  edd: EDD;
+}
+
+export class EddV1 extends VerifiableCredentialBase<EnvelopeV1, Subject> {
+  static readonly envelopeContext: string = CONTEXT_IDOS_CREDENTIAL_V1;
+  static readonly subjectContext: string = CONTEXT_IDOS_CREDENTIAL_V1_EDD;
+
+  constructor() {
+    super(EnvelopeV1, Subject);
+  }
+
+  override level(): string {
+    return "edd";
+  }
+
+  override publicNotes(): PublicNotes {
+    return { type: "edd", level: this.level() };
+  }
+}

package/src/schemas/Envelope.ts

@@ -0,0 +1,37 @@
+import { IsInt, IsOptional, IsPositive, IsString } from "class-validator";
+
+import { IsoDateField } from "./utils";
+
+/** The envelope: the credential's own fields, alongside `credentialSubject`. */
+export class EnvelopeV1 {
+  @IsString()
+  id: string;
+
+  /* Level of KYC verification performed (e.g. basic, plus+liveness). */
+  @IsString()
+  level: string;
+
+  /* Date the credential was approved. */
+  @IsOptional()
+  @IsoDateField()
+  approvedAt?: Date;
+}
+
+/** `EnvelopeV1` plus a numeric KYC level and the issuance/expiry dates. */
+export class EnvelopeV2 extends EnvelopeV1 {
+  /* Level of KYC verification performed (1, 2 or 3). */
+  @IsOptional()
+  @IsInt()
+  @IsPositive()
+  kycLevel?: number;
+
+  /* @default new Date() */
+  @IsOptional()
+  @IsoDateField()
+  issued?: Date;
+
+  /* Date the credential expires. */
+  @IsOptional()
+  @IsoDateField()
+  expirationDate?: Date;
+}