@idos-network/credentials 1.2.0 → 2.2.0

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() };
+  }
+}

package/src/schemas/KycV3/Biometric.ts

@@ -0,0 +1,14 @@
+import { IsNumber, IsOptional } from "class-validator";
+
+import { Base85FileField } from "../utils";
+
+export class Biometric {
+  /* The person's selfie image. */
+  @Base85FileField()
+  selfieFile: Buffer;
+
+  /* A score indicating whether the selfie/liveness photo matches the document photo. */
+  @IsOptional()
+  @IsNumber()
+  selfieMatch?: number;
+}

package/src/schemas/KycV3/Contact.ts

@@ -0,0 +1,13 @@
+import { IsEmail, IsOptional, IsString } from "class-validator";
+
+export class Contact {
+  /* The person's email address. */
+  @IsOptional()
+  @IsEmail()
+  email?: string;
+
+  /* The person's phone number. */
+  @IsOptional()
+  @IsString()
+  phoneNumber?: string;
+}

package/src/schemas/KycV3/EDD.ts

@@ -0,0 +1,32 @@
+import { IsIn, IsMimeType, IsOptional, IsString } from "class-validator";
+
+import { Occupations, type Occupation } from "../enums";
+import { Base85FileField, RequiredWhen } from "../utils";
+
+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;
+
+  /* Type of the document provided as proof of the person's source of funds. */
+  @RequiredWhen((edd: EDD) => !!edd.sourceOfFundsProofFile)
+  @IsString()
+  @IsMimeType()
+  sourceOfFundsProofFileType?: string;
+
+  /* Name of the document provided as proof of the person's source of funds. */
+  @RequiredWhen((edd: EDD) => !!edd.sourceOfFundsProofFile)
+  @IsString()
+  sourceOfFundsProofFileName?: string;
+}

package/src/schemas/KycV3/IdDocument.ts

@@ -0,0 +1,92 @@
+import { IsIn, IsOptional, IsISO31661Alpha2, Length, IsString, IsMimeType } from "class-validator";
+
+import { IDDocumentTypes, type IDDocumentType } from "../enums";
+import { Base85FileField, IsoDateField, RequiredWhen } from "../utils";
+
+export class IdDocument {
+  /* The type of identity document used for verification (e.g. PASSPORT, ID_CARD, DRIVERS). */
+  @IsIn(IDDocumentTypes)
+  type: IDDocumentType;
+
+  /* The unique number on the identity document (e.g. passport number, ID card number). */
+  @Length(1, 255)
+  number: string;
+
+  /* The country of issuance of the identity document. */
+  @IsISO31661Alpha2()
+  country: string;
+
+  /* The date the identity document expires or ceases to be valid. */
+  @IsOptional()
+  @IsoDateField()
+  dateOfExpiry?: Date;
+
+  /* The date the identity document was issued. */
+  @IsOptional()
+  @IsoDateField()
+  dateOfIssue?: Date;
+
+  /* The authority that issued the document (e.g. DVLA, Bundesdruckerei). */
+  @IsOptional()
+  @Length(1, 255)
+  issuingAuthority?: string;
+
+  /* The file containing the front of the identity document. */
+  @Base85FileField()
+  frontFile: Buffer;
+
+  /* Type of the document provided as front of the identity document. */
+  @IsString()
+  @IsMimeType()
+  frontFileType: string;
+
+  /* Name of the document provided as front of the identity document. */
+  @IsString()
+  frontFileName: string;
+
+  /* The file containing the back of the identity document. */
+  @IsOptional()
+  @Base85FileField()
+  backFile?: Buffer;
+
+  /* Type of the document provided as back of the identity document. */
+  @RequiredWhen((idDocument: IdDocument) => !!idDocument.backFile)
+  @IsString()
+  @IsMimeType()
+  backFileType?: string;
+
+  /* Name of the document provided as back of the identity document. */
+  @RequiredWhen((idDocument: IdDocument) => !!idDocument.backFile)
+  @IsString()
+  backFileName?: string;
+
+  /* The Machine-Readable Zone (MRZ) line from the document. Includes mrzLine2 and mrzLine3. */
+  @IsOptional()
+  @Length(1, 255)
+  mrzLine1?: string;
+
+  /* A title or honorific on the identity document (e.g. Dr, Mr, Ms, Prof). */
+  @IsOptional()
+  @Length(1, 255)
+  title?: string;
+
+  /* An extended expiry date when the document's validity has been officially extended. */
+  @IsOptional()
+  @IsoDateField()
+  extendedValidUntil?: Date;
+
+  /* A secondary personal identification number on the document (e.g. DNI in Spain, CRP in Brazil). */
+  @IsOptional()
+  @Length(1, 255)
+  additionalNumber?: string;
+
+  /* The person's ethnicity as indicated on the document — only present on some national documents. */
+  @IsOptional()
+  @Length(1, 255)
+  ethnicity?: string;
+
+  /* The state or province that issued the document (e.g. US state driver's licenses). */
+  @IsOptional()
+  @Length(1, 255)
+  issuingSubdivision?: string;
+}

package/src/schemas/KycV3/Onboarding.ts

@@ -0,0 +1,36 @@
+import { IsIn } from "class-validator";
+
+import {
+  Currencies,
+  EmploymentStatuses,
+  ExpectedMonthlyTransactionCounts,
+  ExpectedMonthlyTransactionVolumes,
+  IntendedUses,
+  type Currency,
+  type EmploymentStatus,
+  type ExpectedMonthlyTransactionCount,
+  type ExpectedMonthlyTransactionVolume,
+  type IntendedUse,
+} from "../enums";
+
+export class Onboarding {
+  /* Intended use of the credentials. */
+  @IsIn(IntendedUses)
+  intendedUse: IntendedUse;
+
+  /* The person's employment status (e.g. EMPLOYED, RETIRED). */
+  @IsIn(EmploymentStatuses)
+  employmentStatus: EmploymentStatus;
+
+  /* The person's expected monthly transaction count, as a band. */
+  @IsIn(ExpectedMonthlyTransactionCounts)
+  expectedMonthlyTransactionCount: ExpectedMonthlyTransactionCount;
+
+  /* The person's expected monthly transaction volume, as a band. */
+  @IsIn(ExpectedMonthlyTransactionVolumes)
+  expectedMonthlyTransactionVolume: ExpectedMonthlyTransactionVolume;
+
+  /* The currency of the person's expected monthly transaction volume. */
+  @IsIn(Currencies)
+  expectedMonthlyTransactionVolumeCurrency: Currency;
+}

package/src/schemas/KycV3/Person.ts

@@ -0,0 +1,105 @@
+import { IsBoolean, IsIn, IsOptional, IsString, IsISO31661Alpha2 } from "class-validator";
+
+import { Genders, type Gender } from "../enums";
+import { IsoDateField, RequiredWhen } from "../utils";
+
+export class Person {
+  /* The person's first/given name(s) as on their identity document. */
+  @RequiredWhen((person: Person) => !person.familyName)
+  @IsString()
+  firstName?: string;
+
+  /* The person's family/last name as on their identity document. */
+  @IsOptional()
+  @IsString()
+  familyName?: string;
+
+  /* The person's middle name(s). */
+  @IsOptional()
+  @IsString()
+  middleName?: string;
+
+  /* The person's father's name / patronymic — required in some jurisdictions (e.g. Greece). */
+  @IsOptional()
+  @IsString()
+  fatherName?: string;
+
+  /* The person's maiden name (family name before marriage). */
+  @IsOptional()
+  @IsString()
+  maidenName?: string;
+
+  /* The person's mother's birth name — required in some jurisdictions (e.g. Hungary). */
+  @IsOptional()
+  @IsString()
+  motherName?: string;
+
+  /* The person's gender (M, F, or OTHER). */
+  @IsOptional()
+  @IsIn(Genders)
+  gender?: Gender;
+
+  /* The person's nationality country code (ISO 3166-1 alpha-2). */
+  @RequiredWhen((person: Person) => !person.stateless && !person.secondNationality)
+  @IsISO31661Alpha2()
+  nationality?: string;
+
+  /* A second nationality held by the person, if applicable (ISO 3166-1 alpha-2). */
+  @IsOptional()
+  @IsISO31661Alpha2()
+  secondNationality?: string;
+
+  /* The person's date of birth. */
+  @IsoDateField()
+  dateOfBirth: Date;
+
+  /* The city/country where the person was born. */
+  @IsOptional()
+  @IsString()
+  placeOfBirth?: string;
+
+  /* The state, region or territory within a country where the person was born. */
+  @IsOptional()
+  @IsString()
+  regionOfBirth?: string;
+
+  /* Whether the person is stateless (holds no nationality). */
+  @IsOptional()
+  @IsBoolean()
+  stateless?: boolean;
+
+  /* Whether the person holds refugee status. */
+  @IsOptional()
+  @IsBoolean()
+  refugeeStatus?: boolean;
+
+  /* Whether the person holds subsidiary protection status (below refugee status). */
+  @IsOptional()
+  @IsBoolean()
+  subsidiaryProtectionStatus?: boolean;
+
+  /* A national identification number (e.g. DNI in Spain, PESEL in Poland) — distinct from the document number. */
+  @IsOptional()
+  @IsString()
+  nationalIdNumber?: string;
+
+  /* The person's Tax Identification Number (TIN/VAT number) as issued by a tax authority. */
+  @IsOptional()
+  @IsString()
+  taxIdNumber?: string;
+
+  /* The country that issued the person's Tax Identification Number. */
+  @IsOptional()
+  @IsISO31661Alpha2()
+  taxIdIssuingCountry?: string;
+
+  /* Country where the person is tax-resident. May differ from the TIN-issuing country. */
+  @IsOptional()
+  @IsISO31661Alpha2()
+  taxResidenceCountry?: string;
+
+  /* The person's Social Security Number (US). */
+  @IsOptional()
+  @IsString()
+  ssn?: string;
+}

package/src/schemas/KycV3/ResidentialAddress.ts

@@ -0,0 +1,73 @@
+import { IsOptional, IsString, IsISO31661Alpha2, IsMimeType, IsEnum } from "class-validator";
+
+import { ResidentialAddressSources, type ResidentialAddressSource } from "../enums";
+import { Base85FileField, IsoDateField, RequiredWhen } from "../utils";
+
+export class ResidentialAddress {
+  /* How the address was obtained: typed in, autocompleted, from GPS, an external database, or read from an identity or proof-of-address document. */
+  @IsEnum(ResidentialAddressSources)
+  source: ResidentialAddressSource;
+
+  /* Street address. */
+  @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). */
+  @IsString()
+  city: string;
+
+  /* Postal code. */
+  @IsOptional()
+  @IsString()
+  postalCode?: string;
+
+  /* Country (ISO 3166-1 alpha-2). */
+  @IsISO31661Alpha2()
+  country: string;
+
+  /* Type of document provided to verify the address (e.g. utility bill, bank statement). */
+  @RequiredWhen((address: ResidentialAddress) => address.source === "PROOF_OF_ADDRESS")
+  @IsString()
+  proofCategory?: string;
+
+  /* Date the address proof document was issued. */
+  @IsOptional()
+  @IsoDateField()
+  proofDateOfIssue?: Date;
+
+  /* The document provided as address proof. */
+  @RequiredWhen((address: ResidentialAddress) => address.source === "PROOF_OF_ADDRESS")
+  @Base85FileField()
+  proofFile?: Buffer;
+
+  /* Type of the document provided as address proof. */
+  @RequiredWhen((address: ResidentialAddress) => address.source === "PROOF_OF_ADDRESS")
+  @IsString()
+  @IsMimeType()
+  proofFileType?: string;
+
+  /* Name of the document provided as address proof. */
+  @RequiredWhen((address: ResidentialAddress) => address.source === "PROOF_OF_ADDRESS")
+  @IsString()
+  proofFileName?: string;
+
+  /* Country code derived from the IP address used when the applicant registered. */
+  @IsOptional()
+  @IsISO31661Alpha2()
+  ipCountry?: string;
+}

package/src/schemas/KycV3/Screening.ts

@@ -0,0 +1,27 @@
+import { IsIn, IsNumber, IsOptional, Max, Min } from "class-validator";
+
+import { ScreeningResults, type ScreeningResult } from "../enums";
+
+export class Screening {
+  /* Whether the person appears on any sanctions lists (e.g. CLEAR, NOT_CHECKED). */
+  @IsIn(ScreeningResults)
+  sanctionsCheckResult: ScreeningResult;
+
+  /* A confidence score (0–100) for the sanctions screening result. */
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Max(100)
+  sanctionsConfidenceScore?: number;
+
+  /* The result of the PEP (Politically Exposed Person) screening check. */
+  @IsIn(ScreeningResults)
+  pepCheckResult: ScreeningResult;
+
+  /* A confidence score (0–100) for the PEP screening result. */
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Max(100)
+  pepConfidenceScore?: number;
+}

package/src/schemas/KycV3/SourceOfWealth.ts

@@ -0,0 +1,44 @@
+import { IsIn, IsOptional } from "class-validator";
+
+import {
+  ApproximateNetWorths,
+  Currencies,
+  SourceOfWealthTypes,
+  YearlyGrossIncomes,
+  type ApproximateNetWorth,
+  type Currency,
+  type SourceOfWealthType,
+  type YearlyGrossIncome,
+} from "../enums";
+import { Base85FileField, RequiredWith } from "../utils";
+
+export class SourceOfWealth {
+  /* The category of wealth source declared by the person (e.g. SALARY, INVESTMENTS). */
+  @IsIn(SourceOfWealthTypes)
+  type: SourceOfWealthType;
+
+  /* The person's yearly gross income, as a band. */
+  @IsOptional()
+  @IsIn(YearlyGrossIncomes)
+  yearlyGrossIncome?: YearlyGrossIncome;
+
+  /* The currency of the person's yearly gross income. */
+  @RequiredWith("yearlyGrossIncome")
+  @IsIn(Currencies)
+  yearlyGrossIncomeCurrency?: Currency;
+
+  /* The person's approximate net worth, as a band. */
+  @IsOptional()
+  @IsIn(ApproximateNetWorths)
+  approximateNetWorth?: ApproximateNetWorth;
+
+  /* The currency of the person's approximate net worth. */
+  @RequiredWith("approximateNetWorth")
+  @IsIn(Currencies)
+  approximateNetWorthCurrency?: Currency;
+
+  /* A file containing proof of the person's source of wealth. */
+  @IsOptional()
+  @Base85FileField()
+  sourceOfWealthProofFile?: Buffer;
+}

package/src/schemas/KycV3/Subject.ts

@@ -0,0 +1,54 @@
+import { IsDefined, IsOptional, IsString } from "class-validator";
+
+import { Section } from "../utils";
+import { Biometric } from "./Biometric";
+import { Contact } from "./Contact";
+import { EDD } from "./EDD";
+import { IdDocument } from "./IdDocument";
+import { Onboarding } from "./Onboarding";
+import { Person } from "./Person";
+import { ResidentialAddress } from "./ResidentialAddress";
+import { Screening } from "./Screening";
+import { SourceOfWealth } from "./SourceOfWealth";
+
+/** The credential subject: the sections that get flattened onto the wire. */
+export class Subject {
+  @IsString()
+  id: string;
+
+  @Section(() => Person)
+  @IsDefined()
+  person: Person;
+
+  @Section(() => IdDocument)
+  @IsOptional()
+  idDocument?: IdDocument;
+
+  @Section(() => Contact)
+  @IsOptional()
+  contact?: Contact;
+
+  @Section(() => Biometric)
+  @IsOptional()
+  biometric?: Biometric;
+
+  @Section(() => ResidentialAddress)
+  @IsOptional()
+  residentialAddress?: ResidentialAddress;
+
+  @Section(() => Screening)
+  @IsOptional()
+  screening?: Screening;
+
+  @Section(() => EDD)
+  @IsOptional()
+  edd?: EDD;
+
+  @Section(() => SourceOfWealth)
+  @IsOptional()
+  sourceOfWealth?: SourceOfWealth;
+
+  @Section(() => Onboarding)
+  @IsOptional()
+  onboarding?: Onboarding;
+}