@idos-network/credentials 1.1.0

package/src/utils/utils.test.ts

@@ -0,0 +1,303 @@
+import { describe, expect, it } from "vitest";
+
+import type { CredentialSubject } from "../types";
+
+import {
+  deriveLevel,
+  highestMatchingCredential,
+  matchLevelOrHigher,
+  pickHighestMatchingLevel,
+  recordFilter,
+} from "./";
+
+const defaultCredential: CredentialSubject = {
+  id: "uuid:1234",
+  firstName: "John",
+  familyName: "Doe",
+  idDocumentType: "PASSPORT",
+  dateOfBirth: new Date("1990-01-01"),
+  idDocumentCountry: "US",
+  idDocumentNumber: "123456789",
+  idDocumentFrontFile: Buffer.from("ID Document Front"),
+  selfieFile: Buffer.alloc(0),
+};
+
+describe("recordFilter", () => {
+  [
+    [
+      { level: "basic+liveness", status: "approved", issuer: "issuer-a", type: "kyc" },
+      { level: ["basic+liveness", "plus+liveness"], status: ["approved"] },
+      {},
+      true,
+    ],
+    [
+      { level: "plus+liveness", status: "approved", issuer: "issuer-a", type: "kyc" },
+      { level: ["basic+liveness"], status: ["approved"] },
+      {},
+      false,
+    ],
+    [
+      { level: "basic+liveness", status: "approved", issuer: "issuer-a", type: "kyc" },
+      { level: ["basic+liveness"], status: ["approved"] },
+      { issuer: ["issuer-b", "issuer-a"] },
+      false,
+    ],
+    [
+      { level: "basic+liveness", status: "approved", issuer: "issuer-a", type: "kyc" },
+      { level: ["basic+liveness"], status: ["approved"] },
+      { issuer: ["issuer-b"] },
+      true,
+    ],
+    [{ level: "plus+liveness", status: "approved", issuer: "issuer-a", type: "kyc" }, {}, {}, true],
+    [
+      { credentialSubject: { nationality: "CZ" } },
+      { "credentialSubject.nationality": ["CZ", "DE"] },
+      {},
+      true,
+    ],
+    [
+      { credentialSubject: { nationality: "CZ" } },
+      {},
+      { "credentialSubject.nationality": ["CZ", "DE"] },
+      false,
+    ],
+  ].forEach(([publicNotes, pick, omit, expected]) => {
+    it(`publicNotes=${JSON.stringify(publicNotes)}, pick=${JSON.stringify(pick)}, omit=${JSON.stringify(omit)} => ${expected}`, () => {
+      const result = recordFilter(
+        publicNotes as Record<string, unknown>,
+        pick as Record<string, unknown[]>,
+        omit as Record<string, unknown[]>,
+      );
+
+      expect(result).toBe(expected);
+    });
+  });
+});
+
+describe("matchLevelOrHigher", () => {
+  [
+    ["basic", [], "basic+liveness", true],
+    ["plus", [], "plus+liveness", true],
+    ["plus", [], "basic", false],
+    ["plus", ["liveness"], "plus", false],
+    ["basic", ["email"], "basic+liveness+email+phoneNumber", true],
+    ["plus", ["email", "phoneNumber"], "plus+liveness+email+phoneNumber", true],
+    ["plus", ["email", "phoneNumber"], "plus+phoneNumber", false],
+  ].forEach(([level, requiredAddons, testLevel, expected]) => {
+    it(`level=${level} requiredAddons=[${(requiredAddons as string[]).join(",")}] testLevel=${testLevel} => ${expected}`, () => {
+      expect(
+        matchLevelOrHigher(
+          level as "basic" | "plus",
+          requiredAddons as ("liveness" | "email" | "phoneNumber")[],
+          testLevel as string,
+        ),
+      ).toBe(expected as boolean);
+    });
+  });
+});
+
+describe("pickHighestMatchingLevel", () => {
+  [
+    [
+      ["basic+liveness", "plus+liveness+email", "plus+liveness+email+phoneNumber"],
+      "plus",
+      ["email"],
+      "plus+liveness+email+phoneNumber",
+    ],
+    [
+      ["basic+liveness", "plus+liveness+email", "plus+liveness+email+phoneNumber"],
+      "plus",
+      ["email", "phoneNumber"],
+      "plus+liveness+email+phoneNumber",
+    ],
+    [
+      ["basic+liveness", "plus+liveness+email", "plus+liveness+email"],
+      "plus",
+      ["email", "phoneNumber"],
+      null,
+    ],
+    [["basic+liveness", "plus+liveness"], "basic", ["liveness"], "plus+liveness"],
+  ].forEach(([levels, requiredLevel, requiredAddons, expected]) => {
+    it(`levels=${levels} requiredLevel=${requiredLevel} requiredAddons=[${(requiredAddons as string[]).join(",")}] => ${expected}`, () => {
+      expect(
+        pickHighestMatchingLevel(
+          levels as string[],
+          requiredLevel as "basic" | "plus",
+          requiredAddons as ("liveness" | "email" | "phoneNumber")[],
+        ),
+      ).toBe(expected);
+    });
+  });
+});
+
+describe("highestMatchingCredential", () => {
+  it("choose basic, because plus did not match constraints", () => {
+    const credentials = [
+      {
+        public_notes: JSON.stringify({
+          level: "basic+liveness+email",
+          issuer: "custom-issuer",
+          status: "approved",
+        }),
+      },
+      {
+        public_notes: JSON.stringify({
+          level: "plus+liveness",
+          issuer: "custom-issuer",
+          status: "pending",
+        }),
+      },
+    ];
+
+    const matchedCredentials = highestMatchingCredential(credentials, "basic", {
+      addons: ["email"],
+      publicNotesConstraint: { status: "approved" },
+    });
+
+    expect(matchedCredentials).toEqual(credentials[0]);
+  });
+
+  it("choose plus+liveness+email+phoneNumber because it has better score", () => {
+    const credentials = [
+      {
+        public_notes: JSON.stringify({
+          level: "plus+liveness+email+phoneNumber",
+        }),
+      },
+      {
+        public_notes: JSON.stringify({
+          level: "plus+liveness+email",
+        }),
+      },
+    ];
+
+    const matchedCredentials = highestMatchingCredential(credentials, "basic", {
+      addons: ["email"],
+    });
+
+    expect(matchedCredentials).toEqual(credentials[0]);
+  });
+
+  it("choose plus+liveness because it has better score", () => {
+    const credentials = [
+      {
+        public_notes: JSON.stringify({
+          level: "basic+liveness+email+phoneNumber",
+        }),
+      },
+      {
+        public_notes: JSON.stringify({
+          level: "plus+liveness",
+        }),
+      },
+    ];
+
+    const matchedCredentials = highestMatchingCredential(credentials, "basic", {
+      addons: ["liveness"],
+    });
+
+    expect(matchedCredentials).toEqual(credentials[1]);
+  });
+
+  it("choose basic+liveness+email because plus has no email", () => {
+    const credentials = [
+      {
+        public_notes: JSON.stringify({
+          level: "plus+liveness",
+        }),
+      },
+      {
+        public_notes: JSON.stringify({
+          level: "basic+liveness+email",
+        }),
+      },
+    ];
+
+    const matchedCredentials = highestMatchingCredential(credentials, "basic", {
+      addons: ["email"],
+    });
+
+    expect(matchedCredentials).toEqual(credentials[1]);
+  });
+
+  it("choose nothing because it did not match the constraints", () => {
+    const credentials = [
+      {
+        public_notes: JSON.stringify({
+          level: "plus+liveness",
+          status: "pending",
+          type: "kyc",
+        }),
+      },
+      {
+        public_notes: JSON.stringify({
+          level: "basic+liveness+email",
+          status: "pending",
+          type: "kyc",
+        }),
+      },
+    ];
+
+    const matchedCredentials = highestMatchingCredential(credentials, "basic", {
+      addons: ["liveness"],
+      publicNotesConstraint: { status: "approved", type: "kyc" },
+    });
+
+    expect(matchedCredentials).toBeUndefined();
+  });
+});
+
+describe("deriveLevel", () => {
+  it("basic only", () => {
+    expect(
+      deriveLevel({
+        ...defaultCredential,
+        // @ts-expect-error - to test absence of selfieFile
+        selfieFile: undefined,
+      }),
+    ).toBe("basic");
+  });
+
+  it("basic+liveness", () => {
+    expect(
+      deriveLevel({
+        ...defaultCredential,
+      }),
+    ).toBe("basic+liveness");
+  });
+
+  it("plus+liveness", () => {
+    expect(
+      deriveLevel({
+        ...defaultCredential,
+        residentialAddress: {
+          street: "123 Main St",
+          city: "Anytown",
+          postalCode: "12345",
+          country: "US",
+          proofCategory: "UTILITY_BILL",
+          proofFile: Buffer.from("Utility Bill"),
+        },
+      }),
+    ).toBe("plus+liveness");
+  });
+
+  it("plus+liveness+phoneNumber", () => {
+    expect(
+      deriveLevel({
+        ...defaultCredential,
+        selfieFile: Buffer.from("Selfie"),
+        phoneNumber: "+1234567890",
+        email: "john.doe@example.com",
+        residentialAddress: {
+          street: "123 Main St",
+          city: "Anytown",
+          postalCode: "12345",
+          country: "US",
+          proofCategory: "UTILITY_BILL",
+          proofFile: Buffer.from("Utility Bill"),
+        },
+      }),
+    ).toBe("plus+liveness+email+phoneNumber");
+  });
+});

package/types/index.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="../dist/index.d.ts" />
+/// <reference path="./internals.d.ts" />
+export * from "../dist/index.js";
+export * from "./internal.js";

package/types/internals.d.ts

@@ -0,0 +1,124 @@
+// Those are the types for the digitalbazaar libraries.
+// There are missing a bunch of types, it's just what we need.
+declare module "@digitalbazaar/ed25519-signature-2020" {
+  export interface Ed25519Signature2020Options {
+    key: Ed25519VerificationKey2020;
+    verificationMethod?: string;
+  }
+
+  export declare class Ed25519Signature2020 {
+    constructor(options: Ed25519Signature2020Options);
+  }
+}
+
+declare module "@digitalbazaar/ed25519-verification-key-2020" {
+  export interface Ed25519VerificationKey2020Options {
+    id?: string;
+    controller: string;
+    publicKeyMultibase: string;
+    privateKeyMultibase?: string;
+    type: "Ed25519VerificationKey2020";
+  }
+
+  export interface Ed25519VerificationKey2020GenerateOptions {
+    id?: string;
+    controller?: string;
+  }
+
+  export declare class Ed25519VerificationKey2020 {
+    public static from(
+      options: Ed25519VerificationKey2020Options,
+    ): Promise<Ed25519VerificationKey2020>;
+    public static generate(
+      options: Ed25519VerificationKey2020GenerateOptions,
+    ): Promise<Ed25519VerificationKey2020>;
+    public controller: string;
+    public id: string;
+    public publicKeyMultibase: string;
+    public privateKeyMultibase?: string;
+  }
+}
+
+declare module "@digitalbazaar/vc" {
+  export interface IssueOptions {
+    credential: object;
+    suite: Ed25519Signature2020;
+    documentLoader: JsonLDDocumentLoaderInstance;
+  }
+
+  export interface VerifiedCredentialsProof {
+    type: string;
+    created: string;
+    verificationMethod: string;
+    proofValue: string;
+    proofPurpose: string;
+  }
+
+  export interface VerifiedCredentials<K> {
+    "@context": string[];
+    type: string[];
+    issuer: string;
+    id: string;
+    level: string;
+    issued: string;
+    approvedAt: string;
+    expirationDate: string;
+    credentialSubject: K;
+    issuanceDate: string;
+    proof: VerifiedCredentialsProof;
+  }
+
+  // oxlint-disable-next-line typescript/no-explicit-any -- I don't know the right type
+  export declare function issue<K = any>(options: IssueOptions): Promise<VerifiedCredentials<K>>;
+
+  export interface VerifyCredentialOptions<K> {
+    credential: VerifiedCredentials<K>;
+    suite: Ed25519Signature2020;
+    controller: object;
+    documentLoader: JsonLDDocumentLoaderInstance;
+  }
+
+  export interface VerifyCredentialError {
+    name: string;
+    message: string;
+    stack: string;
+  }
+
+  export interface VerifyCredentialResult {
+    verified: boolean;
+    error?: {
+      name: string;
+      errors: VerifyCredentialError[];
+    };
+    results: {
+      proof: VerifiedCredentialsProof;
+    }[];
+    purposeResult: {
+      valid: boolean;
+    };
+  }
+
+  export declare function verifyCredential<K>(
+    options: VerifyCredentialOptions<K>,
+  ): Promise<VerifyCredentialResult>;
+}
+
+declare module "jsonld-document-loader" {
+  export interface JsonLdDocument {
+    contextUrl?: string | null;
+    // oxlint-disable-next-line typescript/no-explicit-any -- I don't know the right type
+    document: any;
+    documentUrl: string;
+    tag?: string;
+  }
+
+  export type JsonLDDocumentLoaderInstance = (url: string) => Promise<JsonLdDocument>;
+
+  export class JsonLdDocumentLoader {
+    constructor();
+
+    addStatic(url: string, document: object): void;
+
+    build(): JsonLDDocumentLoaderInstance;
+  }
+}