@idos-network/credentials 1.1.0

package/src/types/credentials.ts

@@ -0,0 +1,282 @@
+import * as z from "zod";
+
+export type idOSCredential = {
+  id: string;
+  user_id: string;
+  public_notes: string;
+  content: string;
+  encryptor_public_key: string;
+  issuer_auth_public_key: string;
+  original_id?: string | null;
+};
+
+export type InsertableIDOSCredential = Omit<idOSCredential, "id" | "original_id"> & {
+  id?: idOSCredential["id"];
+  content_hash?: string;
+  public_notes_signature: string;
+  broader_signature: 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 {
+  type: string;
+  created: string;
+  verificationMethod: string;
+  proofValue: string;
+  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> {
+  "@context": string[];
+  type: string[];
+  issuer: string;
+  id: string;
+  level: string;
+  issued: string;
+  approvedAt: string;
+  expirationDate: string;
+  credentialSubject: K;
+  issuanceDate: string;
+  proof: VerifiedCredentialsProof;
+}
+
+export type VerifiableCredential<K> = VerifiedCredentials<K>;

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export type * from "./credentials";
+export * from "./credentials";
+export type * from "./issuers";
+export * from "./issuers";

package/src/types/issuers.ts

@@ -0,0 +1,21 @@
+import type {
+  Ed25519VerificationKey2020,
+  Ed25519VerificationKey2020Options,
+} from "@digitalbazaar/ed25519-verification-key-2020";
+
+export interface CustomIssuerType {
+  issuer: string;
+
+  /* Multibase encoded public key */
+  publicKeyMultibase: string;
+
+  /* Multibase encoded private key */
+  privateKeyMultibase?: string;
+
+  /* id and controller will be generated by the library */
+}
+
+export type AvailableIssuerType =
+  | Omit<Ed25519VerificationKey2020Options, "type">
+  | Ed25519VerificationKey2020
+  | CustomIssuerType;

package/src/utils/index.ts

@@ -0,0 +1,277 @@
+import { Ed25519VerificationKey2020 } from "@digitalbazaar/ed25519-verification-key-2020";
+import { base64Decode, base64Encode, hexEncode, utf8Encode } from "@idos-network/utils/codecs";
+import * as base85 from "base85";
+import { every, get } from "es-toolkit/compat";
+import invariant from "tiny-invariant";
+import nacl from "tweetnacl";
+
+import type {
+  AvailableIssuerType,
+  CredentialFields,
+  CredentialResidentialAddress,
+  CredentialSubject,
+  CredentialSubjectFaceId,
+  CustomIssuerType,
+  InsertableIDOSCredential,
+} from "../types";
+
+export function fileToBase85(file: Buffer): string {
+  return base85.encode(file, "ascii85");
+}
+
+export function base85ToFile(data: string): Buffer | false {
+  return base85.decode(data);
+}
+
+export function capitalizeFirstLetter(str: string): string {
+  return str[0].toUpperCase() + str.slice(1);
+}
+
+function isIssuerKey(issuer: AvailableIssuerType): issuer is Ed25519VerificationKey2020 {
+  return (
+    typeof issuer === "object" &&
+    issuer !== null &&
+    "type" in issuer &&
+    "id" in issuer &&
+    "controller" in issuer
+  );
+}
+
+function isCustomIssuerType(issuer: AvailableIssuerType): issuer is CustomIssuerType {
+  return (
+    typeof issuer === "object" &&
+    issuer !== null &&
+    "issuer" in issuer &&
+    "publicKeyMultibase" in issuer
+  );
+}
+
+export async function issuerToKey(
+  issuer: AvailableIssuerType,
+): Promise<Ed25519VerificationKey2020> {
+  if (isIssuerKey(issuer)) {
+    return issuer;
+  }
+
+  if (isCustomIssuerType(issuer)) {
+    return await Ed25519VerificationKey2020.from({
+      id: `${issuer.issuer}/keys/1`,
+      controller: `${issuer.issuer}/issuers/1`,
+      publicKeyMultibase: issuer.publicKeyMultibase,
+      privateKeyMultibase: issuer.privateKeyMultibase,
+      type: "Ed25519VerificationKey2020",
+    });
+  }
+
+  return await Ed25519VerificationKey2020.from({ ...issuer, type: "Ed25519VerificationKey2020" });
+}
+
+export function convertValues<
+  K extends
+    | CredentialFields
+    | CredentialSubject
+    | CredentialResidentialAddress
+    | CredentialSubjectFaceId,
+>(fields: K, prefix?: string): Record<string, unknown> {
+  const acc: Record<string, unknown> = {};
+
+  for (const key in fields) {
+    if (Object.hasOwn(fields, key)) {
+      const value = fields[key];
+      const name = prefix ? `${prefix}${capitalizeFirstLetter(key)}` : key;
+      if (value instanceof Date) {
+        acc[name] = value.toISOString();
+      } else if (value instanceof Buffer) {
+        // Convert file to base85
+        acc[name] = fileToBase85(value);
+      } else {
+        acc[name] = value;
+      }
+    }
+  }
+
+  return acc;
+}
+
+type BaseLevel = "basic" | "plus";
+type Addon = "liveness" | "email" | "phoneNumber";
+
+export function deriveLevel(credential: CredentialSubject): string {
+  let level: BaseLevel = "basic";
+
+  // Address is a sign for plus+
+  const address = credential.residentialAddress;
+  if (address?.proofFile && address?.city && address?.proofCategory) {
+    level = "plus";
+  }
+
+  const addons: Addon[] = [];
+  if (credential.selfieFile) {
+    addons.push("liveness");
+  }
+
+  if (credential.email) {
+    addons.push("email");
+  }
+
+  if (credential.phoneNumber) {
+    addons.push("phoneNumber");
+  }
+
+  return [level, ...addons].join("+");
+}
+
+export function parseLevel(level: string): {
+  base: BaseLevel;
+  addons: Addon[];
+} {
+  const [base, ...addons] = level.split("+") as [BaseLevel, ...Addon[]];
+  return { base, addons };
+}
+
+export function matchLevelOrHigher(
+  level: BaseLevel,
+  requiredAddons: Addon[],
+  currentLevel: string,
+): boolean {
+  const { base: currentBaseLevel, addons: currentAddons } = parseLevel(currentLevel);
+
+  // TODO: Consider pop+ or uniqueness+ scenarios
+  if (level === "plus" && currentBaseLevel !== "plus") {
+    return false;
+  }
+
+  return requiredAddons.every((addon) => currentAddons.includes(addon));
+}
+
+export function levelScore(level: string): number {
+  const { base, addons } = parseLevel(level);
+  let score = 0;
+
+  if (base === "plus") {
+    score += 100;
+  }
+
+  score += addons.length * 10;
+
+  return score;
+}
+
+export function pickHighestMatchingLevel(
+  levels: string[],
+  requiredLevel: BaseLevel,
+  requiredAddons: Addon[],
+): string | null {
+  return (
+    levels
+      .filter((currentLevel) => matchLevelOrHigher(requiredLevel, requiredAddons, currentLevel))
+      .sort((a, b) => {
+        const aAddons = levelScore(a);
+        const bAddons = levelScore(b);
+        return bAddons - aAddons; // descending
+      })[0] ?? null
+  );
+}
+
+export function highestMatchingCredential<K extends { public_notes: string }>(
+  credentials: K[],
+  requiredLevel: BaseLevel,
+  {
+    addons: requiredAddons = [],
+    publicNotesConstraint = {},
+  }: {
+    addons?: Addon[];
+    publicNotesConstraint?: Record<string, number | string>;
+  },
+): K | undefined {
+  const matchingCredentials = credentials
+    .map((credential) => {
+      const publicNotes = JSON.parse(credential.public_notes || "{}");
+      return {
+        credential,
+        publicNotes,
+      };
+    })
+    .filter(({ publicNotes }) => {
+      const level = publicNotes.level;
+
+      if (!level) {
+        return false;
+      }
+
+      if (!matchLevelOrHigher(requiredLevel, requiredAddons, level)) {
+        return false;
+      }
+
+      for (const key in publicNotesConstraint) {
+        if (publicNotes[key] !== publicNotesConstraint[key]) {
+          return false;
+        }
+      }
+
+      return true;
+    })
+    .sort((a, b) => {
+      const aLevel = a.publicNotes.level;
+      const bLevel = b.publicNotes.level;
+      return levelScore(bLevel) - levelScore(aLevel); // descending
+    })
+    .map(({ credential }) => credential);
+
+  return matchingCredentials[0];
+}
+
+export function recordFilter(
+  rec: Record<string, unknown>,
+  pick: Record<string, unknown[]>,
+  omit: Record<string, unknown[]>,
+): boolean {
+  const matchCriteria = (content: Record<string, unknown>, criteria: Record<string, unknown[]>) =>
+    every(Object.entries(criteria), ([path, targetSet]) => targetSet.includes(get(content, path)));
+
+  if (Object.keys(pick).length > 0 && !matchCriteria(rec, pick)) {
+    // Fast fail on pick criteria
+    return false;
+  }
+
+  if (Object.keys(omit).length > 0 && matchCriteria(rec, omit)) {
+    // Fast fail on omit criteria
+    return false;
+  }
+
+  return true;
+}
+
+export function buildInsertableIDOSCredential(
+  userId: string,
+  publicNotes: string,
+  content: string,
+  encryptorPublicKey: string,
+): InsertableIDOSCredential {
+  invariant(encryptorPublicKey, "Missing `encryptorPublicKey`");
+
+  const ephemeralAuthenticationKeyPair = nacl.sign.keyPair();
+
+  const publicNotesSignature = nacl.sign.detached(
+    utf8Encode(publicNotes),
+    ephemeralAuthenticationKeyPair.secretKey,
+  );
+
+  return {
+    user_id: userId,
+    content,
+
+    public_notes: publicNotes,
+    public_notes_signature: base64Encode(publicNotesSignature),
+
+    broader_signature: base64Encode(
+      nacl.sign.detached(
+        Uint8Array.from([...publicNotesSignature, ...base64Decode(content)]),
+        ephemeralAuthenticationKeyPair.secretKey,
+      ),
+    ),
+
+    issuer_auth_public_key: hexEncode(ephemeralAuthenticationKeyPair.publicKey, true),
+    encryptor_public_key: encryptorPublicKey,
+  };
+}