gdc-common-utils-ts 1.0.1

package/src/models/consent-rule.ts

@@ -0,0 +1,141 @@
+// src/models/consent-rule.ts
+
+export enum ClaimConsent {
+    'decision' = 'Consent.decision',
+    'action' = 'Consent.action',
+    'category' = 'Consent.category',
+    'subject' = 'Consent.subject',
+    'actorIdentifier' = 'Consent.actor-identifier',
+    'actorRole' = 'Consent.actor-role',
+    'date' = 'Consent.date',
+    'periodStart' = 'Consent.period-start',
+    'periodEnd' = 'Consent.period-end',
+    'grantee' = 'Consent.grantee',
+    'verifiedBy' = 'Consent.verified-by',
+    'verifiedDate' = 'Consent.verified-date',
+    'purpose' = 'Consent.purpose',
+    'identifier' = 'Consent.identifier',
+    'attachmentContentType' = 'Consent.attachment-contentType',
+    'attachmentData' = 'Consent.attachment-data',
+    'attachmentId' = 'Consent.attachment-id',
+}
+
+/**
+ * Defines the structured, query-optimized format for storing a single, atomic consent rule
+ * in the vault (e.g., Firestore, CouchDB).
+ *
+ * This object is the "Query" model in a CQRS (Command Query Responsibility Segregation) pattern.
+ * It is generated by the `ConsentManager` from the "Command" - a set of interoperable claims
+ * provided in the `meta.claims` block of an incoming FHIR Consent resource.
+ *
+ * The backend's authorization engine queries against collections of these objects for high-speed
+ * access decisions. The original FHIR Consent resource may be stored separately for auditing.
+ *
+ * All fields are derived from claims using the reverse-DNS format, e.g., the `decision` field
+ * is populated from the `org.hl7.fhir.api.Consent.decision` claim.
+ */
+export interface ConsentRule {
+    /**
+     * JSON-LD context to define the vocabulary for the rule.
+     * Value MUST be "org.hl7.fhir.api".
+     */
+    '@context': 'org.hl7.fhir.api';
+
+    /**
+     * The decision of the rule: permit or deny.
+     * Derived from the `org.hl7.fhir.api.Consent.decision` claim.
+     */
+    'Consent.decision': 'permit' | 'deny';
+
+    /**
+     * The data sections this rule applies to, as a comma-separated list of coded values.
+     * Derived from the `org.hl7.fhir.api.Consent.action` claim.
+     * Example claim: "LOINC|48765-2,SNOMED|12345"
+     */
+    'Consent.action': string;
+
+    /**
+     * The type of consent document, as a comma-serpareted list of coded values.
+     * Used for classifying the consent itself (e.g., for release of information).
+     * Derived from the `org.hl7.fhir.api.Consent.category` claim.
+     * Example claim: "LOINC|59284-0,LOINC|57016-8"
+     */
+    'Consent.category'?: string;
+
+    /**
+     * The subject of the consent.
+     * Derived from the `org.hl7.fhir.api.Consent.patient.identifier` claim.
+     */
+    'Consent.subject': string;
+
+    /**
+     * The identifier of the actor (jurisdiction, organization, professional) this rule applies to.
+     * This is the party whose access is being controlled.
+     * Derived from a claim like `org.hl7.fhir.api.Consent.actor.reference.identifier`.
+     * e.g., "urn:iso:3166-2:ES-CT", "did:web:hospital.example.com", "urn:email:dr-smith@example.com"
+     */
+    'Consent.actor-identifier': string;
+
+    /**
+     * The role of the actor this rule applies to.
+     * Derived from a claim like `org.hl7.fhir.api.Consent.actor.role`.
+     * e.g., "doctor", "nurse"
+     */
+    'Consent.actor-role': string;
+
+    /**
+     * The date the consent was granted (ISO 8601 Date).
+     * Derived from the `org.hl7.fhir.api.Consent.date` claim.
+     */
+    'Consent.date': string;
+
+    /**
+     * Start of the consent's validity period (ISO 8601 DateTime).
+     * Note: This is different from the date the consent was signed.
+     * Derived from the start of the `org.hl7.fhir.api.Consent.period` claim.
+     */
+    'Consent.period-start'?: string;
+
+    /**
+     * End of the consent's validity period (ISO 8601 DateTime).
+     * Derived from the end of the `org.hl7.fhir.api.Consent.period` claim.
+     */
+    'Consent.period-end'?: string;
+
+    /**
+     * The party to whom the consent is granted.
+     * Use both 'Consent.actor-identifier' and 'Consent.actor-role' instead.
+     * Derived from the `org.hl7.fhir.api.Consent.grantee` claim.
+     */
+    // 'Consent.grantee': string;
+
+    /**
+     * The DID of the entity (person or system) that verified the consent.
+     * Derived from the `org.hl7.fhir.api.Consent.verified-by` claim.
+     */
+    'Consent.verified-by'?: string;
+
+    /**
+     * The date the consent was verified (ISO 8601 DateTime).
+     * Derived from the `org.hl7.fhir.api.Consent.verified-date` claim.
+     */
+    'Consent.verified-date'?: string;
+
+
+    /**
+     * The purpose of use for this rule.
+     * Derived from the `org.hl7.fhir.api.Consent.purpose` claim.
+     * e.g., "ETREAT", "CAREMGT"
+     */
+    'Consent.purpose': string;
+
+    /**
+     * The original Consent resource ID for auditing.
+     * Derived from the `org.hl7.fhir.api.Consent.identifier` claim.
+     */
+    'Consent.identifier': string;
+
+    'Consent.attachment-contentType'?: string
+    'Consent.attachment-data'?: string
+    'Consent.attachment-id'?: string
+}

package/src/models/crypto.ts

@@ -0,0 +1,43 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/crypto.ts
+
+import { PublicJwk } from "../interfaces/Cryptography.types";
+
+/**
+ * Describes a public key and its controller, for use in JWE recipients or DID documents.
+ * @see https://w3c-ccg.github.io/ld-cryptosuite-registry/
+ */
+export interface RecipientPublicKey {
+    type: string; // "JsonWebKey2020";
+    controller?: string; // DID of the key controller
+    publicKeyJwk: PublicJwk;
+    nbf?: number; // Not Before timestamp
+    exp?: number; // Expiration timestamp
+}
+
+/**
+ * Represents a full cryptographic key pair, including the private key material.
+ * This format is for internal use by the KMS and should never be exposed.
+ */
+export interface KeyPair extends RecipientPublicKey {
+    /** The raw private key bytes. This MUST be protected at rest (encrypted). */
+    privateKeyBytes: Uint8Array;
+}
+
+/**
+
+ * Contains all cryptographic material for a single tenant, managed by the Gateway Service.
+ * This object is what would be encrypted and stored in a tenant's vault.
+ */
+export interface TenantCryptoData {
+    /** A cache of public keys of recipients this tenant frequently interacts with. */
+    recipients: RecipientPublicKey[];
+    /** A protected PIN/Password used to derive a key for local cryptographic operations. */
+    passKey: Uint8Array; 
+    /** The history of encryption key pairs used by the tenant (for key rotation). The last one is the current key. */
+    keyAgreement: KeyPair[];
+    /** The history of signature key pairs used by the tenant (for key rotation). The last one is the current key. */
+    verificationMethod: KeyPair[];
+}
+
+

package/src/models/device-license.ts

@@ -0,0 +1,161 @@
+// src/models/device-license.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+/**
+ * A fingerprint of a specific device, used for binding a license to it.
+ */
+export interface DeviceInfo {
+  /**
+   * A stable, unique identifier for the specific app installation, generated by the client.
+   * This is the primary key for device binding.
+   */
+  clientInstanceId: string;
+
+  /** The operating system of the device (e.g., "iOS", "Android", "Windows"). */
+  os?: string;
+
+  /** The specific OS version. */
+  osVersion?: string;
+
+  /** The manufacturer of the device (e.g., "Apple", "Samsung"). */
+  manufacturer?: string;
+  
+  /** The model of the device (e.g., "iPhone14,6"). */
+  model?: string;
+}
+
+/**
+ * A set of rules that a device must match to be eligible to activate a license.
+ */
+export interface DeviceRestrictions {
+  /** A regex pattern for the allowed manufacturer(s). */
+  manufacturer?: string;
+
+  /** A regex pattern for the allowed model(s). */
+  model?: string;
+}
+
+/**
+ * Represents a single device activation license, enabling a user to register a specific device
+ * for a tenant's service. It governs access based on user class, platform, and subscription terms.
+ * Timestamps are stored as Unix epoch seconds (numeric).
+ * All property names follow the camelCase convention.
+ */
+export interface DeviceLicense {
+  /**
+   * The unique identifier for this license document in the vault.
+   */
+  id: string;
+
+  /**
+   * The logical identifier of the tenant organization that owns this license.
+   * @example "acme"
+   */
+  tenantId: string;
+  
+  /**
+   * Identifier for the purchase order or invoice that generated this license.
+   * All licenses created from the same purchase will share the same orderId.
+   * @example "inv_12345"
+   */
+  orderId: string;
+
+  /**
+   * A secure, single-use code given to a user to activate a device.
+   * This is generated when the license status becomes 'issued'.
+   */
+  activationCode?: string;
+
+  /**
+   * **CRITICAL:** Defines the class of user this license is intended for.
+   * This allows for stratified licensing (e.g., selling "professional seats"
+   * separately from "individual access").
+   */
+  userClass: 'employee' | 'individual';
+
+  /**
+   * **Specifies the functional category for an 'employee' license.**
+   * This determines the set of roles the user is permitted to have.
+   * This field MUST be present if userClass is 'employee'.
+   * It is typically undefined for 'individual' licenses.
+   * @example "medicalStaff", "firstResponder", "admin"
+   */
+  userCategory?: string;
+
+
+  /**
+   * Defines the platform this license is for.
+   */
+  type: 'mobile' | 'web';
+
+  /**
+   * The current lifecycle status of the license.
+   * - 'available': Fresh license, ready to be assigned to a user.
+   * - 'issued': Assigned to a user and an activation code has been generated.
+   * - 'active': The user has successfully used the activation code to register a device.
+   * - 'inactive': Deactivated by an administrator or user, or has expired.
+   */
+  status: 'available' | 'issued' | 'active' | 'inactive';
+
+  /**
+   * The subscription or purchase plan associated with this license.
+   * @example "premium_annual" | "standard_monthly" | "trial"
+   */
+  plan: string;
+
+  /**
+   * Defines the renewal period for the license.
+   * '1m' for one month, '12m' for one year.
+   * A null value indicates the license does not auto-renew.
+   */
+  renewalCycle: '1m' | '12m' | null;
+  
+  /**
+   * If true, the license can be reactivated after being made inactive
+   * (e.g., after a user clicks "Log out everywhere"). If false, an inactive
+   * license cannot be used again.
+   */
+  reactivationEnabled: boolean;
+
+  /**
+   * "Issued At" timestamp. The time the license was assigned to a user, as a Unix epoch in seconds.
+   * Set when status moves to 'issued'.
+   */
+  issuedAt?: number;
+  
+  /**
+   * "Activation Time" timestamp. The time the license was successfully used to register a device,
+   * as a Unix epoch in seconds. Set when status moves to 'active'.
+   */
+  activatedAt?: number;
+
+  /**
+   * "Expiration Time" timestamp. The time at which the license and the device's authorization
+   * expire, as a Unix epoch in seconds.
+   */
+  exp: number;
+
+  /**
+   * The unique identifier of the user (e.g., employeeId or customerId) to whom the license is issued.
+   * Populated when the status becomes 'issued'.
+   */
+  subjectId?: string;
+  
+  /**
+   * The unique identifier (`client_id`) of the device registered with this license.
+   * Populated when the status becomes 'active'.
+   */
+  deviceId?: string;
+
+  /**
+   * Optional, pre-defined restrictions on which devices are allowed to activate this license.
+   * Set at the time of license creation.
+   */
+  deviceRestrictions?: DeviceRestrictions;
+
+  /**
+   * A fingerprint of the device that successfully activated this license.
+   * This is captured upon activation and is used to lock the license to that specific device.
+   */
+  deviceInfo?: DeviceInfo;
+}

package/src/models/did.ts

@@ -0,0 +1,81 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/did.ts
+
+import { PublicJwk } from "../interfaces/Cryptography.types";
+import { RecipientPublicKey } from "./crypto";
+
+/**
+ * The parameters required to construct a service endpoint selector.
+ * This is the contract for a specific API method to define its endpoint.
+ */
+export interface ServiceEndpointSelector {
+  /** When the organization has its own domain for the connector the apiVersion and sector do not appear in the path */
+  apiVersion?: string;
+  sector?: string;
+  /** Corresponds to <sectionTypeOrCompartmentCodingSystem> */
+  section: string; // entity, individual, ...
+  /** Corresponds to <formatTypeOrCompartmentCodingValue> */
+  format: string;
+  resourceType: string;
+  action: string;
+}
+
+/**
+ * Extends the base selector with authorization information.
+ * This is used for endpoints that are not public and require a SMART token.
+ */
+export interface SecureServiceEndpointSelector extends ServiceEndpointSelector {
+  requiredScope: string; // The OAuth/SMART scope needed to call this endpoint
+}
+
+/**
+ * Represents a service endpoint in a DID Document.
+ * @see https://www.w3.org/TR/did-core/#service-endpoints
+ */
+export interface DidService {
+    id: string;
+    type: string;
+    serviceEndpoint: string;
+    [key: string]: any; // Allow for additional properties
+}
+
+/**
+ * Represents a DID Document, compliant with the W3C DID Core specification.
+ * It describes how to use a DID, including verification methods and service endpoints.
+ * @see https://www.w3.org/TR/did-core/
+ */
+export interface DidDocument {
+    /** The DID context, typically "https://www.w3.org/ns/did/v1". */
+    '@context': string | string[];
+    /** The DID URI itself. */
+    id: string;
+    /** Public keys used for verifying digital signatures */
+    verificationMethod?: VerificationMethod[];
+    /** 
+     * Specifies verification methods for making claims. Can be embedded or a string referencing a `verificationMethod`.
+     * @see https://www.w3.org/TR/did-core/#assertion
+     */
+    assertionMethod?: (string | VerificationMethod)[]; 
+    /** 
+     * Specifies methods for authentication. Can be embedded or a string referencing a `verificationMethod`.
+     * @see https://www.w3.org/TR/did-core/#authentication
+     */
+    authentication?: (string | VerificationMethod)[]; 
+    /** 
+     * Specifies methods for key agreement. Can be embedded or a string referencing a `verificationMethod`.
+     * @see https://www.w3.org/TR/did-core/#key-agreement
+     */
+    keyAgreement?: (string | VerificationMethod)[];
+    /** Service endpoints for interacting with the entity */    
+    service?: DidService[];
+    /** Other properties are allowed. */
+    [key: string]: any;
+}
+
+// En src/models/did.ts (o donde esté RecipientPublicKey/VerificationMethod)
+export interface VerificationMethod extends RecipientPublicKey {
+  id: string; // e.g., did:web:example.com#key-1
+  type: string; // e.g., JsonWebKey2020
+  controller: string; // e.g., did:web:example.com
+  publicKeyJwk: PublicJwk;
+}

package/src/models/index.ts

@@ -0,0 +1,31 @@
+export * from './aes';
+export * from './auth';
+export * from './bundle';
+export * from './comm';
+export * from './clinical-sections';
+export * from './clinical-sections.en';
+export * from './confidential-job';
+export * from './confidential-message';
+export * from './confidential-storage';
+export * from './consent-rule';
+export * from './crypto';
+export * from './device-license';
+export * from './did';
+export * from './indexing';
+export * from './issue';
+export * from './jsonapi';
+export * from './jwe';
+export * from './jwk';
+export * from './jws';
+export * from './jwt';
+export * from './oidc4ida.common.model';
+export * from './oidc4ida.document.model';
+export * from './oidc4ida.electronicRecord.model';
+export * from './oidc4ida.evidence.model';
+export * from './openid-device';
+export * from './operation-outcome';
+export * from './params';
+export * from './resource-document';
+export * from './response';
+export * from './urlPath';
+export * from './verifiable-credential';

package/src/models/indexing.ts

@@ -0,0 +1,20 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: src/models/indexing.ts
+
+import { ClaimsOrganizationSchemaorg } from "../constants/schemaorg";
+
+/**
+ * Defines which claims are allowed to be indexed for different resource types.
+ * This provides a single, strongly-typed source of truth for indexing strategies.
+ */
+export const AllowedIndexableClaims = {
+  /**
+   * Defines the claims that can be indexed in the central tenant registry for an Organization.
+   */
+  organizationRegistry: [
+    ClaimsOrganizationSchemaorg.alternateName,
+    ClaimsOrganizationSchemaorg.identifierValue,
+    ClaimsOrganizationSchemaorg.identifierType,
+    ClaimsOrganizationSchemaorg.addressCountry,
+  ] as const, // Use 'as const' to provide strong typing for the array elements
+};

package/src/models/issue.ts

@@ -0,0 +1,85 @@
+// src/models/issue.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// Source: https://www.hl7.org/fhir/valueset-issue-severity.html
+
+/**
+ * Defines the level of an issue.
+ */
+export enum IssueLevel {
+  /** The issue is fatal and the system is in an unstable state. */
+  Fatal = 'fatal',
+  /** The issue is an error that prevents the action from completing. */
+  Error = 'error',
+  /** The issue is a warning that does not prevent the action from completing. */
+  Warning = 'warning',
+  /** The issue is informational and requires no action. */
+  Information = 'information',
+}
+
+// Source: https://www.hl7.org/fhir/valueset-issue-type.html
+/**
+ * Defines the code for the type of issue.
+ * This is a subset of the full FHIR value set, focused on common API scenarios.
+ */
+export const IssueType = {
+  // --- Category: Invalid Content ---
+  /** Content invalid against the specification. */
+  Invalid: 'invalid',
+  /** A required element is missing. */
+  Required: 'required',
+  /** An element value is invalid. */
+  Value: 'value',
+  /** A business rule has been violated. */
+  BusinessRule: 'business-rule',
+
+  // --- Category: Security ---
+  /** An authentication/authorization error has occurred. */
+  Login: 'login',
+  /** The user is not authorized for the requested action. */
+  Forbidden: 'forbidden',
+  /** A security-related issue has been detected. */
+  Security: 'security',
+
+  // --- Category: Processing ---
+  /** The resource was not found. */
+  NotFound: 'not-found',
+  /** The operation led to a conflict. */
+  Conflict: 'conflict',
+  /** A duplicate record was detected. */
+  Duplicate: 'duplicate',
+  /** The operation is not supported. */
+  NotSupported: 'not-supported',
+  /** An internal processing exception occurred. */
+  Exception: 'exception',
+  /** The operation has timed out. */
+  Timeout: 'timeout',
+  /** The operation was throttled. */
+  Throttled: 'throttled',
+} as const;
+
+/**
+ * A union type derived from the keys of the IssueType object.
+ * This ensures that only defined issue type codes can be used.
+ */
+export type IssueTypeCode = typeof IssueType[keyof typeof IssueType];
+
+/**
+ * Maps our internal IssueType codes to the appropriate HTTP status code strings.
+ * This provides a single source of truth for error responses.
+ */
+export const IssueTypeToHttpStatus: Record<IssueTypeCode, string> = {
+  [IssueType.Invalid]: '400',
+  [IssueType.Required]: '400',
+  [IssueType.Value]: '400',
+  [IssueType.BusinessRule]: '400',
+  [IssueType.Login]: '401',
+  [IssueType.Forbidden]: '403',
+  [IssueType.Security]: '403',
+  [IssueType.NotFound]: '404',
+  [IssueType.Conflict]: '409',
+  [IssueType.Duplicate]: '409',
+  [IssueType.NotSupported]: '501',
+  [IssueType.Exception]: '500',
+  [IssueType.Timeout]: '503',
+  [IssueType.Throttled]: '429',
+};

package/src/models/jsonapi.ts

@@ -0,0 +1,19 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: src/models/jsonapi.ts
+
+import { RecordBase } from "./resource-document";
+
+/**
+ * Represents a resource object in a JSON:API 'included' array.
+ * The type is made "open" with an index signature to allow for additional properties.
+ */
+export interface IncludedResource extends RecordBase {
+  // 'id' is inherited from RecordBase
+  type: string;
+  meta: {
+    claims: Record<string, any>; // The worker will create always claims (even if empty)
+    [key: string]: any; // Make meta open
+  };
+  [key: string]: any; // Make the top-level resource open
+}
+