gdc-common-utils-ts 1.0.1

package/src/models/openid-device.ts

@@ -0,0 +1,146 @@
+// src/models/openid-device.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+/**
+ * @fileoverview Defines data models for device registration based on OpenID Connect Dynamic Client Registration 1.0,
+ * with custom extensions for native device information.
+ * @see https://openid.net/specs/openid-connect-registration-1_0.html
+ */
+
+import { JwkSet } from "./jwk";
+
+/**
+ * Represents the information about the physical device being registered.
+ * This is a custom extension to the OpenID DCR standard.
+ */
+export interface OpenIdDeviceInfo {
+  /**
+   * The push notification token for the device.
+   * @example "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
+   */
+  push_token: string;
+
+  /**
+   * The push notification provider.
+   * @example "expo"
+   */
+  push_provider: string;
+
+  /**
+   * A unique identifier for the device, such as the OS internal build ID.
+   * @example "19.6.0"
+   */
+  device_id: string;
+
+  /**
+   * A user-friendly name for the device.
+   * @example "John's iPhone"
+   */
+  device_name: string;
+}
+
+/**
+ * Represents the request payload for Dynamic Client Registration,
+ * based on OpenID Connect Registration 1.0.
+ * The `body` of the DIDComm message will contain this object.
+ * @see https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest
+ */
+export interface DcrRegistrationRequest {
+  // --- Standard OIDC DCR Fields ---
+
+  /**
+   * Array of redirection URIs for use in redirect-based flows. For a native app,
+   * this could be a custom scheme URI.
+   * @example ["myapp://callback"]
+   */
+  redirect_uris: string[];
+
+  /**
+   * Kind of the application. The only supported value is 'native'.
+   */
+  application_type?: 'native';
+  
+  /**
+   * Human-readable name of the client to be presented to the end-user.
+   * @example "My Awesome App"
+   */
+  client_name?: string;
+
+  /**
+   * URL of the home page of the client.
+   */
+  client_uri?: string;
+
+  /**
+   * Requested authentication method for the token endpoint.
+   * For apps using public keys, 'private_key_jwt' is common.
+   * 'none' can be used for public clients.
+   */
+  token_endpoint_auth_method?: 'none' | 'private_key_jwt';
+
+  /**
+   * A list of OAuth 2.0 grant types that the client will restrict itself to using.
+   */
+  grant_types?: ('authorization_code' | 'implicit' | 'refresh_token' | 'client_credentials')[];
+
+  /**
+   * URL for the client's JSON Web Key Set [JWK] document. If the client signs requests to the Server,
+   * it contains the signing key(s) the Server uses to validate signatures from the Client.
+   */
+  jwks_uri?: string;
+
+  /**
+   * JSON Web Key Set containing the client's public keys.
+   * REQUIRED if `jwks_uri` is not provided.
+   */
+  jwks?: JwkSet; 
+
+  // --- Custom Extension Fields ---
+
+  /**
+   * Custom data about the specific device instance being registered.
+   * This is prefixed to avoid collision with standard fields.
+   */
+  ext_device_info?: OpenIdDeviceInfo;
+}
+
+/**
+ * Represents the response payload for a successful Dynamic Client Registration,
+ * based on OpenID Connect Registration 1.0.
+ * This object will be nested inside the `resource` of the final BundleEntry.
+ * @see https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse
+ */
+export interface DcrRegistrationResponse {
+  /**
+   * Unique client identifier.
+   */
+  client_id: string;
+
+  /**
+   * Time at which the client_id was issued, represented as a Unix timestamp.
+   */
+  client_id_issued_at: number;
+  
+  /**
+   * The client secret. For public clients or those using JWTs for client authentication,
+   * this may not be returned.
+   */
+  client_secret?: string;
+  
+  /**
+   * Time at which the client_secret will expire, represented as a Unix timestamp.
+   * If 0, the secret does not expire.
+   */
+  client_secret_expires_at?: number;
+  
+  /**
+   * A registration access token that can be used at the client configuration endpoint
+   * to perform subsequent operations upon the client registration.
+   */
+  registration_access_token?: string;
+
+  /**
+   * URL of the client's configuration endpoint.
+   */
+  registration_client_uri?: string;
+}

package/src/models/operation-outcome.ts

@@ -0,0 +1,34 @@
+// src/models/fhir/operation-outcome.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import { IssueLevel, IssueTypeCode } from './issue';
+
+/**
+ * A single detail associated with an operation, based on a simplified FHIR structure.
+ * Renamed from 'Issue' to be more neutral for potential success reporting.
+ */
+export interface OperationOutcomeDetails {
+  /**
+   * Indicates the severity of the detail.
+   */
+  severity: IssueLevel;
+
+  /**
+   * A code classifying the type of detail.
+   */
+  code: IssueTypeCode;
+
+  /**
+   * Additional diagnostic information, such as a stack trace or detailed error message.
+   */
+  diagnostics?: string;
+}
+
+/**
+ * A structured response detailing the result of an operation, based on a simplified FHIR structure.
+ */
+export interface OperationOutcome {
+  resourceType: 'OperationOutcome';
+  issue: OperationOutcomeDetails[];
+}
+

package/src/models/params.ts

@@ -0,0 +1,142 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/params.ts
+
+/**
+ * Represents a interoperable claim for all specifications.
+ */
+export interface ClaimInteroperable {
+    /**
+     * Key name of the interoperable claim in reverse-DNS (e.g., 'org.hl7.fhir.immunization.vaccine-code').
+     */
+    name: string;
+    /**
+     * The value of the claim. Can be either a string or a number.
+     * Derived interfaces may specify more precise types.
+     */
+    value: any;
+}
+
+/**
+ * Represents a single, named piece of data within an entity's configuration,
+ * aligning with the structure of a Parameter in the FHIR Parameters resource.
+ *
+ * This structure is used to store secondary or multi-value attributes (like
+ * multiple emails or official identifiers) in their original, readable format.
+ * The entire collection of these attributes is considered private and is always
+ * stored within an encrypted parent configuration object.
+ *
+ * @see {@link https://hl7.org/fhir/parameters.html}
+ */
+export interface ParamAttribute extends ClaimInteroperable {
+  /**
+   * The name of the parameter, which often corresponds to a key in the
+   * 'indexed' attributes dictionary of the parent configuration.
+   *
+   * @example 'NNES' (for a Spanish DNI, unique=true)
+   * @example 'email' (unique=falsez)
+   */
+  name: string;
+
+  /**
+   * The original value of the parameter. Can be either a string or a number.
+   * This corresponds to a simplified `value[x]` (e.g., `valueString`) in a FHIR Parameter.
+   */
+  value: string | number | undefined;
+
+  /**
+   * A custom flag to indicate whether this attribute's value is expected to
+   * be unique across all entities of the same type. This is used for
+   * server-side validation logic and is not part of the FHIR standard.
+   * @default false
+   */
+  unique?: boolean;
+}
+
+export type ParameterType = 'number' | 'date' | 'string' | 'token' | 'reference' | 'composite' | 'quantity' | 'uri' | 'period';
+
+/**
+ * Represents a common interface for all types of parameters.
+ */
+export interface ParameterData extends ParamAttribute {
+    /**
+     * Defines the type of parameter.
+     */
+    type: ParameterType | string;
+    /**
+     * (Optional) Coding system (e.g., SNOMED, LOINC...).
+     */
+    system?: string;
+    /**
+     * (Optional) Unit of measurement (e.g., ml, mg...).
+     */
+    unit?: string;
+    /**
+     * (Optional) Indicates if the date is a Period (e.g., FHIR effectivePeriod or FHIR onsetPeriod).
+     */
+    period?: boolean;
+    /**
+     * (Optional) The end date of a FHIR Period.
+     */
+    end?: string;
+    /**
+     * (Optional) Prefix for dates and quantities for comparisons (e.g., eq, gt, lt, ...).
+     */
+    prefix?: string;
+    /**
+     * (Optional) International display derived from a FHIR Coding within a CodeableConcept.
+     */
+    intDisplay?: string;
+    /**
+     * (Optional) Localized text derived from a FHIR CodeableConcept.
+     */
+    localizedText?: string;
+    /**
+     * (Optional) A hint or tooltip to guide users in a UI setting.
+     */
+    hint?: string;
+    /**
+     * (Optional) A list of select options for UI dropdowns or similar components.
+     */
+    optionsList?: any[];
+    /**
+     * (Optional) Resources to which this parameter is applicable.
+     */
+    appliesTo?: string[];
+}
+
+export interface StringSearchParameter extends ParameterData {
+    type: 'string';
+    value: string;
+}
+export interface NumberSearchParameter extends ParameterData {
+    value: number;
+}
+export interface DateSearchParameter extends ParameterData {
+    value: string;
+    end?: string;
+    period?: boolean;
+}
+export interface TokenSearchParameter extends ParameterData {
+    type: 'token';
+    value: string;
+    system: string;
+}
+export interface ReferenceSearchParameter extends ParameterData {
+    type: 'reference';
+    reference: string;
+}
+export interface CompositeSearchParameter extends ParameterData {
+    type: 'composite';
+    components: ParameterData[];
+}
+export interface QuantitySearchParameter extends ParameterData {
+    type: 'quantity';
+    value: number;
+    system: string;
+    unit: string;
+}
+export interface URISearchParameter extends ParameterData {
+    type: 'uri';
+    value: string;
+}
+export type FHIRSearchParameter = NumberSearchParameter | DateSearchParameter | StringSearchParameter | TokenSearchParameter | ReferenceSearchParameter | CompositeSearchParameter | QuantitySearchParameter | URISearchParameter;

package/src/models/resource-document.ts

@@ -0,0 +1,21 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/resource-document.ts
+
+/**
+ * A flexible record type for claims objects.
+ */
+export type ClaimsRecord = Record<string, any>;
+
+// A generic type for records stored in the vault.
+export interface RecordBase {
+  id: string;
+}
+
+/**
+ * Represents the configuration metadata for a vault.
+ * As defined in the original database abstract layer.
+ */
+export interface VaultConfig extends RecordBase{
+    custodian?: string; // The tenant responsible for this vault
+}
+

package/src/models/response.ts

@@ -0,0 +1,5 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/response.ts
+
+// Re-exported for backwards compatibility. The canonical definition lives in `confidential-message.ts`.
+export type { IDecodedDidcommPayload } from './confidential-message';

package/src/models/urlPath.ts

@@ -0,0 +1,76 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/urlPath.ts
+
+/**
+ * Defines the standardized business sectors supported by the gateway.
+ * Using an enum ensures type safety and prevents the use of arbitrary strings.
+ */
+export enum Sector {
+  TEST = 'test', // For mock/demo endpoints and host registry in tests
+  SYSTEM = 'system', // Reserved for the host's bootstrap operation (TODO: deprecate)
+  HEALTH_CARE = 'health-care',
+  HEALTH_INSURANCE = 'health-insurance',
+  EMERGENCY = 'emergency',
+  RESEARCH = 'research',
+}
+
+export enum Section {
+  /** Managing registration of organizations */
+  registry = 'registry',
+  /** Managing data of the hosted organization */
+  entity = 'entity',
+  /** Managing data of the hosted individual */
+  individual = 'individual',
+  /** Managing data in the blockchain network */
+  network = 'network', // generic 'network' for the path, but customized network name can be used
+}
+
+/** Standards, specifications and formats for data supported in the url path */
+export enum Format {
+  Schema = 'org.schema',
+  FhirApi = 'org.hl7.fhir.api',
+  //Pdf' = 'pdf',
+}
+
+/** Types of resources supported in the url path */
+export enum Resource {
+  Person = 'Person',
+  RelatedPerson = 'RelatedPerson',
+  Employee = 'Emloyee',
+  EmployeeRole = 'EmloyeeRole',
+  Practitioner = 'Practitioner',
+  PractitionerRole = 'PractitionerRole',
+  Organization = 'Organization',
+  Location = 'Location',
+  Group = 'Group',
+}
+
+export enum JobAction {
+  "_batch" = "_batch",
+  "_create" = "_create",
+  "_discovery" = "_discovery"
+}
+
+export enum knownDomainsReversedEnum {
+  'org.schema' = 'org.schema',
+  'org.hl7.fhir.api' = 'org.hl7.fhir.api',
+  'org.hl7.fhir.r4' = 'org.hl7.fhir.r4',
+  'org.ilo.isco' = 'org.ilo.isco',
+  'net.openid' = 'net.openid',
+  // Add other known standards here
+};
+
+/**
+ * A list of known, fully-qualified context prefixes in reverse DNS format.
+ * This is used by the claim normalization utility to identify claims that
+ * are already interoperable and should not be modified.
+ * All entries should be in lowercase.
+ */
+export const knownDomainsReversed: string[] = [
+  knownDomainsReversedEnum["org.schema"],
+  knownDomainsReversedEnum["org.hl7.fhir.api"],
+  knownDomainsReversedEnum["org.hl7.fhir.r4"],
+  knownDomainsReversedEnum["org.ilo.isco"],
+  knownDomainsReversedEnum["net.openid"]
+  // Add other known standards here
+];

package/src/models/verifiable-credential.ts

@@ -0,0 +1,52 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/verifiable-credential.ts
+
+import { EvidenceObjectDLT } from "./oidc4ida.evidence.model"
+
+/**
+ * Defines the JSON-LD context URI for W3C Verifiable Credentials Data Model v2.0.
+ * This constant MUST be used for all V2 credential creations to ensure consistency.
+ * @see https://www.w3.org/TR/vc-data-model-2.0/#contexts
+ */
+export const VC_CONTEXT_V2 = 'https://www.w3.org/ns/credentials/v2';
+
+/** ProofEBSIv2 foresees the possibility to use different types of proofs for Verifiable Credentials,
+ *  such as proofs derived from eIDAS keys (qualified) to DID keys (unqualified).
+ *  In EBSI 2.0, every V-ID will only contain a single proof, which must be derived from eIDAS keys.
+ *  Definition: https://www.w3.org/TR/vc-data-model/#proofs-signatures
+ *  See https://ec.europa.eu/digital-building-blocks/wikis/display/EBSIDOC/Verifiable+Attestation
+ *  - 'created' is REQURED, it is the ISO 8601 original timestamp of the signature, it is not the same as credential.issued (tx timestamp) (in Aries go framework use *util.TimeWithTrailingZeroMsec instead of time.Time)
+ *  - 'jws' is REQUIRED, it defines the detached JWS signature string "<base64url(protectedheader)>..<base64url(signature)>"
+ *  - 'proofPurpose' is REQUIRED, e.g.: assertionMethod, authentication, keyAgreement, contractAgreement, capabilityInvocation, capabilityDelegation
+ *  - 'type' is REQUIRED, e.g.: "JsonWebSignature2020", "BbsBlsSignature2020", "BbsBlsSignatureProof2020".
+ *  - 'verificationMethod' is REQUIRED, it is the 'urndid#keyId' to verify the signature by using the issuer's public signature key.
+ */
+ export interface ProofEBSIv2  {
+	created?:               string // ISO 8601 original timestamp of the signature, it is not the same as credential.issued (tx timestamp) (in Aries go framework use *util.TimeWithTrailingZeroMsec instead of time.Time)
+	jws?:                   string // The detached JWS signature string "<base64url(protectedheader)>..<base64url(signature)>"
+	proofPurpose?:          string // assertionMethod, authentication, keyAgreement, contractAgreement, capabilityInvocation, capabilityDelegation
+	type:                  string // "JsonWebSignature2020", "BbsBlsSignature2020", "BbsBlsSignatureProof2020"
+	verificationMethod?:    string // The DID URL of the public key, e.g., "did:web:host.example.com#keyIdThumbprintBase64urlEncoded"
+}
+
+/**
+ * Defines the structure for a W3C Verifiable Credential.
+ * The credentialSubject can be any object containing the claims.
+ * @see https://www.w3.org/TR/vc-data-model-2.0/#verifiable-credentials
+ */
+export interface VerifiableCredentialV2 {
+  '@context': string[];
+  id?: string; // A unique identifier for the credential, e.g. hash result of the credential version (unique URN).
+  type: string[];
+  /** Claims about the subject, such as the "identifier" or subject's URN */
+  credentialSubject: Record<string, any>;
+  /** Evidence for Identity Assurance: https://openid.net/specs/openid-ida-verified-claims-1_0-final.html#section-5.4.4 */
+  evidence?: EvidenceObjectDLT[];
+  /** The issuer is the creator (e.g., "did:web:gateway.example.com"), but could be distinct to the signer of a proof */
+  issuer: string; // The DID of the issuer 
+  /** Proof is optional during creation, but required for a signed VC */
+  proof?: ProofEBSIv2 | ProofEBSIv2[];
+  validFrom: string; // ISO 8601 timestamp, e.g.: 2025-09-29T11:31:00Z
+  validUntil?: string; // ISO 8601 timestamp, e.g.: 2026-09-29T11:30:59Z
+}
+

package/src/types/noble-hashes.d.ts

@@ -0,0 +1,4 @@
+declare module '@noble/hashes/hmac.js';
+declare module '@noble/hashes/sha3.js';
+declare module '@noble/hashes/sha2.js';
+declare module '@noble/hashes/utils.js';

package/src/utils/actor.ts

@@ -0,0 +1,52 @@
+// src/utils/actor.ts
+
+export type ParsedActor = {
+  /**
+   * The token subject / authenticated actor identifier (as provided in the token request).
+   * Examples:
+   * - did:web:api.acme.org:employee:doctor1@acme.org:role:ISCO-08|2211
+   * - doctor1@acme.org
+   */
+  sub: string;
+  /** The employee email if present (either from did:web employee DID or raw email). */
+  email?: string;
+  /** The employee role code if present (e.g. "ISCO-08|2211"). */
+  role?: string;
+  /** The base organization did:web if `sub` is did:web (e.g. "did:web:api.acme.org"). */
+  organization?: string;
+};
+
+export function parseActorFromSub(sub: string): ParsedActor {
+  const trimmed = (sub || '').trim();
+  const parsed: ParsedActor = { sub: trimmed };
+  if (!trimmed) return parsed;
+
+  if (trimmed.startsWith('did:web:')) {
+    // Base org DID is always the first component after did:web:
+    // did:web:<host>[:...]
+    const after = trimmed.replace(/^did:web:/, '');
+    const host = after.split(':')[0];
+    if (host) parsed.organization = `did:web:${host}`;
+
+    // Extract email and role from the canonical employee DID shape:
+    // did:web:<host>:employee:<email>:role:<roleCode>[:device:<uuid>]
+    const parts = after.split(':');
+    const employeeIdx = parts.indexOf('employee');
+    if (employeeIdx >= 0 && parts.length > employeeIdx + 1) {
+      const email = parts[employeeIdx + 1];
+      if (email && email.includes('@')) parsed.email = email.toLowerCase();
+    }
+    const roleIdx = parts.indexOf('role');
+    if (roleIdx >= 0 && parts.length > roleIdx + 1) {
+      parsed.role = parts[roleIdx + 1];
+    }
+    return parsed;
+  }
+
+  // Raw email actor identifier
+  if (trimmed.includes('@') && !/\s/.test(trimmed)) {
+    parsed.email = trimmed.toLowerCase();
+  }
+  return parsed;
+}
+

package/src/utils/base-convert.ts

@@ -0,0 +1,77 @@
+// crypto-ts/utils/base-convert.ts
+
+import {
+    encode as encodeBase64,
+    decode as decodeBase64,
+    decodeURLSafe,
+    encodeURLSafe,
+} from "@stablelib/base64";
+import { alphabetBase58, decodeN, encodeN } from './baseN';
+import { stringToBytesUTF8 } from './string-convert';
+
+/** Converts a Uint8Array to a hexadecimal string. */
+export function bytesToHexString(bytes: Uint8Array): string {
+    return Array.from(bytes, (byte) => {
+        return ('0' + (byte & 0xff).toString(16)).slice(-2);
+    }).join('');
+};
+
+/** Encodes a Uint8Array into a Base58 string. */
+export function bytesToBase58(bytes: Uint8Array): string {
+    return encodeN(bytes, alphabetBase58, undefined);
+}
+
+/** Decodes a Base58 string into a Uint8Array. */
+export function base58ToBytes(base58str: string): Uint8Array {
+    return decodeN(base58str, alphabetBase58);
+}
+
+/** Encodes a string into a standard Base64 string (with padding). */
+export function stringToStdBase64(str: string): string {
+    const dataBytes: Uint8Array = stringToBytesUTF8(str);
+    return encodeBase64(dataBytes);
+}
+
+/** Converts a standard Base64 string to a Base64URL string. */
+export function base64ToBase64Url(encodedData: string): string {
+    if (encodedData && (encodedData.indexOf("+") !== -1 || encodedData.indexOf("/") !== -1)) {
+        return encodedData.split("+").join("-").split("/").join("_");
+    } else {
+        return encodedData;
+    }
+}
+
+/** Encodes a string into a Base64URL string. */
+export function stringToBase64Url(stringifiedData: string): string {
+    const encodedData = stringToStdBase64(stringifiedData);
+    return base64ToBase64Url(encodedData);
+}
+
+/** Converts a Base64URL string to a standard Base64 string. */
+export function base64UrlToBase64(encodedData: string): string {
+    if (encodedData && (encodedData.indexOf("-") !== -1 || encodedData.indexOf("_") !== -1)) {
+        return encodedData.split("-").join("+").split("_").join("/");
+    } else {
+        return encodedData;
+    }
+}
+
+/** Decodes a string that is either Base64 or Base64URL into a Uint8Array. */
+export function base64OrUrlSafeToBytes(base64OrUrlSafe: string): Uint8Array {
+    if (String(base64OrUrlSafe).includes("+") || String(base64OrUrlSafe).includes("/")) {
+        return  new Uint8Array(decodeBase64(base64OrUrlSafe));
+    } else {
+        return new Uint8Array(decodeURLSafe(base64OrUrlSafe));
+    }
+}
+
+/** Encodes a Uint8Array into a standard Base64 string (with padding). */
+export function bytesToBase64(bytes: Uint8Array): string {
+    return encodeBase64(bytes);
+}
+
+/** Encodes a Uint8Array into a raw Base64URL string (no padding). */
+export function bytesToRawBase64UrlSafe(bytes: Uint8Array): string {
+    return encodeURLSafe(bytes).replace(/=/g, "");
+}
+