@idos-network/credentials 1.2.0 → 2.2.0

package/src/schemas/integration.test.ts

@@ -0,0 +1,251 @@
+import { Ed25519VerificationKey2020 } from "@digitalbazaar/ed25519-verification-key-2020";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { parseCredential } from "../parser";
+import { verifyCredential } from "../verifier";
+import * as S from "./index";
+import { flatFieldsOf } from "./utils";
+
+const assetsDir = fileURLToPath(new URL("../../assets", import.meta.url));
+
+const issuer = "https://my-issuer.id";
+const key = await Ed25519VerificationKey2020.generate({
+  id: `${issuer}/keys/1`,
+  controller: `${issuer}/issuers/1`,
+});
+const env = { id: `${issuer}/credentials/1`, approvedAt: new Date("2022-01-01") };
+
+// Every version issued, verified, and parsed: JSON-LD @protected rejects undefined terms,
+// so this is what proves the generated contexts actually cover the classes.
+describe("all versions issue + verify + parse", () => {
+  it("KycV1", async () => {
+    const c = new S.VerifiableCredentialKycV1()
+      .setEnvelope(env)
+      .setSubject({
+        id: "uuid:v1",
+        applicantId: "a1",
+        inquiryId: "i1",
+        firstName: "Ada",
+        middleName: "M",
+        nationality: "GB",
+        familyName: "L",
+        maidenName: "B",
+        gender: "F",
+        governmentId: "g",
+        governmentIdType: "NATIONAL_ID",
+        email: "a@b.com",
+        ssn: "1",
+        phoneNumber: "+1",
+        dateOfBirth: new Date("1815-12-10"),
+        placeOfBirth: "London",
+        selfieFile: Buffer.from("Selfie"),
+      })
+      .addSection("idDocument", {
+        country: "GB",
+        number: "1",
+        type: "PASSPORT",
+        dateOfIssue: new Date("2020-01-01"),
+        dateOfExpiry: new Date("2030-01-01"),
+        frontFile: Buffer.from("F"),
+        backFile: Buffer.from("B"),
+      })
+      .addSection("residentialAddress", {
+        street: "S",
+        houseNumber: "1",
+        additionalAddressInfo: "x",
+        region: "R",
+        city: "London",
+        postalCode: "P",
+        country: "GB",
+        proofCategory: "UTILITY_BILL",
+        proofDateOfIssue: new Date("2021-01-01"),
+        proofFile: Buffer.from("P"),
+      });
+    const vc = await c.issue(key);
+    expect((await verifyCredential(vc, [key]))[0]).toBe(true);
+    expect(await parseCredential(vc)).toBeInstanceOf(S.VerifiableCredentialKycV1);
+  });
+
+  it("KycV2", async () => {
+    const c = new S.VerifiableCredentialKycV2()
+      .setEnvelope({
+        ...env,
+        kycLevel: 2,
+        issued: new Date("2022-01-01"),
+        expirationDate: new Date("2030-01-01"),
+      })
+      .setSubject({
+        id: "uuid:v2",
+        firstName: "Ada",
+        middleName: "M",
+        nationality: "GB",
+        familyName: "L",
+        maidenName: "B",
+        gender: "F",
+        email: "a@b.com",
+        phoneNumber: "+1",
+        ssn: "1",
+        dateOfBirth: new Date("1815-12-10"),
+        placeOfBirth: "London",
+        selfieFile: Buffer.from("S"),
+      })
+      .addSection("idDocument", {
+        country: "GB",
+        number: "1",
+        type: "PASSPORT",
+        frontFile: Buffer.from("F"),
+      });
+    const vc = await c.issue(key);
+    expect((await verifyCredential(vc, [key]))[0]).toBe(true);
+    expect(await parseCredential(vc)).toBeInstanceOf(S.VerifiableCredentialKycV2);
+  });
+
+  it("EddV1", async () => {
+    const c = new S.VerifiableCredentialEddV1()
+      .setEnvelope(env)
+      .setSubject({ id: "uuid:edd" })
+      .addSection("edd", {
+        occupation: "AGRICULTURE",
+        sourceOfFundsCategory: "SALARY",
+        sourceOfFundsProofFile: Buffer.from("P"),
+      });
+    const vc = await c.issue(key);
+    expect((await verifyCredential(vc, [key]))[0]).toBe(true);
+    expect(await parseCredential(vc)).toBeInstanceOf(S.VerifiableCredentialEddV1);
+  });
+
+  it("FaceIdV1", async () => {
+    const c = new S.VerifiableCredentialFaceIdV1()
+      .setEnvelope(env)
+      .setSubject({ faceSignUserId: "11111111-1111-1111-1111-111111111111" });
+    const vc = await c.issue(key);
+    expect((await verifyCredential(vc, [key]))[0]).toBe(true);
+    expect(await parseCredential(vc)).toBeInstanceOf(S.VerifiableCredentialFaceIdV1);
+  });
+
+  it("KycV3 with every section populated", async () => {
+    const c = new S.VerifiableCredentialKycV3()
+      .setEnvelope(env)
+      .setSubject({ id: "uuid:v3" })
+      .addSection("person", {
+        firstName: "J",
+        familyName: "D",
+        middleName: "M",
+        fatherName: "F",
+        maidenName: "N",
+        motherName: "MO",
+        gender: "M",
+        nationality: "US",
+        secondNationality: "GB",
+        dateOfBirth: new Date("1990-01-01"),
+        placeOfBirth: "NY",
+        regionOfBirth: "NY",
+        stateless: false,
+        refugeeStatus: false,
+        subsidiaryProtectionStatus: false,
+        nationalIdNumber: "1",
+        taxIdNumber: "2",
+        taxIdIssuingCountry: "US",
+        taxResidenceCountry: "US",
+        ssn: "3",
+      })
+      .addSection("idDocument", {
+        type: "PASSPORT",
+        number: "1",
+        country: "US",
+        dateOfExpiry: new Date("2030-01-01"),
+        dateOfIssue: new Date("2020-01-01"),
+        issuingAuthority: "DOS",
+        frontFile: Buffer.from("F"),
+        frontFileType: "image/jpeg",
+        frontFileName: "front.jpg",
+        backFile: Buffer.from("B"),
+        backFileType: "image/jpeg",
+        backFileName: "back.jpg",
+        mrzLine1: "P<USA",
+        title: "Dr",
+        extendedValidUntil: new Date("2031-01-01"),
+        additionalNumber: "9",
+        ethnicity: "x",
+        issuingSubdivision: "CA",
+      })
+      .addSection("contact", { email: "j@e.com", phoneNumber: "+1" })
+      .addSection("biometric", { selfieFile: Buffer.from("S"), selfieMatch: 99 })
+      .addSection("residentialAddress", {
+        source: "PROOF_OF_ADDRESS",
+        street: "S",
+        houseNumber: "1",
+        additionalAddressInfo: "x",
+        region: "R",
+        city: "NY",
+        postalCode: "P",
+        country: "US",
+        proofCategory: "UTILITY_BILL",
+        proofDateOfIssue: new Date("2021-01-01"),
+        proofFile: Buffer.from("P"),
+        proofFileType: "image/jpeg",
+        proofFileName: "proof.jpg",
+        ipCountry: "US",
+      })
+      .addSection("screening", {
+        sanctionsCheckResult: "CLEAR",
+        sanctionsConfidenceScore: 95,
+        pepCheckResult: "CLEAR",
+        pepConfidenceScore: 10,
+      })
+      .addSection("edd", {
+        occupation: "REAL_ESTATE",
+        sourceOfFundsCategory: "SALARY",
+        sourceOfFundsProofFile: Buffer.from("F"),
+        sourceOfFundsProofFileType: "application/pdf",
+        sourceOfFundsProofFileName: "funds.pdf",
+      })
+      .addSection("sourceOfWealth", {
+        type: "SALARY",
+        yearlyGrossIncome: "LESS_THAN_20000",
+        yearlyGrossIncomeCurrency: "EUR",
+        approximateNetWorth: "UP_TO_25000",
+        approximateNetWorthCurrency: "EUR",
+        sourceOfWealthProofFile: Buffer.from("P"),
+      })
+      .addSection("onboarding", {
+        intendedUse: "INVESTING",
+        employmentStatus: "EMPLOYED",
+        expectedMonthlyTransactionCount: "LESS_THAN_5",
+        expectedMonthlyTransactionVolume: "MORE_THAN_500_LESS_THAN_2000",
+        expectedMonthlyTransactionVolumeCurrency: "EUR",
+      });
+    const vc = await c.issue(key);
+    expect((await verifyCredential(vc, [key]))[0]).toBe(true);
+    const parsed = await parseCredential(vc);
+    expect(parsed).toBeInstanceOf(S.VerifiableCredentialKycV3);
+    expect(c.kycLevel()).toBe(3);
+  });
+});
+
+// Every generated context key must be a key the class accepts, and vice versa.
+describe("generated contexts match the classes", () => {
+  const cases = [
+    ["idos-credential-subject-v1", S.VerifiableCredentialKycV1],
+    ["idos-credential-subject-v2", S.VerifiableCredentialKycV2],
+    ["idos-credential-subject-v3", S.VerifiableCredentialKycV3],
+    ["idos-credential-subject-face-id-v1", S.VerifiableCredentialFaceIdV1],
+    ["idos-credential-subject-edd-v1", S.VerifiableCredentialEddV1],
+  ] as const;
+
+  it.each(cases)("%s", async (asset, Version) => {
+    const ctx = JSON.parse(readFileSync(`${assetsDir}/${asset}.json`, "utf8"))["@context"];
+    const ctxKeys = Object.keys(ctx).filter(
+      (k) => !k.startsWith("@") && k !== "xsd" && k !== "aux",
+    );
+    // biome-ignore lint: reading a private field for review purposes
+    const accepted = flatFieldsOf((new Version() as any).subjectClass);
+    const notAccepted = ctxKeys.filter((k) => !accepted.has(k));
+    const notInContext = [...accepted].filter(
+      (k) => !ctxKeys.includes(k) && !["id", "issued", "expirationDate"].includes(k),
+    );
+    expect({ notAccepted, notInContext }).toEqual({ notAccepted: [], notInContext: [] });
+  });
+});

package/src/schemas/types.ts

@@ -0,0 +1,11 @@
+/**
+ * A value a credential may publish in its unencrypted public notes.
+ *
+ * A `Date` is accepted here, but public notes travel as JSON: once stored, a `Date` is an
+ * ISO string, and every consumer reads it as one.
+ */
+export type PublicNotesAllowedValues = number | string | Date | undefined;
+export type PublicNotes = Record<
+  string,
+  PublicNotesAllowedValues | Record<string, PublicNotesAllowedValues> | undefined
+>;

package/src/schemas/utils.ts

@@ -0,0 +1,274 @@
+import "reflect-metadata";
+import { base85ToFile, fileToBase85 } from "@idos-network/utils/codecs";
+import { Transform, Type, instanceToPlain, plainToInstance } from "class-transformer";
+import {
+  IsDate,
+  IsInstance,
+  ValidateIf,
+  ValidateNested,
+  type ValidationError,
+  getMetadataStorage,
+  validateSync,
+} from "class-validator";
+
+/*
+ * A credential subject travels the wire flat: every section is merged into one object with
+ * its own name as a prefix (`person` + `firstName` -> `personFirstName`), while `root`
+ * contributes its fields unprefixed. `@Section` records the mapping so both directions are
+ * derived from the class instead of being generated or hand-written per version.
+ */
+
+const SECTIONS = Symbol("idos:sections");
+
+type Ctor<T> = new () => T;
+
+interface SectionMeta {
+  property: string;
+  prefix: string;
+  type: () => Ctor<object>;
+}
+
+function flatKey(prefix: string, field: string): string {
+  return prefix ? `${prefix}${field.charAt(0).toUpperCase()}${field.slice(1)}` : field;
+}
+
+/**
+ * Declares a property as a flattened section, and wires up the nested class for
+ * class-transformer and class-validator. Pass `prefix: ""` to keep the section's field
+ * names as they are — that is what `root` does.
+ *
+ * Presence stays the caller's business: pair with `@IsDefined()` for a mandatory section
+ * or `@IsOptional()` for an optional one.
+ */
+export function Section(type: () => Ctor<object>, prefix?: string): PropertyDecorator {
+  return (target, propertyKey) => {
+    const property = String(propertyKey);
+
+    /*
+     * Read inherited sections but define our own copy, so a subclass extending a subject
+     * sees its parent's sections without mutating the parent's array.
+     */
+    const own = Reflect.getOwnMetadata(SECTIONS, target.constructor) as SectionMeta[] | undefined;
+    const sections = own ?? [
+      ...((Reflect.getMetadata(SECTIONS, target.constructor) as SectionMeta[] | undefined) ?? []),
+    ];
+
+    sections.push({ property, prefix: prefix ?? property, type });
+    Reflect.defineMetadata(SECTIONS, sections, target.constructor);
+
+    Type(type)(target, propertyKey);
+    ValidateNested()(target, propertyKey);
+  };
+}
+
+export function sectionsOf(cls: Ctor<object>): SectionMeta[] {
+  return (Reflect.getMetadata(SECTIONS, cls) as SectionMeta[] | undefined) ?? [];
+}
+
+/**
+ * The field names of a class, taken from its validation metadata — which is why every
+ * field needs at least one validation decorator to survive a round trip. Inherited fields
+ * are included.
+ */
+export function fieldsOf(cls: Ctor<object>): string[] {
+  const metadata = getMetadataStorage().getTargetValidationMetadatas(cls, cls.name, true, false);
+
+  return [...new Set(metadata.map((entry) => entry.propertyName))];
+}
+
+/**
+ * Flattens an instance to its wire form. Classes declaring `@Section` properties merge
+ * those sections in with their prefixes; anything else contributes its own fields.
+ * Undefined values are dropped rather than emitted as explicit `undefined` keys.
+ */
+export function toFlat<T extends object>(instance: T): Record<string, unknown> {
+  const plain = instanceToPlain(instance) as Record<string, unknown>;
+  const sections = new Map(
+    sectionsOf(instance.constructor as Ctor<object>).map(({ property, prefix }) => [
+      property,
+      prefix,
+    ]),
+  );
+  const flat: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(plain)) {
+    /*
+     * A key the class declares as a section is merged in with its prefix; anything else is a
+     * field of the class itself, like the subject's `id`, and travels as it is.
+     */
+    if (!sections.has(key)) {
+      if (value !== undefined) flat[key] = value;
+      continue;
+    }
+
+    if (!value) continue;
+
+    const prefix = sections.get(key) as string;
+
+    for (const [field, nested] of Object.entries(value as Record<string, unknown>)) {
+      if (nested !== undefined) flat[flatKey(prefix, field)] = nested;
+    }
+  }
+
+  return flat;
+}
+
+/** The flat wire keys a class accepts: its own fields, plus each section's prefixed fields. */
+export function flatFieldsOf(cls: Ctor<object>): Set<string> {
+  const sections = sectionsOf(cls);
+  const sectionProperties = new Set(sections.map(({ property }) => property));
+  const keys = fieldsOf(cls).filter((field) => !sectionProperties.has(field));
+
+  for (const { prefix, type } of sections) {
+    for (const field of fieldsOf(type())) keys.push(flatKey(prefix, field));
+  }
+
+  return new Set(keys);
+}
+
+/**
+ * Rebuilds an instance from its wire form, the inverse of `toFlat`. Only keys the class
+ * declares are read, so extras a credential happens to carry (`proof`, `@context`, an
+ * unknown section) are dropped instead of landing on the instance.
+ */
+export function fromFlat<T extends object>(cls: Ctor<T>, flat: Record<string, unknown>): T {
+  const sections = sectionsOf(cls);
+  const sectionProperties = new Set(sections.map(({ property }) => property));
+  const nested: Record<string, unknown> = {};
+
+  // The class's own fields — everything it declares that is not a section, like a subject's `id`.
+  for (const field of fieldsOf(cls)) {
+    if (!sectionProperties.has(field) && Object.hasOwn(flat, field)) nested[field] = flat[field];
+  }
+
+  for (const { property, prefix, type } of sections) {
+    const section: Record<string, unknown> = {};
+
+    for (const field of fieldsOf(type())) {
+      const key = flatKey(prefix, field);
+
+      if (Object.hasOwn(flat, key)) section[field] = flat[key];
+    }
+
+    // An absent section stays absent — an empty object would validate as a broken section.
+    if (Object.keys(section).length > 0) nested[property] = section;
+  }
+
+  return plainToInstance(cls, nested);
+}
+
+/**
+ * Builds an instance from the subset of a class's fields a caller passed, applying the class's
+ * `toClassOnly` transforms — so either form of a value is accepted: an ISO string or a `Date`,
+ * ascii85 or a `Buffer`.
+ *
+ * Fields the caller left out stay absent rather than becoming an explicit `undefined`, which
+ * would overwrite a section already added.
+ */
+export function toClass<T extends object>(cls: Ctor<T>, fields: object): Partial<T> {
+  const instance = plainToInstance(cls, fields) as Record<string, unknown>;
+
+  return Object.fromEntries(Object.keys(fields).map((key) => [key, instance[key]])) as Partial<T>;
+}
+
+function describe(errors: ValidationError[], path = ""): string[] {
+  return errors.flatMap((error) => {
+    const at = path ? `${path}.${error.property}` : error.property;
+
+    return [
+      ...Object.values(error.constraints ?? {}).map((message) => `${at}: ${message}`),
+      ...describe(error.children ?? [], at),
+    ];
+  });
+}
+
+export class CredentialValidationError extends Error {
+  override readonly name = "CredentialValidationError";
+
+  constructor(
+    label: string,
+    readonly errors: ValidationError[],
+  ) {
+    super(`Invalid ${label}: ${describe(errors).join("; ")}`);
+  }
+}
+
+/** Throws `CredentialValidationError` unless `instance` and its sections are valid. */
+export function assertValid(label: string, instance: object): void {
+  const errors = validateSync(instance);
+
+  if (errors.length > 0) throw new CredentialValidationError(label, errors);
+}
+
+/**
+ * Validates this property when `predicate` holds, and whenever it carries a value — so a
+ * conditionally required field is still type-checked when the condition is off.
+ *
+ * Do not combine with `@IsOptional()`: that skips every validator on an absent value,
+ * including this one.
+ */
+export function RequiredWhen(predicate: (object: any) => boolean): PropertyDecorator {
+  return (target, propertyKey) =>
+    ValidateIf(
+      (object: Record<string, unknown>) =>
+        predicate(object) || object[String(propertyKey)] !== undefined,
+    )(target, propertyKey);
+}
+
+/** `RequiredWhen`, for the common case of a field required by the presence of another. */
+export function RequiredWith(property: string): PropertyDecorator {
+  return RequiredWhen((object: Record<string, unknown>) => object[property] !== undefined);
+}
+
+/*
+ * Codecs: the encoded side is what a serialized credential carries, the decoded side is
+ * what a subject holds. A field declares its representation once, and neither direction
+ * inspects value types at serialization time.
+ */
+
+function decorate(...decorators: PropertyDecorator[]): PropertyDecorator {
+  return (target, propertyKey) => {
+    for (const decorator of decorators) decorator(target, propertyKey);
+  };
+}
+
+/** A date carried as an ISO 8601 string on the wire, held as a `Date` in a subject. */
+export function IsoDateField(): PropertyDecorator {
+  return decorate(
+    Transform(({ value }) => (value instanceof Date ? value.toISOString() : value), {
+      toPlainOnly: true,
+    }),
+    Transform(({ value }) => (typeof value === "string" ? new Date(value) : value), {
+      toClassOnly: true,
+    }),
+    // `new Date("nonsense")` yields an Invalid Date, which `IsDate` rejects.
+    IsDate(),
+  );
+}
+
+/** `fileToBase85` always emits delimited ascii85; `base85.decode` accepts anything. */
+const ASCII85_FRAMED = /^<~[\s\S]*~>$/;
+
+/** A file carried as ascii85 on the wire, held as a `Buffer` in a subject. */
+export function Base85FileField(): PropertyDecorator {
+  return decorate(
+    Transform(({ value }) => (Buffer.isBuffer(value) ? fileToBase85(value) : value), {
+      toPlainOnly: true,
+    }),
+    /*
+     * Undecodable input is handed on untouched so `IsInstance` reports it, rather than
+     * being turned into a `false` that reads like an intentional value.
+     */
+    Transform(
+      ({ value }) => {
+        if (typeof value !== "string" || !ASCII85_FRAMED.test(value)) return value;
+
+        return base85ToFile(value) || value;
+      },
+      { toClassOnly: true },
+    ),
+    IsInstance(Buffer, {
+      message: ({ property }) => `${property} must be a file encoded as delimited ascii85`,
+    }),
+  );
+}