@idos-network/credentials 1.5.0 → 2.2.0

package/src/types/credentials.ts

@@ -1,255 +1,33 @@
-import * as z from "zod";
-
 export type idOSCredential = {
   id: string;
   user_id: string;
   public_notes: string;
-  content: string;
+  content_uri: string;
+  content_size: number;
   encryptor_public_key: string;
   issuer_auth_public_key: string;
   original_id?: string | null;
+  inserter_type?: string | null;
+  inserter_id?: string | null;
+};
+
+export type idOSCredentialRecord = Omit<idOSCredential, "content_uri" | "content_size"> & {
+  content: string | null;
+  content_uri?: string | null;
+  content_size?: number | null;
 };
 
-export type InsertableIDOSCredential = Omit<idOSCredential, "id" | "original_id"> & {
-  id?: idOSCredential["id"];
-  content_hash?: string;
+export type SignedCredentialContentReference = {
+  public_notes: string;
   public_notes_signature: string;
   broader_signature: string;
+  issuer_auth_public_key: string;
 };
 
-// https://github.com/colinhacks/zod/issues/3751
-export const CredentialFieldsSchema: z.ZodObject<{
-  id: z.ZodString;
-  level: z.ZodString;
-  issued: z.ZodOptional<z.ZodDate>;
-  approvedAt: z.ZodOptional<z.ZodDate>;
-  expirationDate: z.ZodOptional<z.ZodDate>;
-}> = z.object({
-  id: z.string(),
-
-  /* Level of KYC verification performed (e.g., basic, intermediate, advanced). */
-  level: z.string(),
-
-  /* @default Date.now() */
-  issued: z.date().optional(),
-
-  /* Date the credential was approved. */
-  approvedAt: z.date().optional(),
-
-  /* Date the credential was revoked. */
-  expirationDate: z.date().optional(),
-});
-
-export type CredentialFields = z.infer<typeof CredentialFieldsSchema>;
-
-// https://github.com/colinhacks/zod/issues/3751
-export const CredentialResidentialAddressSchema: z.ZodObject<{
-  street: z.ZodString;
-  houseNumber: z.ZodOptional<z.ZodString>;
-  additionalAddressInfo: z.ZodOptional<z.ZodString>;
-  region: z.ZodOptional<z.ZodString>;
-  city: z.ZodString;
-  postalCode: z.ZodOptional<z.ZodString>;
-  country: z.ZodString;
-  proofCategory: z.ZodString;
-  proofDateOfIssue: z.ZodOptional<z.ZodDate>;
-  proofFile: z.ZodType<Buffer<ArrayBufferLike>>;
-}> = z.object({
-  /* Street address. */
-  street: z.string(),
-
-  /* House number. */
-  houseNumber: z.string().optional(),
-
-  /* Additional address information (e.g., apartment number). */
-  additionalAddressInfo: z.string().optional(),
-
-  /* Region (e.g., state, province). */
-  region: z.string().optional(),
-
-  /* Locality (e.g., city, town). */
-  city: z.string(),
-
-  /* Postal code. */
-  postalCode: z.string().optional(),
-
-  /* Country (ISO 3166-1 alpha-2). */
-  country: z.string().min(2).max(2),
-
-  /* Residential Address Proof Category	Type of document provided to verify the address(e.g., utility bill, bank statement). */
-  proofCategory: z.string(),
-
-  /* Residential Address Proof Date Of Issue	Date the address proof document was issued. */
-  proofDateOfIssue: z.date().optional(),
-
-  /* Residential Address Proof File or URL of the document provided as address proof. */
-  proofFile: z.instanceof(Buffer),
-});
-
-export type CredentialResidentialAddress = z.infer<typeof CredentialResidentialAddressSchema>;
-
-export const IDDocumentTypeSchema: z.ZodEnum<{
-  PASSPORT: "PASSPORT";
-  DRIVERS: "DRIVERS";
-  ID_CARD: "ID_CARD";
-  VOTING_CARD: "VOTING_CARD";
-  PAN_CARD: "PAN_CARD";
-  INTERNAL_PASSPORT: "INTERNAL_PASSPORT";
-  RESIDENCE_PERMIT: "RESIDENCE_PERMIT";
-}> = z.enum([
-  "PASSPORT",
-  "DRIVERS",
-  "ID_CARD",
-  "VOTING_CARD",
-  "PAN_CARD",
-  "INTERNAL_PASSPORT",
-  "RESIDENCE_PERMIT",
-]);
-export type IDDocumentType = z.infer<typeof IDDocumentTypeSchema>;
-
-export const GenderSchema: z.ZodEnum<{
-  M: "M";
-  F: "F";
-  OTHER: "OTHER";
-}> = z.enum(["M", "F", "OTHER"]);
-export type Gender = z.infer<typeof GenderSchema>;
-
-// https://github.com/colinhacks/zod/issues/3751
-export const CredentialSubjectSchema: z.ZodObject<{
-  id: z.ZodString;
-  // Indonesian and Indian did not always have first name
-  firstName: z.ZodOptional<z.ZodString>;
-  middleName: z.ZodOptional<z.ZodString>;
-  ssn: z.ZodOptional<z.ZodString>;
-  gender: z.ZodOptional<typeof GenderSchema>;
-  nationality: z.ZodOptional<z.ZodString>;
-  // Indonesian and Indian did not always have family name
-  familyName: z.ZodOptional<z.ZodString>;
-  maidenName: z.ZodOptional<z.ZodString>;
-  email: z.ZodOptional<z.ZodEmail>;
-  phoneNumber: z.ZodOptional<z.ZodString>;
-  dateOfBirth: z.ZodDate;
-  placeOfBirth: z.ZodOptional<z.ZodString>;
-  idDocumentCountry: z.ZodString;
-  idDocumentNumber: z.ZodString;
-  idDocumentType: typeof IDDocumentTypeSchema;
-  idDocumentDateOfIssue: z.ZodOptional<z.ZodDate>;
-  idDocumentDateOfExpiry: z.ZodOptional<z.ZodDate>;
-  idDocumentFrontFile: z.ZodType<Buffer<ArrayBufferLike>>;
-  idDocumentBackFile: z.ZodOptional<z.ZodType<Buffer<ArrayBufferLike>>>;
-  selfieFile: z.ZodType<Buffer<ArrayBufferLike>>;
-  residentialAddress: z.ZodOptional<typeof CredentialResidentialAddressSchema>;
-}> = z
-  .object({
-    /* ID(unique credential)	Unique identifier for the credential itself. */
-    id: z.string(),
-
-    /* First name. */
-    firstName: z.string().optional(),
-
-    /* Middle name. */
-    middleName: z.string().optional(),
-
-    /* Social-security-number (without dashes) */
-    ssn: z.string().min(9).max(9).optional(),
-
-    /* Nationality (ISO 3166-1 alpha-2). */
-    nationality: z.string().min(2).max(2).optional(),
-
-    /* Gender (M or F, empty if not provided). */
-    gender: GenderSchema.optional(),
-
-    /* Family name. */
-    familyName: z.string().optional(),
-
-    /* Maiden name. */
-    maidenName: z.string().optional(),
-
-    /* Date of birth. */
-    dateOfBirth: z.date(),
-
-    /* Place of birth. */
-    placeOfBirth: z.string().optional(),
-
-    /* Email. */
-    email: z.email().optional(),
-
-    /* Phone number. */
-    phoneNumber: z.string().optional(),
-
-    /* Country that issued the identity document (ISO 3166-1 alpha-2). */
-    idDocumentCountry: z.string().min(2).max(2),
-
-    /* ID Document Number	Unique number on the identity document. */
-    idDocumentNumber: z.string(),
-
-    /* ID Document Type	Type of identity document(e.g., Passport, Driver's License, National ID). */
-    idDocumentType: IDDocumentTypeSchema,
-
-    /* ID Document Date of Issue	Date the identity document was issued. */
-    idDocumentDateOfIssue: z.date().optional(),
-
-    /* ID Document Date of Expiry	Expiration date of the identity document - if applicable. */
-    idDocumentDateOfExpiry: z.date().optional(),
-
-    /* ID Document Front File	Buffer with file representing the front of the identity document. */
-    idDocumentFrontFile: z.instanceof(Buffer),
-
-    /* ID Document Back File	Buffer with file representing the back of the identity document - if applicable. */
-    idDocumentBackFile: z.instanceof(Buffer).optional(),
-
-    /* (ID Document) Selfie File	Buffer with selfie with the identity document for verification purposes. */
-    selfieFile: z.instanceof(Buffer),
-
-    /* Residential Address Full residential address of the individual - if applicable. */
-    residentialAddress: CredentialResidentialAddressSchema.optional(),
-  })
-  .refine(
-    // At least one of firstName or familyName must be present,
-    (data) => data.firstName || data.familyName,
-    { message: "At least one of firstName or familyName must be provided" },
-  );
-
-export type CredentialSubject = z.infer<typeof CredentialSubjectSchema>;
-
-export interface VerifiableCredentialSubject extends Omit<
-  CredentialSubject,
-  | "residentialAddress"
-  | "idDocumentBackFile"
-  | "idDocumentFrontFile"
-  | "selfieFile"
-  | "idDocumentDateOfIssue"
-  | "idDocumentDateOfExpiry"
-  | "dateOfBirth"
-> {
-  "@context": string;
-  // Files are strings in verifiable credentials, but as an input they should be buffers
-  idDocumentFrontFile?: string;
-  idDocumentBackFile?: string;
-  selfieFile?: string;
-  // Dates are strings in verifiable credentials
-  dateOfBirth?: string;
-  idDocumentDateOfIssue?: string;
-  idDocumentDateOfExpiry?: string;
-  // This is the residential address flattened fields
-  residentialAddressStreet?: string;
-  residentialAddressHouseNumber?: string;
-  residentialAddressAdditionalAddressInfo?: string;
-  residentialAddressRegion?: string;
-  residentialAddressCity?: string;
-  residentialAddressPostalCode?: string;
-  residentialAddressCountry?: string;
-  residentialAddressProofCategory?: string;
-  // Dates are strings in verifiable credentials
-  residentialAddressProofDateOfIssue?: string;
-  // Files are strings in verifiable credentials, but as an input they should be buffers
-  residentialAddressProofFile?: string;
-}
-
 // TODO: This is a stub of the types for @digitalbazaar/vc
 // when they introduce TypeScript support we should remove this
 // The copy is here because `types.d.ts` file is not bundled.
-export interface VerifiedCredentialsProof {
+export interface VerifiableCredentialProof {
   type: string;
   created: string;
   verificationMethod: string;
@@ -257,26 +35,17 @@ export interface VerifiedCredentialsProof {
   proofPurpose: string;
 }
 
-export const CredentialSubjectFaceIdSchema: z.ZodObject<{
-  faceSignUserId: z.ZodString;
-}> = z.object({
-  faceSignUserId: z.string(),
-});
-
-export type CredentialSubjectFaceId = z.infer<typeof CredentialSubjectFaceIdSchema>;
-
-export interface VerifiedCredentials<K> {
+export interface VerifiableCredential<K> {
   "@context": string[];
   type: string[];
   issuer: string;
   id: string;
   level: string;
+  kycLevel?: number;
   issued: string;
   approvedAt: string;
-  expirationDate: string;
+  expirationDate?: string;
   credentialSubject: K;
   issuanceDate: string;
-  proof: VerifiedCredentialsProof;
+  proof: VerifiableCredentialProof;
 }
-
-export type VerifiableCredential<K> = VerifiedCredentials<K>;

package/src/utils/{utils.test.ts → index.test.ts}

@@ -1,26 +1,18 @@
+import { hexEncode, utf8Encode } from "@idos-network/utils/codecs";
+import nacl from "tweetnacl";
 import { describe, expect, it } from "vitest";
 
-import type { CredentialSubject } from "../types";
-
 import {
-  deriveLevel,
+  buildEphemeralSignedCredentialContentReference,
+  buildPreliminaryIDOSCredential,
+  buildSignedCredentialContentReference,
   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),
-};
+  type Addon,
+  type BaseLevel,
+} from ".";
 
 describe("recordFilter", () => {
   [
@@ -76,6 +68,9 @@ describe("recordFilter", () => {
 
 describe("matchLevelOrHigher", () => {
   [
+    ["unverified", [], "unverified", true],
+    ["unverified", [], "basic", true],
+    ["basic", [], "unverified", false],
     ["basic", [], "basic+liveness", true],
     ["plus", [], "plus+liveness", true],
     ["plus", [], "basic", false],
@@ -86,11 +81,7 @@ describe("matchLevelOrHigher", () => {
   ].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,
-        ),
+        matchLevelOrHigher(level as BaseLevel, requiredAddons as Addon[], testLevel as string),
       ).toBe(expected as boolean);
     });
   });
@@ -116,6 +107,12 @@ describe("pickHighestMatchingLevel", () => {
       ["email", "phoneNumber"],
       null,
     ],
+    [
+      ["unverified+phoneNumber", "basic+phoneNumber", "plus+phoneNumber"],
+      "unverified",
+      ["phoneNumber"],
+      "plus+phoneNumber",
+    ],
     [["basic+liveness", "plus+liveness"], "basic", ["liveness"], "plus+liveness"],
   ].forEach(([levels, requiredLevel, requiredAddons, expected]) => {
     it(`levels=${levels} requiredLevel=${requiredLevel} requiredAddons=[${(requiredAddons as string[]).join(",")}] => ${expected}`, () => {
@@ -247,57 +244,52 @@ describe("highestMatchingCredential", () => {
   });
 });
 
-describe("deriveLevel", () => {
-  it("basic only", () => {
-    expect(
-      deriveLevel({
-        ...defaultCredential,
-        // @ts-expect-error - to test absence of selfieFile
-        selfieFile: undefined,
-      }),
-    ).toBe("basic");
+describe("buildSignedCredentialContentReference", () => {
+  it("derives issuer_auth_public_key from the signing secret key", () => {
+    const keyPair = nacl.sign.keyPair();
+    const result = buildSignedCredentialContentReference("", "ipfs://cid", keyPair.secretKey);
+
+    expect(result.public_notes).toBe("");
+    expect(result.public_notes_signature).toBeTruthy();
+    expect(result.broader_signature).toBeTruthy();
+    expect(result.issuer_auth_public_key).toBe(hexEncode(keyPair.publicKey, true));
   });
+});
 
-  it("basic+liveness", () => {
-    expect(
-      deriveLevel({
-        ...defaultCredential,
-      }),
-    ).toBe("basic+liveness");
+describe("buildEphemeralSignedCredentialContentReference", () => {
+  it("returns a signed reference with a public key", () => {
+    const result = buildEphemeralSignedCredentialContentReference("", "ipfs://cid");
+
+    expect(result.public_notes).toBe("");
+    expect(result.public_notes_signature).toBeTruthy();
+    expect(result.broader_signature).toBeTruthy();
+    expect(result.issuer_auth_public_key).toMatch(/^(0x)?[0-9a-f]+$/i);
   });
+});
 
-  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");
+describe("buildPreliminaryIDOSCredential", () => {
+  const recipient = nacl.box.keyPair();
+
+  it("hashes encrypted content to an ipfs:// uri by default", async () => {
+    const result = await buildPreliminaryIDOSCredential({
+      publicNotes: "{}",
+      plaintextContent: utf8Encode("secret"),
+      recipientEncryptionPublicKey: recipient.publicKey,
+    });
+
+    expect(result.contentUri).toMatch(/^ipfs:\/\//);
+    expect(result.contentSize).toBe(result.encryptedContent.byteLength);
   });
 
-  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");
+  it("uses a provided contentUri instead of hashing to ipfs", async () => {
+    const result = await buildPreliminaryIDOSCredential({
+      publicNotes: "{}",
+      plaintextContent: utf8Encode("secret"),
+      recipientEncryptionPublicKey: recipient.publicKey,
+      contentUri: "ukyc://storage-abc/blobs/blob-1",
+    });
+
+    expect(result.contentUri).toBe("ukyc://storage-abc/blobs/blob-1");
+    expect(result.contentSize).toBe(result.encryptedContent.byteLength);
   });
 });