gdc-common-utils-ts 1.0.1

package/src/constants/schemaorg.ts

@@ -0,0 +1,193 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: src/models/schemaorg.ts
+
+import { ParameterData } from "../models/params";
+
+export enum ClaimsServiceSchemaorg {
+    category = "org.schema.Service.category",
+    identifier = "org.schema.Service.identifier",
+    serviceType = "org.schema.Service.serviceType",
+    termsOfService = "org.schema.Service.termsOfService",
+}
+
+/**
+ * Defines the canonical claim names for the 'org.schema' context,
+ * based on Schema.org vocabulary.
+ */
+export enum ClaimsOrganizationSchemaorg {
+    /** ISO 3166-1 alpha-2 (two-letter country code). The jurisdiction could be the country or the region (county, province or state) */
+    addressCountry = "org.schema.Organization.address.addressCountry",
+    /** ISO 3166-2 code for administrative divisions. The jurisdiction could be the country or the region (county, province or state) */
+    addressRegion = "org.schema.Organization.address.addressRegion",
+    addressLocality = "org.schema.Organization.address.addressLocality",
+    postalCode = "org.schema.Organization.address.postalCode",
+    streetAddress = "org.schema.Organization.address.streetAddress",
+    /** `TAX` ID or `EI` (Employer ID): @see http://terminology.hl7.org/CodeSystem/v2-0203 */
+    identifierType = "org.schema.Organization.identifier.additionalType",
+    identifierValue = "org.schema.Organization.identifier.value",
+    /** Legal registered name */
+    legalName = "org.schema.Organization.legalName",
+    /** Commercial name */
+    name = "org.schema.Organization.name",
+    /** short url-friendly name (0-9,a-z) */
+    alternateName = "org.schema.Organization.alternateName",
+    /** External URL for the service */
+    url = "org.schema.Organization.url",
+    /** The identifier is a URN generated using the legal ID (TAX or EI) */
+    identifier = "org.schema.Organization.identifier",
+    /** DUNS (free) or LEI could be provided */
+    duns = "org.schema.Organization.duns",
+    /** Public contact email */
+    email = "org.schema.Organization.email",
+    /** Public contact phone */
+    telephone = "org.schema.Organization.telephone",
+    numberOfEmployees = "org.schema.Organization.numberOfEmployees.value" // to purchase licenses for device profile's activation
+}
+
+export enum ClaimsOfferSchemaorg {
+    acceptedPaymentMethod = "org.schema.Offer.acceptedPaymentMethod",
+    category = "org.schema.Offer.category",
+    checkoutPageURLTemplate = "org.schema.Offer.checkoutPageURLTemplate",
+    eligibleCustomerType = "org.schema.Offer.eligibleCustomerType",
+    eligibleQuantityValue = "org.schema.Offer.eligibleQuantity.value",
+    identifier = "org.schema.Offer.identifier",
+    itemOfferedName = "org.schema.Offer.itemOffered.name",
+    itemOfferedSku = "org.schema.Offer.itemOffered.sku",
+    offeredBy = "org.schema.Offer.offeredBy",
+    price = "org.schema.Offer.price",
+    priceCurrency = "org.schema.Offer.priceCurrency",
+    serialNumber = "org.schema.Offer.serialNumber",
+}
+
+/** For Employees (and Employee Role, but no PII) and customers / related persons.
+ * - `givenName`: The given name of the person.
+ * - `familyName`: The primary family name or surname of the person.
+ * - `alternateName`: The second surname or mother's family name, used for facilitating searches
+ *   and catering to cultures with multiple surnames.
+ * - `name`: The transliterated full name of the person, useful for standardized naming
+ *   conventions and international contexts.
+ */
+export enum ClaimsPersonSchemaorg {
+    /** Second surname or mother's maiden name */
+    additionalName = "org.schema.Person.additionalName",
+    /** Short friendly name */
+    alternateName = "org.schema.Person.alternateName",
+    birthDate = "org.schema.Person.birthDate",
+    email = "org.schema.Person.email",
+    familyName = "org.schema.Person.familyName",
+    gender = "org.schema.Person.gender",
+    givenName = "org.schema.Person.givenName",
+    hasOccupation = "org.schema.Person.hasOccupation",
+    identifier = "org.schema.Person.identifier", // the URN (composed by the provider)
+    identifierType = "org.schema.Person.identifier.additionalType", // retrieved from a form
+    identifierValue = "org.schema.Person.identifier.value", // retrieved from a form
+    /** ICAO transliteration of official given name (including middlenames), family name and addtional surname */
+    name = "org.schema.Person.name",
+    memberOf = "org.schema.Person.memberOf", // for employees
+    telephone = "org.schema.Person.telephone",
+    worksFor = "org.schema.Person.worksFor", // for employees
+    /*
+    gender = 'org.schema.Person.gender',
+    birthDate = 'org.schema.Person.birthdate',      // Date: Date of birth.
+    birthPlace = 'org.schema.Person.birthplace',    // Place: The place where the person was born.
+    nationality = 'org.schema.Person.nationality',  // Country: Nationality of the person.
+    height = 'org.schema.Person.height',
+    // Properties from Thing
+    additionalType = 'org.schema.Person.additionaltype', // e.g.: 'Employee'
+    */    
+}
+
+/**
+ * Defines the flat claim structure for a schema.org/Action.
+ * This is used for requests where an entity (agent) performs an action,
+ * often with a human controller (participant) initiating it.
+ */
+export enum ClaimsActionSchemaorg {
+  // The primary agent performing the action (e.g., the Tenant Organization)
+  agentIdentifier = 'org.schema.Action.agent.identifier',
+  agentLegalName = 'org.schema.Action.agent.legalName',
+  // ... other flattened properties of the agent ...
+
+  // A co-agent participating in the action (e.g., the Human Controller T)
+  participantIdentifier = 'org.schema.Action.participant.identifier',
+
+  // The service provider or target of the action (e.g., the Fabric Network)
+  providerIdentifier = 'org.schema.Action.provider.identifier',
+  providerName = 'org.schema.Action.provider.name',
+
+  // The time the action was initiated
+  startTime = 'org.schema.Action.startTime',
+}
+
+export const ICAOReverseDns = 'int.icao';
+export enum ICAOIdentityParams {
+  HairColor = 'int.icao.mrtd.hair-color',
+}
+
+export const indexedPersonAttributeList: string[] = [
+  ClaimsPersonSchemaorg.givenName,
+  ClaimsPersonSchemaorg.familyName,
+  ClaimsPersonSchemaorg.additionalName,
+  ClaimsPersonSchemaorg.email,
+  ClaimsPersonSchemaorg.telephone,
+  ClaimsPersonSchemaorg.birthDate,
+  ClaimsPersonSchemaorg.identifierType,
+  ClaimsPersonSchemaorg.identifierValue,
+  // ClaimsPersonSchemaorg.additionalType,
+];
+
+export const fullPersonParamsSchemaorg: ParameterData[] = [
+  {
+    name: ClaimsPersonSchemaorg.additionalName,
+    type: 'string',
+    value: undefined,
+    unique: true,
+  },
+  {
+    name: ClaimsPersonSchemaorg.familyName,
+    type: 'string',
+    value: undefined,
+    unique: true,
+  },
+  { name: ClaimsPersonSchemaorg.email, type: 'string', value: undefined },
+  {
+    name: ClaimsPersonSchemaorg.givenName,
+    type: 'string',
+    value: undefined,
+  },
+  {
+    name: ClaimsPersonSchemaorg.telephone,
+    type: 'string',
+    value: undefined,
+  },
+  {
+    name: ClaimsPersonSchemaorg.gender,
+    type: 'string',
+    value: undefined,
+    unique: true,
+  },
+  {
+    name: ClaimsPersonSchemaorg.identifierType,
+    type: 'string',
+    value: undefined,
+  },
+  {
+    name: ClaimsPersonSchemaorg.identifierValue,
+    type: 'string',
+    value: undefined,
+  },
+  {
+    name: ClaimsPersonSchemaorg.birthDate,
+    type: 'string',
+    value: undefined,
+    unique: true,
+  },
+  /*
+  {
+    name: ClaimsPersonSchemaorg.additionalType,
+    type: 'string',
+    value: undefined,
+  },
+  */
+];
+

package/src/cryptoDecode.ts

@@ -0,0 +1,104 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/cryptoEncode.ts
+
+// Function to encode a payload into a JWT with the header "alg=none"
+// senderTenant signs and encrypts to recipient(s)
+export function encodeJWT(senderKeysSet: any[], payload: any, recipientsEncKey: any[], header: any): string {
+    try {
+      // 1. Convert the header to JSON and then Base64Url encode it
+      const encodedHeader = base64UrlEncode(JSON.stringify(header));
+      
+      // 2. Convert the payload to JSON and then Base64Url encode it
+      const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+      
+      // 3. No signature for `alg=none`, so we just return the concatenation of header and payload
+      // Format: `header.payload.` (no signature part)
+      const jwt = `${encodedHeader}.${encodedPayload}.`;
+  
+      return jwt;
+    } catch (error) {
+      console.error('Error encoding JWT:', error);
+      return '';
+    }
+  }
+  
+  // Helper function to Base64Url encode a string (works for header and payload)
+  function base64UrlEncode(str: string): string {
+    // Convert the string to a Base64 string (using standard Base64 encoding first)
+    const base64 = Buffer.from(str).toString('base64');
+    
+    // Replace '+' with '-', '/' with '_', and remove the padding '='
+    return base64
+      .replace(/\+/g, '-')  // Replace '+' with '-'
+      .replace(/\//g, '_')  // Replace '/' with '_'
+      .replace(/=+$/, '');   // Remove any '=' padding at the end
+  }
+  
+  // src/managers/cryptoDecode.ts
+
+// TODO: decode, verify, encode, sign, encrypt, decrypt, all of them must be in the wallet
+// Note: each tenant can have their own wallet.
+// Function to decode JWT and handle Base64Url using native JavaScript functions
+export function decodePayloadRequest(targetTenant: string, requestJAR: string | undefined, authorizationHeader: string | undefined): any {
+    try {
+      let authToken: string | undefined;
+      // TODO: auth token could be protected in the request: payload.body.meta.http.header.bearer.source
+      // TODO: this function will decode the bearer (auth) token and set it here: payload.body.meta.http.header.bearer.decoded
+      // TODO: first of all the request must be decrypted in case of JWE, then the nested JWT is decoded
+      // If not in the JAR, look for auth token in the Authorization header (Bearer token)
+      if (authorizationHeader) {
+        authToken = authorizationHeader.replace('Bearer ', '').trim();
+      }
+  
+      // If the token is not found, return an error
+      if (!authToken) {
+        throw new Error('No JWT found in request or Authorization header');
+      }
+  
+      // Decode the JWT (Base64Url format as per the JOSE specification)
+      const [header, payload, signature] = authToken.split('.');
+  
+      if (!payload) {
+        throw new Error('JWT payload is missing');
+      }
+      const decodedPayload = decodeBase64Url(payload);
+    
+      // Return the decoded payload that contains the body and data
+      return decodedPayload;
+    } catch (error) {
+      console.error('Error decoding JWT payload:', error);
+      return null;
+    }
+  }
+
+export function decodeBase64Url(base64Url: string): string {
+  try {
+    // Convert Base64Url to Base64 by replacing '-' with '+' and '_' with '/'
+    let base64 = base64Url
+      .replace(/-/g, '+')  // Replace '-' with '+'
+      .replace(/_/g, '/'); // Replace '_' with '/'
+
+    // Ensure that Base64 has the correct size (padding)
+    const padding = base64.length % 4;
+    if (padding) {
+      base64 += '='.repeat(4 - padding); // Add the necessary padding
+    }
+
+    // Decode the Base64 string using Buffer (for Node.js)
+    const decodedString = Buffer.from(base64, 'base64').toString('utf-8');
+
+    // Check if decoding results in a valid JSON string
+    try {
+      JSON.parse(decodedString); // Ensure it's valid JSON
+    } catch (e) {
+      console.error('Invalid Base64Url string:', e);
+      return ''; // Return empty string for invalid JSON payload
+    }
+
+    return decodedString;
+  } catch (error) {
+    console.error('Error decoding Base64Url string:', error);
+    return ''; // Return empty string if there's an error during decoding
+  }
+}
+

package/src/cryptoEncode.ts

@@ -0,0 +1,36 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/cryptoEncode.ts
+
+// Function to encode a payload into a JWT with the header "alg=none"
+// senderTenant signs and encrypts to recipient(s)
+export function encodeJWT(senderKeysSet: any[], payload: any, recipientsEncKey: any[], header: any): string {
+    try {
+      // 1. Convert the header to JSON and then Base64Url encode it
+      const encodedHeader = base64UrlEncode(JSON.stringify(header));
+      
+      // 2. Convert the payload to JSON and then Base64Url encode it
+      const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+      
+      // 3. No signature for `alg=none`, so we just return the concatenation of header and payload
+      // Format: `header.payload.` (no signature part)
+      const jwt = `${encodedHeader}.${encodedPayload}.`;
+  
+      return jwt;
+    } catch (error) {
+      console.error('Error encoding JWT:', error);
+      return '';
+    }
+  }
+  
+  // Helper function to Base64Url encode a string (works for header and payload)
+  function base64UrlEncode(str: string): string {
+    // Convert the string to a Base64 string (using standard Base64 encoding first)
+    const base64 = Buffer.from(str).toString('base64');
+    
+    // Replace '+' with '-', '/' with '_', and remove the padding '='
+    return base64
+      .replace(/\+/g, '-')  // Replace '+' with '-'
+      .replace(/\//g, '_')  // Replace '/' with '_'
+      .replace(/=+$/, '');   // Remove any '=' padding at the end
+  }
+  

package/src/cryptography.abstract.ts

@@ -0,0 +1,29 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/cryptography.abstract.ts
+
+export abstract class CryptographyManagerAbstract {
+    protected publicJWK = {};
+    protected privateKeyBytes!: Uint8Array;
+
+    constructor() {
+    }
+
+    /** Initializes public and private keys. */
+    protected abstract newKeys(seedBytes?: Uint8Array): Promise<void>;
+
+    /** Sets the public and private keys to be used. */
+    protected setKeys(publicJWK: any, privateKeyBytes: Uint8Array): void {
+        this.publicJWK = publicJWK;
+        this.privateKeyBytes = privateKeyBytes;
+    }
+
+    /** Returns the public JWK */
+    public getPublicJWK(): any {
+        return this.publicJWK;
+    }
+
+    /** Returns the public Key ID ('kid') or empty string */
+    public getKeyID(): string {
+        return this.getPublicJWK().kid ? this.getPublicJWK().kid : '';
+    }
+}

package/src/hmac.ts

@@ -0,0 +1,15 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/hmac.ts
+
+// Use explicit .js subpaths to satisfy package exports in Metro/Node ESM.
+import { hmac } from '@noble/hashes/hmac.js';
+import { sha3_256 } from '@noble/hashes/sha3.js';
+import { Content } from './utils/content';
+
+export async function computeHmacSha256(plaintext: string, hmacKeyBytes: Uint8Array): Promise<Uint8Array> {
+    return await hmac(sha3_256, hmacKeyBytes, Content.stringToBytesUTF8(plaintext));
+}
+
+export async function computeHmacSha256Base64Url(plaintext: string, hmacKeyBytes: Uint8Array): Promise<string> {
+    return  Content.bytesToRawBase64UrlSafe(await computeHmacSha256(plaintext, hmacKeyBytes));
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './AesManager';
+export * from './CryptographyService';
+export * from './hmac';

package/src/interfaces/Cryptography.types.ts

@@ -0,0 +1,131 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/interfaces/Cryptography.types.ts
+
+/**
+ * JWK shapes and RFC 7638 thumbprints for ML-KEM and ML-DSA.
+ *
+ * References (normative)
+ * @see https://www.rfc-editor.org/rfc/rfc7638           // JWK Thumbprint
+ * @see https://www.rfc-editor.org/rfc/rfc7517           // JWK
+ * @see https://www.rfc-editor.org/rfc/rfc7515#appendix-C // base64url (no padding)
+ * @see https://www.rfc-editor.org/rfc/rfc8037           // OKP key type
+ * @see https://www.rfc-editor.org/rfc/rfc9278           // JWK Thumbprint URI
+ *
+ * Post-quantum mappings
+ * @see https://datatracker.ietf.org/doc/draft-ietf-jose-pqc-kem/                 // JOSE PQ KEM
+ * @see https://datatracker.ietf.org/doc/draft-ietf-cose-dilithium/               // ML-DSA for JOSE/COSE (datatracker)
+ * @see https://cose-wg.github.io/draft-ietf-cose-dilithium/draft-ietf-cose-dilithium.html // ML-DSA (GitHub pages)
+ *
+ * NIST algorithm specs
+ * @see https://csrc.nist.gov/pubs/fips/203/final // FIPS 203 ML-KEM (landing)
+ * @see https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.203.pdf // FIPS 203 PDF
+ * @see https://csrc.nist.gov/pubs/fips/204/final // FIPS 204 ML-DSA (landing)
+ * @see https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.204.pdf // FIPS 204 PDF
+ */
+
+export type CurveMlKem512 = "ML-KEM-512";
+export type CurveMlKem768 = "ML-KEM-768";
+export type CurveMlKem1024 = "ML-KEM-1024";
+
+export type MlkemCurve = CurveMlKem512 | CurveMlKem768 | CurveMlKem1024;
+
+export type AlgMlDsa2 = "ML-DSA-44";
+export type AlgMlDsa3 = "ML-DSA-65";
+export type AlgMlDsa5 ="ML-DSA-87";
+
+export type MldsaAlg = AlgMlDsa2 | AlgMlDsa3 | AlgMlDsa5;
+
+// Base JWKs used for RFC 7638 thumbprint calculation
+export type MlkemBaseJwk = { kty: "OKP"; crv: MlkemCurve; x: string };
+export type MldsaBaseJwk = { kty: "AKP"; alg: MldsaAlg; pub: string };
+export type EcBaseJwk = { kty: "EC"; crv: string; x: string; y: string };
+export type BaseJwk = MlkemBaseJwk | MldsaBaseJwk | EcBaseJwk;
+
+export interface MlkemPublicJwk extends MlkemBaseJwk {
+    kid?: string;     // filled from thumbprint
+};
+
+export interface MldsaPublicJwk extends MldsaBaseJwk {
+    kid?: string;     // filled from thumbprint
+};
+
+/**
+ * Represents a public key for classic cryptography algorithms like Elliptic Curve.
+ */
+export interface ClassicPublicJwk {
+    kty: "EC";
+    crv: string; // e.g., "P-256"
+    x: string;
+    y: string;
+    kid?: string;
+    alg?: string;
+    use?: string;
+};
+
+/**
+ * Represents a public key in JWK format, suitable for public documents like DIDs.
+ * This is a union of all supported public key types, both Post-Quantum and classic.
+ */
+export type PublicJwk = MlkemPublicJwk | MldsaPublicJwk | ClassicPublicJwk;
+
+export interface MlkemPrivateJwk extends MlkemPublicJwk{
+    // Private material (extended seed) must never be published:
+    dBytes: Uint8Array;
+};
+
+export interface MldsaPrivateJwk extends MldsaPublicJwk{
+    // Private material (extended seed) must never be published:
+    privBytes: Uint8Array;
+};
+
+export interface RecipientInfo {
+  tenantId: string;
+  header?: Record<string, any>;
+}
+
+export interface SignerInfo {
+  tenantId: string;
+  protectedHeader: Record<string, any>;
+  unprotectedHeader?: Record<string, any>;
+}
+
+export interface ProtectRequest {
+  stream: Uint8Array;
+  recipients: RecipientInfo[];
+  protectedHeader?: Record<string, any>; // is it meta.jws.protected?
+  unprotectedHeader?: Record<string, any>; // is it meta.jws.unprotected?
+  aad?: Uint8Array;// src/adapters/queue.ts
+  input: Record<string, any>;
+  meta?: {
+    jws?: { protected?: Record<string, any>; unprotected?: Record<string, any>;}; // protected and unprotected headers
+    jwe?: { header?: Record<string, any>; }; // public unencypted header from the JWE
+    bearer?: { jwt: { header?: Record<string, any>; payload?: Record<string, any>; } }
+  };
+}
+
+export interface JWEData {
+  protected?: string;
+  unprotected?: Record<string, any>;
+  recipients: Array<{
+    header?: Record<string, any>;
+    encrypted_key?: string;
+  }>;
+  aad?: string;
+  iv: string;
+  ciphertext: string;
+  tag: string;
+}
+
+export interface SignRequest {
+  payload: Uint8Array;
+  signers: SignerInfo[];
+}
+
+export interface JwsObject {
+  payload: string;
+  signatures: Array<{
+    protected: string;
+    unprotected?: Record<string, any>;
+    signature: string;
+  }>;
+}

package/src/interfaces/ICryptoHelper.ts

@@ -0,0 +1,33 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/interfaces/ICryptoHelper.ts
+
+/**
+ * @interface ICryptoHelper
+ * Defines the contract for platform-specific cryptographic primitives.
+ * This is the "port" in a hexagonal architecture, allowing the agnostic
+ * core (CryptographyService) to be "plugged into" any runtime environment
+ * (like Expo, Node, or Web) without depending on its implementation details.
+ */
+export interface ICryptoHelper {
+  /**
+   * Generates a specified number of cryptographically secure random bytes.
+   * @param byteCount The number of bytes to generate.
+   * @returns A Promise that resolves to a Uint8Array with the random bytes.
+   */
+  getRandomBytes(byteCount: number): Promise<Uint8Array>;
+
+  /**
+   * Computes the cryptographic digest of a string using a specified algorithm.
+   * The implementation is responsible for validating the algorithm string.
+   * @param data The string to hash.
+   * @param algorithm The hash algorithm to use (e.g., 'SHA-256', 'SHA-512').
+   * @returns A Promise that resolves to the digest as a hex string.
+   */
+  digestString(data: string, algorithm: any): Promise<string>;
+
+  /**
+   * Generates a platform-specific, cryptographically secure UUID v4.
+   * @returns A string representation of the UUID.
+   */
+  randomUUID(): string;
+}