gdc-common-utils-ts 1.0.4 → 1.0.7

package/dist/models/confidential-message.d.ts

@@ -0,0 +1,97 @@
+import { ProtectedHeadersJWE } from "./jwe";
+import { JwsHeader } from "./jws";
+export type { DataEntry } from "./comm";
+/**
+ * Defines the structure of the cryptographic metadata associated with a job request.
+ */
+export interface DidCommDecodedMetadata {
+    jws?: {
+        protected?: JwsHeader;
+        /** Detached signature of the request JWS (when available). */
+        signature?: string;
+    };
+    jwe?: {
+        header?: ProtectedHeadersJWE;
+    };
+    bearer?: {
+        compact?: string;
+        jwt: {
+            header?: JwsHeader;
+            payload?: Record<string, any>;
+        };
+    };
+}
+/**
+ * Represents the standard payload of a DIDComm v2 message.
+ * @see https://identity.foundation/didcomm-messaging/spec/v2.0/#plaintext-message-structure
+ */
+/**
+ * Represents the plaintext of a decoded DIDComm message.
+ * This is the core business-level "input" for a job.
+ * For FAPI compliance, this entire object is typically the payload of a signed JWS.
+ */
+export interface IDecodedDidcommPayload {
+    /** Relevant information available through the decryption and verification process */
+    meta?: DidCommDecodedMetadata;
+    /**
+     * (Issuer) The DID of the entity that issued the message.
+     * REQUIRED for FAPI. MUST match the signer of the enclosing JWS.
+     */
+    iss: string;
+    /**
+     * (Audience) The URL of the backend endpoint that will process this message.
+     * REQUIRED for FAPI. The backend MUST validate that this value matches its own URL.
+     */
+    aud: string;
+    /** (Expiration Time) Timestamp after which the message is considered invalid. REQUIRED for FAPI (instead of expires_time). */
+    exp?: number;
+    /** (Not Before) Timestamp before which the message must not be processed. REQUIRED for FAPI (instead of created_time). */
+    nbf?: number;
+    /** (Issued At) Timestamp when the message was issued. REQUIRED for FAPI. */
+    iat?: number;
+    /**
+     * (JWT ID) A unique identifier for this message/token. Can be used to prevent replay attacks.
+     * In our architecture, this can also serve as the version hash of the data content.
+     */
+    jti: string;
+    /** Optional. The `jti` identifies both the message and job for processing */
+    id?: string;
+    /** The Transaction ID / Thread ID for message correlation across an interaction. */
+    thid: string;
+    /**  Parent Thread ID */
+    pthid?: string;
+    /** The DID of the intended recipient. Used for P2P messaging, informational in client-server requests. */
+    to?: string[];
+    /** The DID of the sender. Used for P2P messaging, but `iss` is the authoritative value for FAPI. */
+    from?: string;
+    /**
+     * The Message Type URI, identifying the type of data in the body or protocol used.
+     * (e.g. 'application/json')
+    */
+    type: string;
+    /** The main business payload of the message. The structure is defined by the 'type' protocol. */
+    body: any;
+}
+/**
+ * Represents a data entry in the `body` of a CommMsgExtended,
+ * following a hybrid JSON:API and FHIR structure.
+ */
+export interface CommDataEntry {
+    id: string;
+    type: 'Annotation' | 'Reference' | 'Attachment' | 'CodeableConcept' | string;
+    resource: {
+        [key: string]: any;
+    };
+    meta?: {
+        claims: any;
+    };
+}
+/**
+ * The canonical, internal representation of a secure message, extending
+ * the standard DIDComm payload with FHIR-specific, flattened metadata.
+ */
+export interface ICommPayloadExtended extends IDecodedDidcommPayload {
+    body: {
+        data: CommDataEntry[];
+    };
+}

package/dist/models/confidential-message.js

@@ -0,0 +1,4 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/confidential-message.ts
+// Description: Defines the core communication and data structures based on DIDComm and FHIR.
+export {};

package/{src/models/confidential-storage.ts → dist/models/confidential-storage.d.ts}

@@ -1,35 +1,29 @@
-// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
-// File: gdc-common-utils-ts/src/models/confidential-storage.ts
-
 import { ParameterType } from './params';
-
 /**
  * FHIR `Coding`-like tag used for research/analytics metadata.
  * Keep values coarse and coded; avoid free text in `display` unless explicitly policy-approved.
  */
 export interface MetaTagCoding {
-  system?: string;
-  code?: string;
-  version?: string;
-  display?: string;
-  userSelected?: boolean;
+    system?: string;
+    code?: string;
+    version?: string;
+    display?: string;
+    userSelected?: boolean;
 }
-
 /**
  * Research/analytics metadata kept outside encrypted `content`.
  * Policy-dependent: treat these fields as potentially sensitive.
  */
 export interface ResearchInfo {
-  /** Coarse jurisdiction identifier (e.g., "cds-es" or "ES"). */
-  jurisdiction?: string;
-  /** Year of birth (YYYY). */
-  yearOfBirth?: string;
-  /** Gender identity (user-identified). Keep coded and coarse. */
-  gender?: string;
-  /** Sex assigned at birth (if collected). Keep coded and coarse. */
-  sexAtBirth?: string;
+    /** Coarse jurisdiction identifier (e.g., "cds-es" or "ES"). */
+    jurisdiction?: string;
+    /** Year of birth (YYYY). */
+    yearOfBirth?: string;
+    /** Gender identity (user-identified). Keep coded and coarse. */
+    gender?: string;
+    /** Sex assigned at birth (if collected). Keep coded and coarse. */
+    sexAtBirth?: string;
 }
-
 /**
  * Audit metadata for traceability.
  *
@@ -39,37 +33,35 @@ export interface ResearchInfo {
  * - any `meta` object inside encrypted `content` (e.g., entry `meta.claims`)
  */
 export interface AuditInfo {
-  /** When the document was first created off-ledger (ISO 8601). */
-  created?: string;
-  /** When the document was last updated off-ledger (ISO 8601). */
-  updated?: string;
-  /** True if removed/deactivated (deactivation time is typically `updated`). */
-  deactivated?: boolean;
-  /** Name of the channel/network where the data is audited/anchored. */
-  channel?: string;
-  /** Base58/Base64Url transaction identifier, depending on the attestation layer. */
-  txId?: string;
-  /** Transaction timestamp (ISO 8601). */
-  txTime?: string;
+    /** When the document was first created off-ledger (ISO 8601). */
+    created?: string;
+    /** When the document was last updated off-ledger (ISO 8601). */
+    updated?: string;
+    /** True if removed/deactivated (deactivation time is typically `updated`). */
+    deactivated?: boolean;
+    /** Name of the channel/network where the data is audited/anchored. */
+    channel?: string;
+    /** Base58/Base64Url transaction identifier, depending on the attestation layer. */
+    txId?: string;
+    /** Transaction timestamp (ISO 8601). */
+    txTime?: string;
 }
-
 /**
  * Defines the structure of an attribute to be indexed for blind, searchable queries.
  * @see https://identity.foundation/confidential-storage/#indexed-attributes
  */
 export interface IndexedAttribute {
-  name: string;
-  value: string;
-  unique?: boolean;
-  /**
-   * The original data type of the `value` before it was converted to a string
-   * for HMAC protection. This is essential for performing type-aware queries
-   * (e.g., numerical range queries) on the indexed data.
-   * If not present, the type is assumed to be 'string'.
-   */
-  type?: ParameterType | string;
+    name: string;
+    value: string;
+    unique?: boolean;
+    /**
+     * The original data type of the `value` before it was converted to a string
+     * for HMAC protection. This is essential for performing type-aware queries
+     * (e.g., numerical range queries) on the indexed data.
+     * If not present, the type is assumed to be 'string'.
+     */
+    type?: ParameterType | string;
 }
-
 /**
  * Defines an indexed portion of a confidential document, allowing specific attributes to be searchable.
  */
@@ -81,14 +73,12 @@ export interface IndexedData {
     };
     sequence?: number;
 }
-
 /**
  * Represents a complete Structured Document as defined by the Confidential Storage specification.
  * This is the canonical format for all documents persisted in a vault.
  * @see https://identity.foundation/confidential-storage/#structureddocument
  */
 export interface ConfidentialStorageDoc {
-    // 'id' is inherited from RecordBase
     id: string;
     status: string;
     /**
@@ -102,46 +92,36 @@ export interface ConfidentialStorageDoc {
     versionId?: string;
     vaultId?: string;
     chunks?: number;
-
     /** A number that MUST be incremented each time the document is updated. */
     sequence: number;
-
     /** Contains an array of indexed attributes protected with HMAC for blind queries. */
     indexed?: IndexedData;
-    
     /** The main, potentially encrypted, content of the document. */
     content?: Record<string, any>;
-
     /** The JWE representation of the encrypted content. It could be a URL in case of a bucket is used to store the JWE or chunks */
     jwe?: Record<string, any>;
-
     /**
      * Document-level created timestamp (outside encrypted `content`).
      * This is distinct from any `meta` objects inside `content` (e.g., entry meta.claims).
      */
     audit?: AuditInfo;
-
     /**
      * @deprecated Use `audit.created` instead.
      */
     created?: string;
-
     /**
      * Document-level content type label (outside encrypted `content`).
      * This is distinct from any `contentType` claims inside `content`.
      */
     contentType?: string;
-
     /**
      * Optional research/routing tags kept outside encrypted `content`.
      * These tags are intended for analytics/routing and may be mirrored back to API responses.
      * Avoid free text in `display` unless explicitly policy-approved.
      */
     tag?: MetaTagCoding[];
-
     /** Policy-dependent research/analytics metadata, kept outside encrypted `content`. */
     research?: ResearchInfo;
-
     /**
      * @deprecated Use `created`, `contentType`, and `research` instead.
      * This legacy field is kept for backwards compatibility with older stored documents.
@@ -158,7 +138,6 @@ export interface ConfidentialStorageDoc {
         tags?: string;
     };
 }
-
 /**
  * Represents a document whose sensitive content has been decrypted and is held
  * in memory. The `jwe` property is removed, and the `content` is guaranteed to exist.

package/dist/models/confidential-storage.js

@@ -0,0 +1,3 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: gdc-common-utils-ts/src/models/confidential-storage.ts
+export {};

package/{src/models/consent-rule.ts → dist/models/consent-rule.d.ts}

@@ -1,25 +1,22 @@
-// 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',
+export declare 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).
@@ -40,20 +37,17 @@ export interface ConsentRule {
      * 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).
@@ -61,13 +55,11 @@ export interface ConsentRule {
      * 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.
@@ -75,67 +67,55 @@ export interface ConsentRule {
      * 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
-}
+    'Consent.attachment-contentType'?: string;
+    'Consent.attachment-data'?: string;
+    'Consent.attachment-id'?: string;
+}

package/dist/models/consent-rule.js

@@ -0,0 +1,21 @@
+// src/models/consent-rule.ts
+export var ClaimConsent;
+(function (ClaimConsent) {
+    ClaimConsent["decision"] = "Consent.decision";
+    ClaimConsent["action"] = "Consent.action";
+    ClaimConsent["category"] = "Consent.category";
+    ClaimConsent["subject"] = "Consent.subject";
+    ClaimConsent["actorIdentifier"] = "Consent.actor-identifier";
+    ClaimConsent["actorRole"] = "Consent.actor-role";
+    ClaimConsent["date"] = "Consent.date";
+    ClaimConsent["periodStart"] = "Consent.period-start";
+    ClaimConsent["periodEnd"] = "Consent.period-end";
+    ClaimConsent["grantee"] = "Consent.grantee";
+    ClaimConsent["verifiedBy"] = "Consent.verified-by";
+    ClaimConsent["verifiedDate"] = "Consent.verified-date";
+    ClaimConsent["purpose"] = "Consent.purpose";
+    ClaimConsent["identifier"] = "Consent.identifier";
+    ClaimConsent["attachmentContentType"] = "Consent.attachment-contentType";
+    ClaimConsent["attachmentData"] = "Consent.attachment-data";
+    ClaimConsent["attachmentId"] = "Consent.attachment-id";
+})(ClaimConsent || (ClaimConsent = {}));

package/{src/models/crypto.ts → dist/models/crypto.d.ts}

@@ -1,20 +1,15 @@
-// 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
+    type: string;
+    controller?: string;
     publicKeyJwk: PublicJwk;
-    nbf?: number; // Not Before timestamp
-    exp?: number; // Expiration timestamp
+    nbf?: number;
+    exp?: number;
 }
-
 /**
  * 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.
@@ -23,7 +18,6 @@ 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.
@@ -33,11 +27,9 @@ 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; 
+    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/dist/models/crypto.js

@@ -0,0 +1,3 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/crypto.ts
+export {};

package/dist/models/device-license.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 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/dist/models/device-license.js

@@ -0,0 +1,3 @@
+// src/models/device-license.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+export {};