gdc-common-utils-ts 1.0.1

package/src/utils/baseN.ts

@@ -0,0 +1,203 @@
+/**
+ * From https://raw.githubusercontent.com/digitalbazaar/base58-universal/master/baseN.js
+ * Base-N/Base-X encoding/decoding functions.
+ *
+ * Original implementation from base-x:
+ * https://github.com/cryptocoinjs/base-x
+ *
+ * Which is MIT licensed:
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright base-x contributors (c) 2016
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+'use strict';
+
+import { bytesToStringUTF8, stringToBytesUTF8 } from './string-convert';
+
+// baseN alphabet indexes
+const _reverseAlphabets: any = [];
+
+// base58 characters (Bitcoin alphabet)
+export const alphabetBase58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+export class BaseN {
+  constructor() { }
+
+  /** BaseN-encodes a Uint8Array using the given alphabet */
+  public static encodeN(input: Uint8Array, alphabet: string, maxline: string | undefined): string {
+    return encodeN(input, alphabet, maxline);
+  }
+
+  /** Decodes a baseN-encoded (using the given alphabet) string to a Uint8Array. */
+  public static decodeN(input: string, alphabet: string): Uint8Array {
+    return decodeN(input, alphabet);
+  }
+
+  /** Base58-encodes a Uint8Array using the Bitcoin alphabet '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz' */
+  public static encodeBytesToBase58(inputBytes: Uint8Array): string {
+    return encodeN(inputBytes, alphabetBase58, undefined);
+  }
+
+  /** Base58-encodes a Uint8Array using the Bitcoin alphabet '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz' */
+  public static encodeStrToBase58(inputStr: string): string {
+    const inputBytes: Uint8Array = stringToBytesUTF8(inputStr);
+    return this.encodeBytesToBase58(inputBytes);
+  }
+
+  /** Decodes a base58-encoded string to a Uint8Array (using the Bitcoin alphabet '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz') */
+  public static decodeBytesFromBase58(base58Str: string): Uint8Array {
+    return decodeN(base58Str, alphabetBase58);
+  }
+
+  /** Decodes a base58-encoded string to a Uint8Array (using the Bitcoin alphabet '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz') */
+  public static decodeStrFromBase58(base58Str: string): string {
+    const inputBytes: Uint8Array = this.decodeBytesFromBase58(base58Str);
+    return bytesToStringUTF8(inputBytes);
+  }
+
+  // decodeToUtf8String = (utf8StringArg: string): string => decodeToUtf8String(utf8StringArg)
+
+}
+
+
+/**
+  * BaseN-encodes a Uint8Array using the given alphabet.
+  *
+  * @param {Uint8Array} input the bytes to encode in a Uint8Array.
+  * @param {number} maxline the maximum number of encoded characters per line to
+  *          use, defaults to none.
+  *
+  * @return {string} the baseN-encoded output string.
+  */
+export function encodeN(input: Uint8Array, alphabet: string, maxline: string | undefined): string {
+  if (!(input instanceof Uint8Array)) {
+    throw new TypeError('"input" must be a Uint8Array.');
+  }
+  if (typeof alphabet !== 'string') {
+    throw new TypeError('"alphabet" must be a string.');
+  }
+  if (maxline !== undefined && typeof maxline !== 'number') {
+    throw new TypeError('"maxline" must be a number.');
+  }
+  if (input.length === 0) {
+    return '';
+  }
+
+  let output: string = '';
+
+  let i = 0;
+  const base = alphabet.length;
+  const first = alphabet.charAt(0);
+  const digits = [0];
+  for (i = 0; i < input.length; ++i) {
+    let carry = input[i];
+    for (let j = 0; j < digits.length; ++j) {
+      carry += digits[j] << 8;
+      digits[j] = carry % base;
+      carry = (carry / base) | 0;
+    }
+
+    while (carry > 0) {
+      digits.push(carry % base);
+      carry = (carry / base) | 0;
+    }
+  }
+
+  // deal with leading zeros
+  for (i = 0; input[i] === 0 && i < input.length - 1; ++i) {
+    output += first;
+  }
+  // convert digits to a string
+  for (i = digits.length - 1; i >= 0; --i) {
+    output += alphabet[digits[i]];
+  }
+
+  if (maxline) {
+    const match = output.match(new RegExp('.{1,' + maxline + '}', 'g'));
+    if (match) {
+      output = match.join('\r\n');
+    }
+  }
+
+  return output;
+}
+
+/**
+  * Decodes a baseN-encoded (using the given alphabet) string to a
+  * Uint8Array.
+  *
+  * @param {string} input the baseN-encoded input string.
+  *
+  * @return {Uint8Array} the decoded bytes in a Uint8Array.
+  */
+export function decodeN(input: string, alphabet: string): Uint8Array {
+  if (typeof input !== 'string') {
+    throw new TypeError('"input" must be a string.');
+  }
+  if (typeof alphabet !== 'string') {
+    throw new TypeError('"alphabet" must be a string.');
+  }
+  if (input.length === 0) {
+    return new Uint8Array(0);
+  }
+
+  let table = _reverseAlphabets[alphabet];
+  if (!table) {
+    // compute reverse alphabet
+    table = _reverseAlphabets[alphabet] = [];
+    for (let i = 0; i < alphabet.length; ++i) {
+      table[alphabet.charCodeAt(i)] = i;
+    }
+  }
+
+  // remove whitespace characters
+  input = input.replace(/\s/g, '');
+
+  const base = alphabet.length;
+  const first = alphabet.charAt(0);
+  const bytes = [0];
+  for (let i = 0; i < input.length; i++) {
+    const value = table[input.charCodeAt(i)];
+    if (value === undefined) {
+      return new Uint8Array(0); // empty
+    }
+
+    let carry = value;
+    for (let j = 0; j < bytes.length; ++j) {
+      carry += bytes[j] * base;
+      bytes[j] = carry & 0xff;
+      carry >>= 8;
+    }
+
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+
+  // deal with leading zeros
+  for (let k = 0; input[k] === first && k < input.length - 1; ++k) {
+    bytes.push(0);
+  }
+
+  return new Uint8Array(bytes.reverse());
+}

package/src/utils/bundle.ts

@@ -0,0 +1,30 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+/**
+ * Normalizes either FHIR Bundle (entry[]) or JSON:API bundle (data[])
+ * into an array of resources.
+ */
+export function extractResources(bundle: any): any[] {
+  if (!bundle) return [];
+  if (Array.isArray(bundle.entry)) {
+    return bundle.entry
+      .map((e: any) => e && (e.resource || e))
+      .filter(Boolean);
+  }
+  if (Array.isArray(bundle.data)) {
+    return bundle.data
+      .map((d: any) => d && (d.resource || d))
+      .filter(Boolean);
+  }
+  if (bundle.resourceType) return [bundle];
+  return [];
+}
+
+export function getNextLink(bundle: any): string | null {
+  if (Array.isArray(bundle?.link)) {
+    const next = bundle.link.find((l: any) => l.relation === 'next');
+    if (next?.url) return next.url;
+  }
+  if (bundle?.links?.next) return bundle.links.next;
+  return null;
+}

package/src/utils/content.ts

@@ -0,0 +1,66 @@
+// crypto-ts/utils/convert.ts
+
+import * as baseConvert from './base-convert';
+import * as objectConvert from './object-convert';
+import * as stringConvert from './string-convert';
+import * as stringUtils from './string-utils';
+
+/**
+ * A unified facade class for all data conversion and utility functions.
+ * This class encapsulates functionality from the various utility modules
+ * (base-convert, object-convert, etc.) into a single, consistent interface.
+ */
+export class Content {
+    // --- String Conversions (from string-convert.ts) ---
+    /** Encodes a string into a Uint8Array of strictly-validated UTF-8 bytes. */
+    static stringToBytesUTF8 = stringConvert.stringToBytesUTF8;
+    /** Decodes a Uint8Array of strictly-validated UTF-8 bytes back into a string. */
+    static bytesToStringUTF8 = stringConvert.bytesToStringUTF8;
+    /** Decodes a Uint8Array containing binary/ASCII data into a string. */
+    static bytesToStringASCII = stringConvert.bytesToStringASCII;
+
+    // --- String Utilities (from string-utils.ts) ---
+    /** Capitalizes the first letter of a string. */
+    static capitalize = stringUtils.capitalize;
+    /** A simple string sanitizer. */
+    static sanitizeString = stringUtils.sanitizeString;
+    /** Converts a string to a string of its ASCII character codes. */
+    static stringToASCII = stringUtils.stringToASCII;
+    /** Converts a string to an array of numbers representing its byte values. */
+    static stringToBytesArrayOfNumbers = stringUtils.stringToBytesArrayOfNumbers;
+
+    // --- Base Conversions (from base-convert.ts) ---
+    /** Converts a Uint8Array to a hexadecimal string. */
+    static bytesToHexString = baseConvert.bytesToHexString;
+    /** Encodes a Uint8Array into a Base58 string. */
+    static bytesToBase58 = baseConvert.bytesToBase58;
+    /** Decodes a Base58 string into a Uint8Array. */
+    static base58ToBytes = baseConvert.base58ToBytes;
+    /** Encodes a string into a standard Base64 string (with padding). */
+    static stringToStdBase64 = baseConvert.stringToStdBase64;
+    /** Converts a standard Base64 string to a Base64URL string. */
+    static base64ToBase64Url = baseConvert.base64ToBase64Url;
+    /** Encodes a string into a Base64URL string. */
+    static stringToBase64Url = baseConvert.stringToBase64Url;
+    /** Converts a Base64URL string to a standard Base64 string. */
+    static base64UrlToBase64 = baseConvert.base64UrlToBase64;
+    /** Decodes a string that is either Base64 or Base64URL into a Uint8Array. */
+    static base64ToBytes = baseConvert.base64OrUrlSafeToBytes;
+    /** Encodes a Uint8Array into a standard Base64 string (with padding). */
+    static bytesToBase64 = baseConvert.bytesToBase64;
+    /** Encodes a Uint8Array into a raw Base64URL string (no padding). */
+    static bytesToRawBase64UrlSafe = baseConvert.bytesToRawBase64UrlSafe;
+
+    // --- Object & Array Conversions (from object-convert.ts) ---
+    /** Compares two arrays and returns true if they are the same, false otherwise. */
+    static arrayCompare = objectConvert.arrayCompare;
+    /** Merges two Uint8Arrays into a single Uint8Array. */
+    static arrayMerge = objectConvert.arrayMerge;
+    /** Serializes a JavaScript object to a Uint8Array of UTF-8 bytes. */
+    static objectToBytes = objectConvert.objectToBytes;
+    /** Serializes a JavaScript object to a raw Base64URL string. */
+    static objectToRawBase64UrlSafe = objectConvert.objectToRawBase64UrlSafe;
+    /** Deserializes a Base64URL string back into a JavaScript object. */
+    static base64UrlSafeToJSON = objectConvert.base64UrlSafeToJSON;
+}
+

package/src/utils/did.ts

@@ -0,0 +1,155 @@
+// crypto-ts/utils/did.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import { ServiceEndpointSelector } from "../models/did";
+
+/**
+ * Generates a DID Service ID fragment from a selector object.
+ * The format is always `#<section>:<format>:<resourceType>:<action>`.
+ *
+ * This utility's only job is to correctly assemble the string. It contains no
+ * conditional logic about DID types, as that is handled by the data layer.
+ *
+ * @param selector The structured object containing the endpoint parts.
+ * @returns The formatted service ID fragment string.
+ */
+export function generateServiceId(selector: ServiceEndpointSelector): string {
+  // Canonical casing:
+  // - `section`, `format`, `resourceType` are matched case-insensitively by the backend router,
+  //   and lowercasing them makes DID Document lookup deterministic across SDKs.
+  // - `action` is kept as-is (future actions may be case-sensitive identifiers).
+  const parts = [
+    selector.section?.toLowerCase(),
+    selector.format?.toLowerCase(),
+    selector.resourceType?.toLowerCase(),
+    selector.action,
+  ];
+  
+  return `#${parts.filter(p => p).join(':')}`;
+}
+
+/**
+ * Normalizes a did:web string to a canonical format to prevent resolution errors
+ * due to case sensitivity in the path component of the underlying URL.
+ *
+ * The rule is:
+ * - All segments are lowercased, EXCEPT the final segment.
+ * - If the final segment represents a `system|code` pair (e.g., for a role),
+ *   the `system` part is lowercased, but the `code` is preserved as-is.
+ * - If the final segment is a unique identifier (like a Tax ID), it is preserved as-is.
+ *
+ * @param did The did:web string to normalize.
+ * @returns The canonicalized did:web string.
+ */
+export function normalizeDidWeb(did: string): string {
+  const parts = did.split(':');
+  if (parts[0] !== 'did' || parts[1] !== 'web' || parts.length < 3) {
+    // Not a valid did:web, return as is.
+    return did;
+  }
+
+  // Lowercase all parts except the very last one.
+  const lowercasedParts = parts.slice(0, -1).map(part => part.toLowerCase());
+  let lastPart = parts[parts.length - 1];
+
+  // Special handling for the last part if it contains a role descriptor.
+  if (lastPart.includes('|')) {
+    const [system, ...codeParts] = lastPart.split('|');
+    const code = codeParts.join('|'); // Re-join in case the code itself has a pipe.
+    lastPart = `${system.toLowerCase()}|${code}`;
+  }
+
+  return [...lowercasedParts, lastPart].join(':');
+}
+
+/**
+* Encodes a hostname according to did:web spec (percent-encodes port colons).
+* @param apiUrl The full base URL of the API.
+* @returns The percent-encoded hostname.
+*/
+function getEncodedHost(apiUrl: string): string {
+  try {
+    const parsedUrl = new URL(apiUrl);
+    return parsedUrl.host.replace(':', '%3A');
+  } catch (e) {
+    console.error(`[getEncodedHost] Invalid apiUrl provided: ${apiUrl}`);
+    return 'localhost'; // Fallback
+  }
+}
+
+/**
+* Creates the deterministic "hosted" did:web for a tenant (Organization).
+*
+* @param hostDidWeb The DID of the host (e.g., 'did:web:host.example.com').
+* @param tenantAlternateName The alternate name of the tenant (e.g., 'acme').
+* @param context An object containing jurisdiction, version, and sector.
+* @returns The tenant's full, correctly formatted hosted did:web.
+*          Example: 'did:web:host.example.com:acme:cds-es:v1:health-care'
+*/
+export function createHostedDidWeb(
+  hostDidWeb: string,
+  tenantAlternateName: string,
+  context: { jurisdiction: string; version: string; sector: string }
+): string {
+  const hostPart = hostDidWeb.replace(/^did:web:/, '');
+  // The path in a did:web uses colons as separators.
+  const didPath = `cds-${context.jurisdiction}:${context.version}:${context.sector}`;
+  return `did:web:${hostPart}:${tenantAlternateName}:${didPath}`;
+}
+
+
+/**
+ * Builds the canonical details (URL and did:web URN) for a hosted DID.
+ * This is the single source of truth for constructing hosted identifiers in the app.
+ *
+ * @param options An object with the components of the DID.
+ * @param options.host The provider's domain (e.g., 'provider.com').
+ * @param options.alternateName The tenant's identifier (e.g., 'acme').
+ * @param options.jurisdiction The legal jurisdiction (defaults to 'ES').
+ * @param options.sector The business sector (defaults to 'health-care').
+ * @returns An object with the full URL (with trailing /) and the canonical did:web.
+ */
+export function buildHostedDidDetails({
+  host,
+  alternateName,
+  jurisdiction = 'ES',
+  sector = 'health-care',
+}: {
+  host: string;
+  alternateName: string;
+  jurisdiction?: string;
+  sector?: string;
+}) {
+  // 1. Build the path part of the DID/URL.
+  const pathPart = `${alternateName}/cds-${jurisdiction}/v1/${sector}`;
+  
+  // 2. Build the full URL, ensuring a trailing slash.
+  const url = `https://${host}/${pathPart}/`;
+  
+  // 3. Build the canonical did:web, replacing / with :.
+  const hostAndPath = `${host}/${pathPart}`;
+  const did = `did:web:${hostAndPath.replace(/\//g, ':')}`;
+  
+  return { did, url };
+}
+
+/**
+* Converts a did:web identifier into a full HTTPS or HTTP base URL with a trailing slash.
+* It correctly decodes percent-encoded ports for local development.
+* @param did The did:web string (e.g., 'did:web:example.com' or 'did:web:localhost%3A3000:acme:cds-es:v1:health-care').
+* @returns The full base URL (e.g., 'https://example.com/acme/cds-es/v1/health-care/').
+*/
+export function getBaseUrlFromDidWeb(did: string): string {
+  const didParts = did.replace(/^did:web:/, '').split(':');
+  const domainPart = didParts[0];
+  const pathParts = didParts.slice(1);
+  
+  const decodedDomain = decodeURIComponent(domainPart);
+  const protocol = decodedDomain.startsWith('localhost') ? 'http' : 'https';
+  
+  const path = pathParts.join('/').replace(/cds-(es|us|gb)/, (match, p1) => `cds-${p1.toUpperCase()}`);
+
+  // Ensure a trailing slash for the base URL, without double slashes when no path is present.
+  const normalizedPath = path ? `${path}/` : '';
+  return `${protocol}://${decodedDomain}/${normalizedPath}`;
+}

package/src/utils/format-converter.ts

@@ -0,0 +1,119 @@
+// crypto-ts/utils/format-converter.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import { safelyJoinUrl } from "./url";
+
+/**
+ * Normalizes a FHIR resource or Bundle into an array of entries.
+ */
+export const convertResourceDataToArrayOfDataEntries = (inputData: any, requestPath: string, webDomain: string): any[] => {
+  if (inputData.resourceType) { // It is FHIR data
+    if (inputData.resourceType === 'Bundle') {
+      return inputData.entry || [];
+    } else {
+      const resourceIdentifier = inputData.id || (inputData.identifier && inputData.identifier[0]?.value) || "";
+      const fullUrl = safelyJoinUrl(webDomain, safelyJoinUrl(requestPath, resourceIdentifier));
+      return [{ fullUrl, resource: inputData }];
+    }
+  } else { // Assume it's already a JSON:API-like object
+    const resourceIdentifier = inputData.id || "";
+    // const fullUrl = safelyJoinUrl(webDomain, safelyJoinUrl(requestPath, resourceIdentifier));
+    return [inputData];
+  }
+};
+
+/**
+ * Converts a resource or a FHIR Bundle to a JSON:API Primary Document.
+ */
+export const convertResourceOrBundleToPrimaryDoc = (resourceData: any, specification: string, webDomain: string, requestPath: string): any => {
+  const entries = convertResourceDataToArrayOfDataEntries(resourceData, requestPath, webDomain);
+  
+  // Handle FHIR entry structure vs. JSON:API data structure
+  const data = entries.map(entry => {
+    if (entry.resource) { // It's a FHIR entry
+      return {
+        type: `${specification}.${entry.resource.resourceType}`,
+        id: entry.resource.id,
+        attributes: { ...entry.resource }
+      };
+    }
+    return entry; // Assumes it's already a JSON:API resource object
+  });
+
+  return { data };
+};
+
+/**
+ * Converts a JSON:API Primary Document back to a FHIR Bundle.
+ */
+export const convertPrimaryDocToBundleFHIR = (primaryDocument: any, bundleType: string): any => {
+  const entries: any[] = [];
+  if (primaryDocument.data) {
+    entries.push(...primaryDocument.data.map((jsonApiResourceObject: any) => ({
+      // fullUrl might need to be reconstructed based on context
+      resource: jsonApiResourceObject.attributes || jsonApiResourceObject
+    })));
+  }
+  if (primaryDocument.errors) {
+    entries.push(...primaryDocument.errors.map((errorObject: any) => ({
+      resource: {
+        resourceType: 'OperationOutcome',
+        id: errorObject.id,
+        issue: [{
+          code: errorObject.status,
+          severity: 'error',
+          details: { text: errorObject.detail },
+        }]
+      }
+    })));
+  }
+  
+  return {
+    entry: entries,
+    resourceType: 'Bundle',
+    total: primaryDocument.data ? primaryDocument.data.length : 0,
+    type: bundleType
+  };
+};
+
+
+/**
+ * Converts a FHIR Bundle containing one or more OperationOutcome entries into a
+ * compliant JSON:API Error Document. Each error entry in the bundle is mapped
+ * to a corresponding error object in the JSON:API `errors` array.
+ *
+ * @param errorBundle The FHIR Bundle representing the error(s).
+ * @returns A JSON:API document with a top-level `errors` array.
+ */
+export const convertFhirErrorBundleToJsonApiError = (errorBundle: any): any => {
+  if (!errorBundle.entry || errorBundle.entry.length === 0) {
+    return {
+      errors: [{
+        status: '500',
+        title: 'Unknown Error',
+        detail: 'An unspecified error occurred and the error bundle was malformed or empty.'
+      }]
+    };
+  }
+
+  const errorObjects = errorBundle.entry.map((entry: any) => {
+    const resource = entry.resource || {};
+    const issue = resource.issue ? resource.issue[0] : {};
+    const title = issue.details?.text || 'Processing Error';
+
+    return {
+      id: resource.id,
+      status: entry.response?.status?.toString() || '500',
+      code: issue.code || 'processing-error',
+      title: title,
+      detail: issue.diagnostics || 'An error occurred while processing the request.',
+      meta: {
+        severity: issue.severity || 'error'
+      }
+    };
+  });
+
+  return {
+    errors: errorObjects
+  };
+};

package/src/utils/index.ts

@@ -0,0 +1,13 @@
+export * from './actor';
+export * from './base-convert';
+export * from './baseN';
+export * from './bundle';
+export * from './content';
+export * from './did';
+export * from './format-converter';
+export * from './jwt';
+export * from './manager-error';
+export * from './multibase58';
+export * from './multibasehash';
+export * from './normalize';
+export * from './object-convert';