@idos-network/credentials 1.2.0 → 2.2.0

package/src/schemas/KycV3/index.ts

@@ -0,0 +1,108 @@
+import type { PublicNotes } from "../types";
+
+import { CONTEXT_IDOS_CREDENTIAL_V2, CONTEXT_IDOS_CREDENTIAL_V3_SUBJECT } from "../../utils/loader";
+import { EnvelopeV2 } from "../Envelope";
+import { VerifiableCredentialBase } from "../VerifiableCredential";
+import { Subject } from "./Subject";
+
+export class KycV3 extends VerifiableCredentialBase<EnvelopeV2, Subject> {
+  static readonly envelopeContext: string = CONTEXT_IDOS_CREDENTIAL_V2;
+  static readonly subjectContext: string = CONTEXT_IDOS_CREDENTIAL_V3_SUBJECT;
+
+  constructor() {
+    super(EnvelopeV2, Subject);
+  }
+
+  override level(): string {
+    const {
+      residentialAddress,
+      biometric,
+      contact,
+      edd,
+      sourceOfWealth,
+      screening,
+      onboarding,
+      person,
+      idDocument,
+    } = this.subject;
+
+    // A verified address with a proof is the sign of plus.
+    let base = "unverified";
+
+    // When we have a idDocument and person, we can set "basic"
+    if (person && idDocument) {
+      base = "basic";
+    }
+
+    // When we also have a verified address, we can set "plus"
+    if (
+      base === "basic" &&
+      residentialAddress?.proofFile &&
+      residentialAddress.city &&
+      residentialAddress.proofCategory &&
+      residentialAddress.source === "PROOF_OF_ADDRESS" &&
+      residentialAddress.country
+    ) {
+      base = "plus";
+    }
+
+    const addons = [
+      biometric?.selfieFile && "liveness",
+      contact?.email && "email",
+      contact?.phoneNumber && "phoneNumber",
+      edd && "edd",
+      sourceOfWealth && "sow",
+      screening && "screening",
+      onboarding && "onboarding",
+    ].filter(Boolean);
+
+    return [base, ...addons].join("+");
+  }
+
+  kycLevel(): number {
+    const { person, idDocument, biometric, residentialAddress, sourceOfWealth, onboarding } =
+      this.subject;
+
+    let kycLevel = 0;
+
+    // basic+liveness are always at least kycLevel = 1
+    if (biometric?.selfieFile && person && idDocument) {
+      kycLevel = 1;
+    }
+
+    // plus+liveness are always at least kycLevel = 2
+    if (
+      kycLevel >= 1 &&
+      residentialAddress?.proofFile &&
+      residentialAddress.source === "PROOF_OF_ADDRESS"
+    ) {
+      kycLevel = 2;
+    }
+
+    // full SOW and onboarding questionnaire are always at least kycLevel = 3
+    if (kycLevel >= 2 && sourceOfWealth && onboarding) {
+      kycLevel = 3;
+    }
+
+    return kycLevel;
+  }
+
+  override publicNotes(): PublicNotes {
+    return {
+      type: "kyc",
+      level: this.level(),
+      kycLevel: this.kycLevel(),
+    };
+  }
+
+  protected override setMissingFields(): void {
+    super.setMissingFields();
+
+    // A kycLevel of 0 means "none reached", which the envelope expresses by omission.
+    if (this.envelope.kycLevel === undefined && this.kycLevel() > 0) {
+      this.envelope.kycLevel = this.kycLevel();
+    }
+
+    this.envelope.expirationDate ??= this.subject.idDocument?.dateOfExpiry;
+  }
+}

package/src/schemas/VerifiableCredential.ts

@@ -0,0 +1,232 @@
+import { Ed25519Signature2020 } from "@digitalbazaar/ed25519-signature-2020";
+import * as vc from "@digitalbazaar/vc";
+
+import type { AvailableIssuerType, VerifiableCredential } from "../types";
+import type { PublicNotes } from "./types";
+
+import { assertNoExtraFields } from "../utils";
+import { issuerToKey } from "../utils/issuer";
+import {
+  CONTEXT_ED25519_SIGNATURE_2020_V1,
+  CONTEXT_V1,
+  defaultDocumentLoader,
+} from "../utils/loader";
+import {
+  assertValid,
+  fieldsOf,
+  flatFieldsOf,
+  fromFlat,
+  sectionsOf,
+  toClass,
+  toFlat,
+} from "./utils";
+
+type Ctor<T> = new () => T;
+
+/** The sections of a subject class, with their optionality dropped. */
+export type Sections<TSubject> = {
+  [K in keyof TSubject]-?: NonNullable<TSubject[K]>;
+};
+
+/**
+ * The fields of a class that are not sections: a subject's `id`, an envelope's own fields.
+ * Sections are the properties holding another class; everything a credential carries as a
+ * value is one of the types below.
+ */
+export type OwnFields<T> = Partial<
+  Pick<
+    T,
+    {
+      [K in keyof T]-?: NonNullable<T[K]> extends string | number | boolean | Date | Buffer
+        ? K
+        : never;
+    }[keyof T]
+  >
+>;
+
+/**
+ * A credential under construction: an envelope and a subject built up section by section,
+ * validated as a whole, then flattened for issuance.
+ *
+ * Both halves stay partial until `checkValidity()` runs — proving them complete is the
+ * point of that call.
+ */
+export abstract class VerifiableCredentialBase<TEnvelope extends object, TSubject extends object> {
+  /*
+   * The JSON-LD contexts, declared here and defined by each subclass. `declare static` stands in
+   * for the abstract static TypeScript lacks: a subclass that forgets one is not caught at compile
+   * time, but the instance methods below can read them.
+   */
+  declare static readonly envelopeContext: string;
+  declare static readonly subjectContext: string;
+
+  readonly envelope: Partial<TEnvelope> = {};
+  readonly subject: Partial<TSubject> = {};
+
+  protected constructor(
+    private readonly envelopeClass: Ctor<TEnvelope>,
+    private readonly subjectClass: Ctor<TSubject>,
+  ) {}
+
+  /**
+   * Adds one section of the subject. Fields the section does not declare are rejected: they
+   * would silently vanish on serialization, and a caller who misspells one deserves to hear
+   * about it rather than issue a credential missing the field.
+   *
+   * Pass `validate: false` to defer value checks to `checkValidity()`; the extra-field check
+   * always runs.
+   */
+  addSection<K extends keyof TSubject>(
+    section: K,
+    fields: Sections<TSubject>[K],
+    validate = true,
+  ): this {
+    const meta = sectionsOf(this.subjectClass).find(({ property }) => property === section);
+
+    if (!meta) throw new Error(`Unknown section: ${String(section)}`);
+
+    const cls = meta.type();
+    const known = new Set(fieldsOf(cls));
+    const extra = Object.keys(fields).filter((field) => !known.has(field));
+
+    if (extra.length > 0) {
+      throw new Error(`Unexpected ${String(section)} fields: ${extra.join(", ")}`);
+    }
+
+    /*
+     * Assigned onto a real instance rather than a bare object, so `validateSync` finds the
+     * class's metadata and `instanceToPlain` applies its transforms.
+     */
+    const instance = Object.assign(new cls(), fields);
+
+    if (validate) assertValid(String(section), instance);
+
+    this.subject[section] = instance as TSubject[K];
+
+    return this;
+  }
+
+  /**
+   * Sets the subject's own fields — the ones that are not a section, such as `id`. Unknown
+   * fields are rejected for the same reason `addSection` rejects them.
+   *
+   * Values are checked by `checkValidity()`, since a field left out here may still be filled
+   * in by `setMissingFields()` later.
+   */
+  setSubject(fields: OwnFields<TSubject>): this {
+    Object.assign(this.subject, this.ownFields("subject", this.subjectClass, fields));
+
+    return this;
+  }
+
+  /** `setSubject`, for the envelope: `id`, `issued`, `approvedAt`, `expirationDate`. */
+  setEnvelope(fields: OwnFields<TEnvelope>): this {
+    Object.assign(this.envelope, this.ownFields("envelope", this.envelopeClass, fields));
+
+    return this;
+  }
+
+  /**
+   * Fills in the fields this credential derives from its own contents, then validates both
+   * halves. Throws `CredentialValidationError` if either is incomplete or invalid.
+   */
+  checkValidity(): void {
+    this.setMissingFields();
+
+    assertValid("envelope", Object.assign(new this.envelopeClass(), this.envelope));
+    assertValid("subject", Object.assign(new this.subjectClass(), this.subject));
+  }
+
+  /** The flat credential subject, with its `@context`. */
+  serializeSubject(): Record<string, unknown> {
+    this.checkValidity();
+
+    return {
+      "@context": [this.contexts.subjectContext],
+      ...toFlat(Object.assign(new this.subjectClass(), this.subject)),
+    };
+  }
+
+  /** The flat envelope fields. */
+  serializeEnvelope(): Record<string, unknown> {
+    this.checkValidity();
+
+    return toFlat(Object.assign(new this.envelopeClass(), this.envelope));
+  }
+
+  /** Signs the credential with `issuer`, producing a verifiable credential. */
+  async issue(issuer: AvailableIssuerType): Promise<VerifiableCredential<unknown>> {
+    const key = await issuerToKey(issuer);
+
+    const credential = {
+      "@context": [CONTEXT_V1, this.contexts.envelopeContext, CONTEXT_ED25519_SIGNATURE_2020_V1],
+      type: ["VerifiableCredential"],
+      issuer: key.controller,
+      ...this.serializeEnvelope(),
+      credentialSubject: this.serializeSubject(),
+    };
+
+    return vc.issue({
+      credential,
+      suite: new Ed25519Signature2020({ key }),
+      documentLoader: defaultDocumentLoader,
+    });
+  }
+
+  /**
+   * Rebuilds envelope and subject from a serialized credential.
+   *
+   * A subject key the class does not declare is an error: the subject context defines the
+   * subject exhaustively, so an unknown key means the credential does not match the
+   * `@context` it claims, and reading it anyway would silently discard what it carried.
+   *
+   * The envelope is the lenient half — a credential carries W3C fields of its own there
+   * (`proof`, `issuanceDate`, `type`, `issuer`), which are dropped rather than rejected.
+   *
+   * SECURITY: this does not verify the signature. See `verifyCredential()`.
+   */
+  async deserialize(credential: VerifiableCredential<unknown>): Promise<void> {
+    const { credentialSubject, ...envelope } = credential;
+
+    // The subject's `@context` is the credential's own, not one of its fields.
+    const { "@context": _context, ...subject } = credentialSubject as Record<string, unknown>;
+
+    assertNoExtraFields("subject", flatFieldsOf(this.subjectClass), subject);
+
+    Object.assign(this.envelope, fromFlat(this.envelopeClass, envelope as Record<string, unknown>));
+
+    Object.assign(
+      this.subject,
+      fromFlat(this.subjectClass, credentialSubject as Record<string, unknown>),
+    );
+  }
+
+  /** The credential's level, derived from its contents. */
+  abstract level(): string;
+
+  /** The credential's public notes, stored unencrypted alongside it. */
+  abstract publicNotes(): PublicNotes;
+
+  /**
+   * The class's own fields, transformed onto an instance. Fields the class does not declare, or
+   * declares as a section rather than a value, are rejected as they are by `add`.
+   */
+  private ownFields<T extends object>(label: string, cls: Ctor<T>, fields: object): Partial<T> {
+    const sections = new Set(sectionsOf(cls).map(({ property }) => property));
+    const own = fieldsOf(cls).filter((field) => !sections.has(field));
+
+    assertNoExtraFields(label, new Set(own), fields);
+
+    return toClass(cls, fields);
+  }
+
+  /** The subclass's static contexts, reached through the instance. */
+  private get contexts(): typeof VerifiableCredentialBase {
+    return this.constructor as typeof VerifiableCredentialBase;
+  }
+
+  /** Fills in derived envelope fields left unset by the caller. */
+  protected setMissingFields(): void {
+    (this.envelope as { level?: string }).level ??= this.level();
+  }
+}

package/src/schemas/enums.ts

@@ -0,0 +1,126 @@
+/*
+ * Enum values as `as const` arrays: `@IsIn(...)` validates against the array and the union
+ * type is derived from it, so each set of values is written once.
+ */
+
+export const IntendedUses = [
+  "INVESTING",
+  "PAYMENT_TO_FRIENDS_FAMILY_OR_OTHERS",
+  "PURCHASE_DIGITAL_ASSETS",
+  "ONLINE_PURCHASES_OF_GOODS_OR_SERVICES",
+  "TRADING",
+] as const;
+export type IntendedUse = (typeof IntendedUses)[number];
+
+export const IDDocumentTypes = [
+  "PASSPORT",
+  "DRIVERS",
+  "ID_CARD",
+  "VOTING_CARD",
+  "PAN_CARD",
+  "INTERNAL_PASSPORT",
+  "RESIDENCE_PERMIT",
+] as const;
+export type IDDocumentType = (typeof IDDocumentTypes)[number];
+
+export const ResidentialAddressSources = [
+  "MANUAL",
+  "GPS",
+  "EXTERNAL_DB",
+  "PROOF_OF_ADDRESS",
+  "PROOF_OF_IDENTITY",
+  "AUTO_COMPLETE",
+] as const;
+export type ResidentialAddressSource = (typeof ResidentialAddressSources)[number];
+
+export const ScreeningResults = ["CLEAR", "NOT_CHECKED"] as const;
+export type ScreeningResult = (typeof ScreeningResults)[number];
+
+export const Genders = ["M", "F", "OTHER"] as const;
+export type Gender = (typeof Genders)[number];
+
+export const EmploymentStatuses = [
+  "EMPLOYED",
+  "SELF_EMPLOYED",
+  "UNEMPLOYED",
+  "RETIRED",
+  "STUDENT",
+] as const;
+export type EmploymentStatus = (typeof EmploymentStatuses)[number];
+
+export const ExpectedMonthlyTransactionCounts = [
+  "LESS_THAN_5",
+  "BETWEEN_5_AND_10",
+  "MORE_THAN_10",
+] as const;
+export type ExpectedMonthlyTransactionCount = (typeof ExpectedMonthlyTransactionCounts)[number];
+
+export const ExpectedMonthlyTransactionVolumes = [
+  "LESS_THAN_500",
+  "MORE_THAN_500_LESS_THAN_2000",
+  "MORE_THAN_2000",
+] as const;
+export type ExpectedMonthlyTransactionVolume = (typeof ExpectedMonthlyTransactionVolumes)[number];
+
+export const SourceOfWealthTypes = [
+  "SALARY",
+  "SAVINGS",
+  "INVESTMENTS",
+  "CRYPTO_TRADING",
+  "OTHER",
+] as const;
+export type SourceOfWealthType = (typeof SourceOfWealthTypes)[number];
+
+export const YearlyGrossIncomes = [
+  "LESS_THAN_20000",
+  "FROM_20001_TO_30000",
+  "FROM_30001_TO_40000",
+  "FROM_40001_TO_50000",
+  "FROM_50001_TO_60000",
+  "FROM_60001_TO_70000",
+  "FROM_70001_TO_80000",
+  "FROM_80001_TO_90000",
+  "FROM_90001_TO_100000",
+  "FROM_100001_TO_110000",
+  "FROM_110001_TO_120000",
+  "FROM_120001_TO_130000",
+  "FROM_130001_TO_140000",
+  "FROM_140001_TO_150000",
+  "FROM_150001_TO_200000",
+  "FROM_200001_TO_500000",
+  "MORE_THAN_500000",
+] as const;
+export type YearlyGrossIncome = (typeof YearlyGrossIncomes)[number];
+
+export const ApproximateNetWorths = [
+  "UP_TO_25000",
+  "BETWEEN_25001_AND_50000",
+  "BETWEEN_50001_AND_100000",
+  "BETWEEN_100001_AND_300000",
+  "BETWEEN_300001_AND_500000",
+  "BETWEEN_500001_AND_1000000",
+  "OVER_1000001",
+] as const;
+export type ApproximateNetWorth = (typeof ApproximateNetWorths)[number];
+
+export const Occupations = [
+  "AGRICULTURE",
+  "ARTS_AND_ENTERTAINMENT",
+  "CONSTRUCTION",
+  "EDUCATION",
+  "FINANCIAL_SERVICES",
+  "INFORMATION_AND_TECHNOLOGY",
+  "RETAIL",
+  "REAL_ESTATE",
+  "OTHER",
+  "BUSINESS_OWNER",
+  "HEALTHCARE",
+  "INDUSTRIAL",
+  "LEGAL_SERVICES",
+  "PUBLIC_SECTOR",
+  "SENIOR_MANAGEMENT",
+] as const;
+export type Occupation = (typeof Occupations)[number];
+
+export const Currencies = ["EUR", "USD", "GBP", "OTHER"] as const;
+export type Currency = (typeof Currencies)[number];

package/src/schemas/index.ts

@@ -0,0 +1,14 @@
+export * from "./enums";
+
+export type { Sections, OwnFields } from "./VerifiableCredential";
+export { VerifiableCredentialBase } from "./VerifiableCredential";
+export type { PublicNotes } from "./types";
+
+export { EnvelopeV1, EnvelopeV2 } from "./Envelope";
+export { EddV1 as VerifiableCredentialEddV1 } from "./EddV1";
+export { FaceIdV1 as VerifiableCredentialFaceIdV1 } from "./FaceIdV1";
+export { KycV1 as VerifiableCredentialKycV1 } from "./KycV1";
+export { KycV2 as VerifiableCredentialKycV2 } from "./KycV2";
+
+export { KycV3 as VerifiableCredentialKycV3 } from "./KycV3";
+export { Subject as VerifiableCredentialKycV3Subject } from "./KycV3/Subject";