@idos-network/credentials 1.5.0 → 2.2.2

package/src/schemas/FaceIdV1/index.ts

@@ -0,0 +1,33 @@
+import { IsString } from "class-validator";
+
+import type { PublicNotes } from "../types";
+
+import { CONTEXT_IDOS_CREDENTIAL_V1, CONTEXT_IDOS_CREDENTIAL_V1_FACE_ID } from "../../utils/loader";
+import { EnvelopeV1 } from "../Envelope";
+import { VerifiableCredentialBase } from "../VerifiableCredential";
+
+/*
+ * One field and no sections, so the subject lives here rather than in a file of its own.
+ * No `id`: unlike the other versions, this subject has never declared one.
+ */
+export class Subject {
+  @IsString()
+  faceSignUserId: string;
+}
+
+export class FaceIdV1 extends VerifiableCredentialBase<EnvelopeV1, Subject> {
+  static readonly envelopeContext: string = CONTEXT_IDOS_CREDENTIAL_V1;
+  static readonly subjectContext: string = CONTEXT_IDOS_CREDENTIAL_V1_FACE_ID;
+
+  constructor() {
+    super(EnvelopeV1, Subject);
+  }
+
+  override level(): string {
+    return "human";
+  }
+
+  override publicNotes(): PublicNotes {
+    return { type: "pop", level: this.level() };
+  }
+}

package/src/schemas/KycV1/IdDocument.ts

@@ -0,0 +1,41 @@
+import { IsOptional, IsString, IsISO31661Alpha2 } from "class-validator";
+
+import { Base85FileField, IsoDateField } from "../utils";
+
+/** The identity document, as v1 and v2 describe it: every field optional and untyped. */
+export class IdDocument {
+  /* The country of issuance of the identity document (ISO 3166-1 alpha-2). */
+  @IsOptional()
+  @IsISO31661Alpha2()
+  country?: string;
+
+  /* The unique number on the identity document. */
+  @IsOptional()
+  @IsString()
+  number?: string;
+
+  /* The type of identity document (e.g. PASSPORT, ID_CARD, DRIVERS). */
+  @IsOptional()
+  @IsString()
+  type?: string;
+
+  /* The date the identity document was issued. */
+  @IsOptional()
+  @IsoDateField()
+  dateOfIssue?: Date;
+
+  /* The date the identity document expires. */
+  @IsOptional()
+  @IsoDateField()
+  dateOfExpiry?: Date;
+
+  /* The file containing the front of the identity document. */
+  @IsOptional()
+  @Base85FileField()
+  frontFile?: Buffer;
+
+  /* The file containing the back of the identity document. */
+  @IsOptional()
+  @Base85FileField()
+  backFile?: Buffer;
+}

package/src/schemas/KycV1/ResidentialAddress.ts

@@ -0,0 +1,56 @@
+import { IsOptional, IsString, IsISO31661Alpha2 } from "class-validator";
+
+import { Base85FileField, IsoDateField } from "../utils";
+
+/** The residential address, as v1 and v2 describe it: every field optional, no `verified` flag. */
+export class ResidentialAddress {
+  /* Street address. */
+  @IsOptional()
+  @IsString()
+  street?: string;
+
+  /* House number. */
+  @IsOptional()
+  @IsString()
+  houseNumber?: string;
+
+  /* Additional address information (e.g. apartment number). */
+  @IsOptional()
+  @IsString()
+  additionalAddressInfo?: string;
+
+  /* Region (e.g. state, province). */
+  @IsOptional()
+  @IsString()
+  region?: string;
+
+  /* Locality (e.g. city, town). */
+  @IsOptional()
+  @IsString()
+  city?: string;
+
+  /* Postal code. */
+  @IsOptional()
+  @IsString()
+  postalCode?: string;
+
+  /* Country (ISO 3166-1 alpha-2). */
+  @IsOptional()
+  @IsISO31661Alpha2()
+  country?: string;
+
+  /* Type of document provided to verify the address (e.g. utility bill, bank statement). */
+  @IsOptional()
+  @IsString()
+  proofCategory?: string;
+
+  /* Date the address proof document was issued. */
+  @IsOptional()
+  @IsoDateField()
+  proofDateOfIssue?: Date;
+
+  /* The document provided as address proof. */
+  @IsOptional()
+  @Base85FileField()
+  proofFile?: Buffer;
+}

package/src/schemas/KycV1/Subject.ts

@@ -0,0 +1,86 @@
+import { IsEmail, IsOptional, IsString, IsISO31661Alpha2 } from "class-validator";
+
+import { Base85FileField, IsoDateField, Section } from "../utils";
+import { IdDocument } from "./IdDocument";
+import { ResidentialAddress } from "./ResidentialAddress";
+
+/*
+ * The credential subject. The fields v1 groups under `root` are declared here directly: they
+ * travel unprefixed, which is exactly how a class's own fields are flattened.
+ */
+export class Subject {
+  @IsString()
+  id: string;
+
+  @IsOptional()
+  @IsString()
+  applicantId?: string;
+
+  @IsOptional()
+  @IsString()
+  inquiryId?: string;
+
+  @IsOptional()
+  @IsString()
+  firstName?: string;
+
+  @IsOptional()
+  @IsString()
+  middleName?: string;
+
+  @IsOptional()
+  @IsISO31661Alpha2()
+  nationality?: string;
+
+  @IsOptional()
+  @IsString()
+  familyName?: string;
+
+  @IsOptional()
+  @IsString()
+  maidenName?: string;
+
+  @IsOptional()
+  @IsString()
+  gender?: string;
+
+  @IsOptional()
+  @IsString()
+  governmentId?: string;
+
+  @IsOptional()
+  @IsString()
+  governmentIdType?: string;
+
+  @IsOptional()
+  @IsEmail()
+  email?: string;
+
+  @IsOptional()
+  @IsString()
+  ssn?: string;
+
+  @IsOptional()
+  @IsString()
+  phoneNumber?: string;
+
+  @IsOptional()
+  @IsoDateField()
+  dateOfBirth?: Date;
+
+  @IsOptional()
+  @IsString()
+  placeOfBirth?: string;
+
+  @IsOptional()
+  @Base85FileField()
+  selfieFile?: Buffer;
+
+  @Section(() => IdDocument)
+  @IsOptional()
+  idDocument?: IdDocument;
+
+  @Section(() => ResidentialAddress)
+  @IsOptional()
+  residentialAddress?: ResidentialAddress;
+}

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

@@ -0,0 +1,156 @@
+import { base85ToFile, fileToBase85 } from "@idos-network/utils/codecs";
+import { describe, expect, it } from "vitest";
+
+import type { VerifiableCredential } from "../../types";
+
+import { KycV1 } from "./index";
+
+function serializedCredential(
+  credentialSubject: Record<string, unknown>,
+): VerifiableCredential<unknown> {
+  return {
+    "@context": [],
+    type: ["VerifiableCredential"],
+    issuer: "did:example:issuer",
+    id: "https://issuer.example/credentials/123",
+    level: "basic",
+    approvedAt: new Date("2022-01-01").toISOString(),
+    issuanceDate: new Date("2022-01-01").toISOString(),
+    credentialSubject,
+    proof: { type: "Ed25519Signature2020", proofValue: "proof" },
+  } as unknown as VerifiableCredential<unknown>;
+}
+
+describe("KycV1", () => {
+  it("is valid with only the ids set", () => {
+    const credential = new KycV1()
+      .setEnvelope({ id: "https://issuer.example/credentials/123" })
+      .setSubject({ id: "uuid:abc" });
+
+    expect(() => credential.checkValidity()).not.toThrow();
+  });
+
+  it("derives level from the subject, reaching plus on a complete address proof", () => {
+    const credential = new KycV1().setSubject({
+      id: "uuid:abc",
+      email: "ada@example.com",
+      selfieFile: Buffer.from("Selfie"),
+    });
+
+    expect(credential.level()).toBe("basic+liveness+email");
+
+    credential.addSection("residentialAddress", {
+      city: "London",
+      proofFile: Buffer.from("Proof"),
+    });
+    expect(credential.level()).toBe("basic+liveness+email");
+
+    credential.addSection("residentialAddress", {
+      city: "London",
+      country: "GB",
+      proofCategory: "UTILITY_BILL",
+      proofFile: Buffer.from("Proof"),
+    });
+    expect(credential.level()).toBe("plus+liveness+email");
+    expect(credential.publicNotes()).toEqual({ type: "kyc", level: "plus+liveness+email" });
+  });
+
+  it("flattens the subject, keeping its own fields unprefixed", () => {
+    const credential = new KycV1()
+      .setEnvelope({
+        id: "https://issuer.example/credentials/123",
+        approvedAt: new Date("2022-01-01"),
+      })
+      .setSubject({
+        id: "uuid:abc",
+        firstName: "Ada",
+        familyName: "Lovelace",
+        nationality: "GB",
+        dateOfBirth: new Date("1815-12-10"),
+        selfieFile: Buffer.from("Selfie"),
+      })
+      .addSection("idDocument", {
+        country: "GB",
+        number: "123456789",
+        type: "PASSPORT",
+        dateOfIssue: new Date("2020-01-01"),
+        frontFile: Buffer.from("Front"),
+      })
+      .addSection("residentialAddress", {
+        street: "Main St",
+        city: "London",
+        country: "GB",
+        proofCategory: "UTILITY_BILL",
+        proofFile: Buffer.from("Proof"),
+      });
+
+    const serialized = credential.serializeSubject();
+
+    expect(serialized.id).toBe("uuid:abc");
+    expect(serialized.firstName).toBe("Ada");
+    expect(serialized.dateOfBirth).toBe(new Date("1815-12-10").toISOString());
+    expect(base85ToFile(serialized.selfieFile as string)?.toString()).toBe("Selfie");
+    expect(serialized.idDocumentCountry).toBe("GB");
+    expect(serialized.idDocumentDateOfIssue).toBe(new Date("2020-01-01").toISOString());
+    expect(base85ToFile(serialized.idDocumentFrontFile as string)?.toString()).toBe("Front");
+    expect(serialized.residentialAddressCity).toBe("London");
+    expect(base85ToFile(serialized.residentialAddressProofFile as string)?.toString()).toBe(
+      "Proof",
+    );
+
+    expect("middleName" in serialized).toBe(false);
+    expect("idDocumentBackFile" in serialized).toBe(false);
+  });
+
+  it("round-trips through deserialize", async () => {
+    const roundTrip = new KycV1();
+
+    await roundTrip.deserialize(
+      serializedCredential({
+        id: "uuid:abc",
+        firstName: "Ada",
+        dateOfBirth: new Date("1815-12-10").toISOString(),
+        selfieFile: fileToBase85(Buffer.from("Selfie")),
+        idDocumentType: "PASSPORT",
+        residentialAddressCity: "London",
+      }),
+    );
+
+    expect(roundTrip.subject.id).toBe("uuid:abc");
+    expect(roundTrip.subject.dateOfBirth).toEqual(new Date("1815-12-10"));
+    expect(roundTrip.subject.selfieFile?.toString()).toBe("Selfie");
+    expect(roundTrip.subject.idDocument?.type).toBe("PASSPORT");
+    expect(roundTrip.subject.residentialAddress?.city).toBe("London");
+    expect(roundTrip.envelope.approvedAt).toEqual(new Date("2022-01-01"));
+  });
+
+  it("rejects fields the subject does not declare", async () => {
+    expect(() => new KycV1().setSubject({ id: "x", bogus: 1 } as never)).toThrow(
+      "Unexpected subject fields: bogus",
+    );
+
+    expect(() => new KycV1().addSection("idDocument", { bogus: 1 } as never)).toThrow(
+      "Unexpected idDocument fields: bogus",
+    );
+
+    await expect(
+      new KycV1().deserialize(serializedCredential({ id: "uuid:abc", bogus: 1 })),
+    ).rejects.toThrow("Unexpected subject fields: bogus");
+  });
+
+  it("keeps the applicant and government-id fields v2 dropped", () => {
+    const serialized = new KycV1()
+      .setEnvelope({ id: "https://issuer.example/credentials/123" })
+      .setSubject({
+        id: "uuid:abc",
+        applicantId: "applicant-1",
+        inquiryId: "inquiry-1",
+        governmentId: "gov-1",
+        governmentIdType: "NATIONAL_ID",
+      })
+      .serializeSubject();
+
+    expect(serialized.applicantId).toBe("applicant-1");
+    expect(serialized.governmentIdType).toBe("NATIONAL_ID");
+  });
+});

package/src/schemas/KycV1/index.ts

@@ -0,0 +1,40 @@
+import type { PublicNotes } from "../types";
+
+import { CONTEXT_IDOS_CREDENTIAL_V1, CONTEXT_IDOS_CREDENTIAL_V1_SUBJECT } from "../../utils/loader";
+import { EnvelopeV1 } from "../Envelope";
+import { VerifiableCredentialBase } from "../VerifiableCredential";
+import { Subject } from "./Subject";
+
+export class KycV1 extends VerifiableCredentialBase<EnvelopeV1, Subject> {
+  static readonly envelopeContext: string = CONTEXT_IDOS_CREDENTIAL_V1;
+  static readonly subjectContext: string = CONTEXT_IDOS_CREDENTIAL_V1_SUBJECT;
+
+  constructor() {
+    super(EnvelopeV1, Subject);
+  }
+
+  override level(): string {
+    const { residentialAddress, selfieFile, email, phoneNumber } = this.subject;
+
+    // A complete address proof is the sign of plus.
+    const base =
+      residentialAddress?.proofFile &&
+      residentialAddress.city &&
+      residentialAddress.proofCategory &&
+      residentialAddress.country
+        ? "plus"
+        : "basic";
+
+    const addons = [
+      selfieFile && "liveness",
+      email && "email",
+      phoneNumber && "phoneNumber",
+    ].filter(Boolean);
+
+    return [base, ...addons].join("+");
+  }
+
+  override publicNotes(): PublicNotes {
+    return { type: "kyc", level: this.level() };
+  }
+}

package/src/schemas/KycV2/Subject.ts

@@ -0,0 +1,67 @@
+import { IsEmail, IsOptional, IsString, IsISO31661Alpha2 } from "class-validator";
+
+import { IdDocument } from "../KycV1/IdDocument";
+import { ResidentialAddress } from "../KycV1/ResidentialAddress";
+import { Base85FileField, IsoDateField, Section } from "../utils";
+
+/** v1's subject, minus the applicant/inquiry and government-id fields v2 dropped. */
+export class Subject {
+  @IsString()
+  id: string;
+
+  @IsOptional()
+  @IsString()
+  firstName?: string;
+
+  @IsOptional()
+  @IsString()
+  middleName?: string;
+
+  @IsOptional()
+  @IsISO31661Alpha2()
+  nationality?: string;
+
+  @IsOptional()
+  @IsString()
+  familyName?: string;
+
+  @IsOptional()
+  @IsString()
+  maidenName?: string;
+
+  @IsOptional()
+  @IsString()
+  gender?: string;
+
+  @IsOptional()
+  @IsEmail()
+  email?: string;
+
+  @IsOptional()
+  @IsString()
+  phoneNumber?: string;
+
+  @IsOptional()
+  @IsString()
+  ssn?: string;
+
+  @IsOptional()
+  @IsoDateField()
+  dateOfBirth?: Date;
+
+  @IsOptional()
+  @IsString()
+  placeOfBirth?: string;
+
+  @IsOptional()
+  @Base85FileField()
+  selfieFile?: Buffer;
+
+  @Section(() => IdDocument)
+  @IsOptional()
+  idDocument?: IdDocument;
+
+  @Section(() => ResidentialAddress)
+  @IsOptional()
+  residentialAddress?: ResidentialAddress;
+}

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

@@ -0,0 +1,162 @@
+import { base85ToFile, fileToBase85 } from "@idos-network/utils/codecs";
+import { describe, expect, it } from "vitest";
+
+import type { VerifiableCredential } from "../../types";
+
+import { KycV2 } from "./index";
+
+function serializedCredential(
+  credentialSubject: Record<string, unknown>,
+): VerifiableCredential<unknown> {
+  return {
+    "@context": [],
+    type: ["VerifiableCredential"],
+    issuer: "did:example:issuer",
+    id: "https://issuer.example/credentials/123",
+    level: "basic",
+    approvedAt: new Date("2022-01-01").toISOString(),
+    issuanceDate: new Date("2022-01-01").toISOString(),
+    credentialSubject,
+    proof: { type: "Ed25519Signature2020", proofValue: "proof" },
+  } as unknown as VerifiableCredential<unknown>;
+}
+
+describe("KycV2", () => {
+  it("is valid with only the ids set", () => {
+    const credential = new KycV2()
+      .setEnvelope({ id: "https://issuer.example/credentials/123" })
+      .setSubject({ id: "uuid:abc" });
+
+    expect(() => credential.checkValidity()).not.toThrow();
+  });
+
+  it("derives level from the subject, reaching plus on a complete address proof", () => {
+    const credential = new KycV2().setSubject({
+      id: "uuid:abc",
+      email: "ada@example.com",
+      selfieFile: Buffer.from("Selfie"),
+    });
+
+    expect(credential.level()).toBe("basic+liveness+email");
+
+    credential.addSection("residentialAddress", {
+      city: "London",
+      proofFile: Buffer.from("Proof"),
+    });
+    expect(credential.level()).toBe("basic+liveness+email");
+
+    credential.addSection("residentialAddress", {
+      city: "London",
+      country: "GB",
+      proofCategory: "UTILITY_BILL",
+      proofFile: Buffer.from("Proof"),
+    });
+    expect(credential.level()).toBe("plus+liveness+email");
+    expect(credential.publicNotes()).toEqual({ type: "kyc", level: "plus+liveness+email" });
+  });
+
+  it("flattens the subject, keeping its own fields unprefixed", () => {
+    const credential = new KycV2()
+      .setEnvelope({
+        id: "https://issuer.example/credentials/123",
+        approvedAt: new Date("2022-01-01"),
+      })
+      .setSubject({
+        id: "uuid:abc",
+        firstName: "Ada",
+        familyName: "Lovelace",
+        nationality: "GB",
+        dateOfBirth: new Date("1815-12-10"),
+        selfieFile: Buffer.from("Selfie"),
+      })
+      .addSection("idDocument", {
+        country: "GB",
+        number: "123456789",
+        type: "PASSPORT",
+        dateOfIssue: new Date("2020-01-01"),
+        frontFile: Buffer.from("Front"),
+      })
+      .addSection("residentialAddress", {
+        street: "Main St",
+        city: "London",
+        country: "GB",
+        proofCategory: "UTILITY_BILL",
+        proofFile: Buffer.from("Proof"),
+      });
+
+    const serialized = credential.serializeSubject();
+
+    expect(serialized.id).toBe("uuid:abc");
+    expect(serialized.firstName).toBe("Ada");
+    expect(serialized.dateOfBirth).toBe(new Date("1815-12-10").toISOString());
+    expect(base85ToFile(serialized.selfieFile as string)?.toString()).toBe("Selfie");
+    expect(serialized.idDocumentCountry).toBe("GB");
+    expect(serialized.idDocumentDateOfIssue).toBe(new Date("2020-01-01").toISOString());
+    expect(base85ToFile(serialized.idDocumentFrontFile as string)?.toString()).toBe("Front");
+    expect(serialized.residentialAddressCity).toBe("London");
+    expect(base85ToFile(serialized.residentialAddressProofFile as string)?.toString()).toBe(
+      "Proof",
+    );
+
+    expect("middleName" in serialized).toBe(false);
+    expect("idDocumentBackFile" in serialized).toBe(false);
+  });
+
+  it("round-trips through deserialize", async () => {
+    const roundTrip = new KycV2();
+
+    await roundTrip.deserialize(
+      serializedCredential({
+        id: "uuid:abc",
+        firstName: "Ada",
+        dateOfBirth: new Date("1815-12-10").toISOString(),
+        selfieFile: fileToBase85(Buffer.from("Selfie")),
+        idDocumentType: "PASSPORT",
+        residentialAddressCity: "London",
+      }),
+    );
+
+    expect(roundTrip.subject.id).toBe("uuid:abc");
+    expect(roundTrip.subject.dateOfBirth).toEqual(new Date("1815-12-10"));
+    expect(roundTrip.subject.selfieFile?.toString()).toBe("Selfie");
+    expect(roundTrip.subject.idDocument?.type).toBe("PASSPORT");
+    expect(roundTrip.subject.residentialAddress?.city).toBe("London");
+    expect(roundTrip.envelope.approvedAt).toEqual(new Date("2022-01-01"));
+  });
+
+  it("rejects fields the subject does not declare", async () => {
+    expect(() => new KycV2().setSubject({ id: "x", bogus: 1 } as never)).toThrow(
+      "Unexpected subject fields: bogus",
+    );
+
+    expect(() => new KycV2().addSection("idDocument", { bogus: 1 } as never)).toThrow(
+      "Unexpected idDocument fields: bogus",
+    );
+
+    await expect(
+      new KycV2().deserialize(serializedCredential({ id: "uuid:abc", bogus: 1 })),
+    ).rejects.toThrow("Unexpected subject fields: bogus");
+  });
+
+  it("carries the v2 envelope fields v1 lacks", () => {
+    const envelope = new KycV2()
+      .setEnvelope({
+        id: "https://issuer.example/credentials/123",
+        kycLevel: 2,
+        issued: new Date("2022-01-01"),
+        expirationDate: new Date("2030-01-01"),
+      })
+      .setSubject({ id: "uuid:abc" })
+      .serializeEnvelope();
+
+    expect(envelope.kycLevel).toBe(2);
+    expect(envelope.issued).toBe(new Date("2022-01-01").toISOString());
+    expect(envelope.expirationDate).toBe(new Date("2030-01-01").toISOString());
+  });
+
+  it("rejects the fields only v1 declares", () => {
+    expect(() => new KycV2().setSubject({ id: "x", applicantId: "a" } as never)).toThrow(
+      "Unexpected subject fields: applicantId",
+    );
+  });
+});

package/src/schemas/KycV2/index.ts

@@ -0,0 +1,45 @@
+import type { PublicNotes } from "../types";
+
+import { CONTEXT_IDOS_CREDENTIAL_V2, CONTEXT_IDOS_CREDENTIAL_V2_SUBJECT } from "../../utils/loader";
+import { EnvelopeV2 } from "../Envelope";
+import { VerifiableCredentialBase } from "../VerifiableCredential";
+import { Subject } from "./Subject";
+
+/*
+ * v2 derives its level the same way as v1; what changed is the subject context and the
+ * envelope, which gained `kycLevel` and the issuance dates — declared in v2's own,
+ * separately protected envelope context.
+ */
+export class KycV2 extends VerifiableCredentialBase<EnvelopeV2, Subject> {
+  static readonly envelopeContext: string = CONTEXT_IDOS_CREDENTIAL_V2;
+  static readonly subjectContext: string = CONTEXT_IDOS_CREDENTIAL_V2_SUBJECT;
+
+  constructor() {
+    super(EnvelopeV2, Subject);
+  }
+
+  override level(): string {
+    const { residentialAddress, selfieFile, email, phoneNumber } = this.subject;
+
+    // A complete address proof is the sign of plus.
+    const base =
+      residentialAddress?.proofFile &&
+      residentialAddress.city &&
+      residentialAddress.proofCategory &&
+      residentialAddress.country
+        ? "plus"
+        : "basic";
+
+    const addons = [
+      selfieFile && "liveness",
+      email && "email",
+      phoneNumber && "phoneNumber",
+    ].filter(Boolean);
+
+    return [base, ...addons].join("+");
+  }
+
+  override publicNotes(): PublicNotes {
+    return { type: "kyc", level: this.level() };
+  }
+}