gdc-common-utils-ts 1.0.1

package/src/interfaces/ICryptography.ts

@@ -0,0 +1,177 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/interfaces/ICryptography.ts
+
+import { JweObject } from '../models/jwe';
+import { ProtectedDataAES } from '../models/aes';
+import { MlkemPublicJwk, MldsaPublicJwk, PublicJwk, MlkemPrivateJwk, MldsaAlg, MlkemCurve } from './Cryptography.types';
+import { DataCompactJWT, JwtCompactParts } from '../models/jwt';
+
+/**
+ * Defines the class for the low-level, stateless cryptography utility (the "Engine").
+ */
+export interface ICryptography {
+
+  // --- Key Generation ---
+  /**
+   * Generates a ML-KEM (Kyber) key pair.
+   * @param seedBytes Optional 64-byte seed for deterministic key generation.
+   * @param crv The desired security level. Defaults to 'ML-KEM-768'.
+   */
+  generateKeyPairMlKem(seedBytes?: Uint8Array, crv?: MlkemCurve): Promise<{ publicJWKey: MlkemPublicJwk & { kid: string }; secretKeyBytes: Uint8Array }>;
+  
+  /**
+   * Generates a ML-DSA (Dilithium) key pair.
+   * @param seedBytes Optional 32-byte seed for deterministic key generation.
+   * @param alg The desired security level. Defaults to 'ML-DSA-44'.
+   */
+  generateKeyPairMlDsa(seedBytes?: Uint8Array, alg?: MldsaAlg): Promise<{ publicJWKey: MldsaPublicJwk & { kid: string }; secretKeyBytes: Uint8Array }>;
+
+  // --- Low-Level Primitives (Symmetric AES) ---
+  /**
+   * Encrypts a plaintext string using AES-GCM (a symmetric algorithm) and returns the components.
+   * This is the core symmetric encryption primitive.
+   * @param plaintext The stringified data to encrypt.
+   * @param cekBytes The 32-byte Content Encryption Key (Symmetric Key).
+   * @param aad The base64url-encoded 'JWE Protected Header', which serves as the 'Additional Authenticated Data' (AAD) for integrity verification.
+   * @returns A promise resolving to the JWE-compatible encrypted components (ciphertext, iv, tag).
+   */
+  encrypt(plaintext: string, cekBytes: Uint8Array, aad: string): Promise<ProtectedDataAES>
+    
+  /**
+   * Decrypts JWE-compatible encrypted components back to a plaintext string.
+   * @param encryptedData The object containing the base64url-encoded ciphertext, iv, and tag.
+   * @param cekBytes The 32-byte Content Encryption Key.
+   * @param aad The base64url-encoded 'JWE Protected Header', which serves as the 'Additional Authenticated Data' (AAD) for integrity verification.
+   * @returns A promise resolving to the decrypted plaintext string.
+   */
+  decrypt(
+    encryptedData: ProtectedDataAES,
+    cekBytes: Uint8Array,
+    aad: string
+  ): Promise<string>
+
+  // --- Post-Quantum Computing ---
+  
+  /**
+   * Generates and protects (encapsulates) a symmetric shared key (32 bytes)
+   * @param cekSeedBytes 
+   * @param secretKeyBytes 
+   * @param recipientPublicKeyBytes 
+   */
+  encapsulate(cekSeedBytes: Uint8Array, secretKeyBytes: Uint8Array, recipientPublicKeyBytes: Uint8Array): Promise<{ encapsulatedCekBytes: Uint8Array; derivedCekBytes: Uint8Array; }>
+  
+  /**
+   * Returns the unprotected shared symmetric key
+   * @param encapsulatedBytes 
+   * @param secretKeyBytes 
+   */
+  decapsulate(encapsulatedBytes: Uint8Array, secretKeyBytes: Uint8Array): Promise<Uint8Array>;
+  
+  /**
+   * Signs a byte array using a specified ML-DSA algorithm.
+   * @param payloadBytes The raw data to sign.
+   * @param secretKeyBytes The private signing key.
+   * @param alg The ML-DSA algorithm to use (e.g., 'ML-DSA-44').
+   * @returns A promise resolving to the raw signature bytes.
+   */
+  signBytes(payloadBytes: Uint8Array, secretKeyBytes: Uint8Array, alg: MldsaAlg): Promise<Uint8Array>; 
+  
+  /**
+   * Verifies a signature against a byte array and a public key.
+   * The algorithm is inferred from the `alg` property of the publicJWKey.
+   * @param signatureBytes The raw signature to verify.
+   * @param dataBytes The original data that was signed.
+   * @param publicJWKey The public key to use for verification.
+   * @returns A promise resolving to true if the signature is valid, false otherwise.
+   */
+  verifyBytes(signatureBytes: Uint8Array, dataBytes: Uint8Array, publicJWKey: PublicJwk): Promise<boolean>;  
+  
+  // --- High-Level Workflows ---
+
+  /**
+   * Encrypts a payload into a JWE Object, suitable for JSON General Serialization.
+   * This method keeps protected and per-recipient headers separate, making it ideal
+   * for multi-recipient scenarios or storing as a structured object (e.g., ConfidentialStorage).
+   * @param payload The JSON object to encrypt.
+   * @param protectedHeader The main protected header (JWE Protected Header). Used as AAD.
+   * @param secretJWKey The sender's private ML-KEM key.
+   * @param recipientsJWKeys An array of public ML-KEM keys for the recipients.
+   * @returns A Promise resolving to a JweObject.
+   */
+  encryptJwe(payload: object, protectedHeader: object, secretJWKey: MlkemPrivateJwk, recipientsJWKeys: MlkemPublicJwk[]): Promise<JweObject>;
+
+  /**
+   * Encrypts a payload directly into a JWE Compact Serialization string.
+   * This method is optimized for single-recipient JWEs. It merges the protected and
+   * recipient headers *before* encryption to form the correct AAD for the compact format.
+   * @param payload The JSON object to encrypt or a nested JWS string (compact representation).
+   * @param protectedHeader The main protected header (e.g., specifying `enc`).
+   * @param secretJWKey The sender's private ML-KEM key.
+   * @param recipientJWKey The single recipient's public ML-KEM key.
+   * @returns A Promise resolving to the JWE as a compact string.
+   */
+  encryptJweToCompact(payload: object | string, protectedHeader: object, secretJWKey: MlkemPrivateJwk, recipientJWKey: MlkemPublicJwk): Promise<string>;
+  
+  /**
+   * Decrypts a JWE (in Compact or JSON format) and returns the decrypted bytes and protected header.
+   * This method identifies the correct recipient using the `kid` from the provided private JWK.
+   * @param jwe The JWE object or Compact JWE string.
+   * @param secretKeyJwk The private key of the recipient, containing the `kid` to find the
+   *   correct recipient and the `dBytes` for the decapsulation operation.
+   * @returns A promise resolving to an object containing the decrypted bytes and the decoded protected header.
+   */
+  decryptJwe(
+    jwe: JweObject | string,
+    secretKeyJwk: MlkemPrivateJwk
+  ): Promise<{ decryptedBytes: Uint8Array, protectedHeader: object }>;
+
+
+  /**
+   * @param jwe The JWE object or Compact/JSON JWE string.
+   * @returns An array of strings, where each string is a recipient's `kid`. Returns an empty array if no kids are found.
+   */
+  getRecipientKidsFromJwe(jwe: JweObject | string): string[];  
+
+  /**
+   * Creates a JWS using the payload and header objects, and the signer's private key bytes.
+   */
+  signDataJws(payload: object, protectedHeader: object, secretJWKey: Uint8Array): Promise<JwtCompactParts>;
+
+  /**
+   * Verifies the signature of a JWS Object against the signer's public key (JWK).
+   */
+  verifyJws(jws: JwtCompactParts | string, publicJWKey: PublicJwk): Promise<boolean>;
+
+  /**
+   * Verifies a detached JWS signature against the original payload.
+   * @param payloadBytes The original, unencoded byte stream that was signed.
+   * @param detachedJws The JWS in detached format ('header..signature').
+   * @param publicJWKey The signer's public key (JWK) to use for verification.
+   * @returns A boolean indicating if the signature is valid.
+   */
+  verifyDetachedJws(payloadBytes: Uint8Array, detachedJws: string, publicJWKey: PublicJwk): Promise<boolean>;  
+  
+  // --- Formatting & Parsing Utilities (Note: from cryptoEncode, cryptoDecode, jwt utils ... ---
+
+  /**
+   * Converts a JWS Object (with decoded headers and payload) into Compact Serialization format.
+   * @param jws The JWS Object to convert.
+   * @returns The JWS in Compact Serialization format (three base64url strings joined by dots).
+   */
+  jwsToCompact(jws: DataCompactJWT): string;
+  
+  /**
+   * Parses a JWS in Compact Serialization format into a JWS Object with decoded headers and payload.
+   * @param jwsString The compact JWS string.
+   * @returns A JWS Object with JSON objects for the header and payload.
+   */
+  parseCompactJws(jwsString: string): DataCompactJWT;
+  
+  /**
+   * Parses a JWE in Compact Serialization format into a JWE Object.
+   * @param jweString The compact JWE string.
+   * @returns A JWE Object.
+   */
+  parseCompactJwe(jweString: string): JweObject;
+}
+

package/src/interfaces/IWallet.ts

@@ -0,0 +1,62 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/interfaces/IWallet.ts
+
+import { JwkSet } from '../models/jwk';
+
+/**
+ * @interface IWallet
+ * Defines the contract for a client-side Wallet, acting as the "frontend KmsService".
+ * It provides high-level cryptographic capabilities without exposing low-level primitives.
+ * @sdk
+ */
+export interface IWallet {
+  /**
+   * Provisions a new, full set of cryptographic keys for a given entity identifier.
+   * This is the primary method for creating a new cryptographic identity.
+   * @param entityId The unique identifier for the key set (e.g., a profile ID).
+   * @returns A Promise that resolves to the public parts of the generated keys in a JWKSet format.
+   */
+  provisionKeys(entityId: string): Promise<JwkSet>;
+
+  /**
+   * Creates a cryptographic digest (hash) of a string.
+   * @param data The string to hash.
+   * @param algorithm The digest algorithm to use.
+   * @returns A Promise that resolves to the hex-encoded hash string.
+   */
+  digest(data: string, algorithm: any): Promise<string>;
+
+  /**
+   * Encrypts a document for secure, local storage (at-rest).
+   * @param doc The document to protect, which must have a `.content` property.
+   * @param entityId The ID of the entity whose keys should be used for encryption.
+   * @returns A Promise that resolves to the protected document, where `.content` is replaced by `.jwe`.
+   */
+  protectConfidentialData(doc: any, entityId: string): Promise<any>;
+
+  /**
+   * Decrypts a document from secure storage.
+   * @param doc The protected document containing the `.jwe` property.
+   * @param entityId The ID of the entity whose keys should be used for decryption.
+   * @returns A Promise that resolves to the document with the decrypted `.content`.
+   */
+  unprotectConfidentialData(doc: any, entityId: string): Promise<any>;
+
+  /**
+   * (Optional) Packs a DIDComm message into a secure format (JWE/JARM) for a recipient.
+   * This is required for FAPI-compliant flows.
+   * @param content The DIDComm message content to pack.
+   * @param recipientDid The DID of the recipient.
+   * @returns A Promise that resolves to the packed, secure message string.
+   */
+  packForRecipient?(content: any, recipientDid: string): Promise<string>;
+
+  /**
+   * (Optional) Unpacks a secure message (JWE/JARM) received from a server.
+   * This is the counterpart to `packForRecipient`.
+   * @param packedMessage The secure message string (e.g., a compact JWE).
+   * @returns A Promise that resolves to an object containing the plaintext `content` and any cryptographic `meta` data.
+   */
+  unpack?(packedMessage: string): Promise<{ content: any, meta: any }>;
+}
+

package/src/interfaces/MlDsa.ts

@@ -0,0 +1,25 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/interfaces/MlDsa.ts
+
+/**
+ *  level 2: privateKeySize = 2528, publicKeySize = 1312, signatureSize = 2420
+ *  level 3: privateKeySize = 4000, publicKeySize = 1952, signatureSize = 3293
+ *  level 5: privateKeySize = 4864, publicKeySize = 2592, signatureSize = 4595
+ *  @see https://openquantumsafe.org/liboqs/algorithms/sig/dilithium.html
+ */
+;
+
+// Size of a packed public key: 32 + PolyT1Size*K
+export const MlDsaPubKeySizeLevel2 = 1312;
+export const MlDsaPubKeySizeLevel3 = 1952;
+export const MlDsaPubKeySizeLevel5 = 2592;
+
+// Size of a packed private key : 32 + 32 + 32 + polyLeqEtaSize*(l+k) + PolyT0Size*K
+export const MlDsaPrivKeySizeLevel2 = 2528;
+export const MlDsaPrivKeySizeLevel3 = 4000;
+export const MlDsaPrivKeySizeLevel5 = 4864;
+
+// Size of a packed signature: l*polyLeGamma1Size + omega + k + 32
+export const MlDsaSignatureSizeLevel2 = 2420;
+export const MlDsaSignatureSizeLevel3 = 3293;
+export const MlDsaSignatureSizeLevel5 = 4595;

package/src/interfaces/MlKem.ts

@@ -0,0 +1,18 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/interfaces/MlKem.ts
+
+export const paramsSymBytes = 32;
+
+export const paramsPolyBytes = 384;
+export const paramsPolyvecBytesK512 = 2 * paramsPolyBytes;
+export const paramsPolyvecBytesK768 = 3 * paramsPolyBytes;
+export const paramsPolyvecBytesK1024 = 4 * paramsPolyBytes;
+
+/** Kyber512PKBytes is a constant representing the byte length of public keys in Kyber-512 */
+export const Kyber512PKBytes = paramsPolyvecBytesK512 + paramsSymBytes;
+
+/** Kyber768PKBytes is a constant representing the byte length of public keys in Kyber-768 */
+export const Kyber768PKBytes = paramsPolyvecBytesK768 + paramsSymBytes;
+
+/** Kyber1024PKBytes is a constant representing the byte length of public keys in Kyber-1024 */
+export const Kyber1024PKBytes = paramsPolyvecBytesK1024 + paramsSymBytes;

package/src/models/aes.ts

@@ -0,0 +1,93 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/aes.ts
+
+export const WORD_BYTES=4;
+export const WORD_BITS=WORD_BYTES*8;        // sjcl BitArray are words of 32 bits.
+export const AES_GCM_256_KEY_SIZE_BITS=256; // key size is 32 bytes = 256 bits (by default it is 128 bits).
+export const AES_GCM_TAG_SIZE_BITS=128;     // tag size is 16 bytes = 128 bits (by default it is 64 bits).
+export const AES_GCM_NONCE_SIZE_BITS=128;   // NIST 800-38D 8.2.2 (RGB Construction of IV) allows to be 16 bytes (128 bits). 
+export const AES_GCM_JWA_ENC='A256GCM'      // AES GCM using 256-bit key, see https://datatracker.ietf.org/doc/html/rfc7518#section-5.1
+
+/**
+ * Represents the raw, binary components of a payload encrypted with AES-GCM.
+ * This interface is used for in-memory cryptographic operations before any
+ * Base64Url encoding is applied. Its string-based counterpart for transport
+ * is `ProtectedDataAES`.
+ */
+export interface AesGcmComponents {
+  /**
+   * The encrypted content as a raw byte array.
+   */
+  ciphertext: Uint8Array;
+  /**
+   * The Initialization Vector (IV) as a raw byte array.
+   */
+  iv: Uint8Array;
+  /**
+   * The Authentication Tag generated by the GCM mode.
+   */
+  authTag: Uint8Array;
+}
+
+/**
+ * Represents the components of an AES-GCM encrypted payload, with each
+ * component encoded as a Base64Url string. This is suitable for use in
+ * transport structures like a JWE. Its byte-based counterpart for in-memory
+ * operations is `AesGcmComponents`.
+ *
+ * - ciphertext: base64url encoded bytes of the plaintext
+ * - tag: base64url encoded
+ * - iv: base64url encoded (it is like a nonce)
+ */
+export interface ProtectedDataAES {
+    ciphertext: string;
+    tag: string;
+    iv: string;
+}
+
+
+/** Use it instead of the SjclCipherDecryptParams to avoid problems with encryption / decryption
+ * iv: required random bytes created for Initialization Vector (nonce) created when doing the encryption, base64 encoded (but not Base64url nor BitArray).
+ * adata: AAD (Additional Authenticated Data) base64 encoded (e.g.: JWE protected headers), but not base64url nor BitArray. It can be and empty string "".
+ * ct: ciphertext and tag combined and then base64 encoded, but not base64url nor BitArray.
+ * ts: tagsize is only required if a value other than the sjcl default value (64 bits) is defined in the encryption options (to know what size authentication tag is part of the cipher text)
+ * mode: "ccm", "gcm" (the default is "ccm").
+ * ks: keysize is only required if a value other than the sjcl default value (128 bits) is defined in the encryption options (to know what size key to generate with Pbkdf2)
+ * iter: iterations for Pbkdf2
+ * v: scjl version
+ * cipher: "aes"
+ */
+export interface DecryptionDataWithParametersSJCL {
+    iv:     string; // required random bytes for Initialization Vector (nonce) base64 encoded, but not Base64url nor BitArray.
+    adata:  string; // required AAD (Additional Authenticated Data) base64 encoded (e.g.: JWE protected headers), but not base64url nor BitArray. It can be and empty string "".
+    ct:     string; // ciphertext and tag combined and then base64 encoded, but not base64url nor BitArray.
+    ts?:    number; // tagsize is only required if a value other than the sjcl default value (64 bits) is defined in the encryption options (to know what size authentication tag is part of the cipher text)
+    mode?:  string; // "ccm", "gcm" (the default is "ccm").
+    ks?:    number; // keysize is only required if a value other than the sjcl default value (128 bits) is defined in the encryption options (to know what size key to generate with Pbkdf2)
+    iter?:  number; // iterations for Pbkdf2
+    v?:     number; // scjl version (optional, 1 is the default)
+    cipher?:string; // "aes"
+};
+
+/** Use it instead of the SjclCipherEncryptParams to avoid problems with encryption / decryption
+ * iv: required BitArray containing the random bytes for the Initialization Vector (nonce).
+ * adata: required BitArray containing the AAD (Additional Authenticated Data), e.g.: JWE protected headers.
+ * ts: tagsize is only required if a value other than the sjcl default value (64 bits) is used (to know what size authentication tag is part of the cipher text).
+ * mode: "ccm", "gcm" (the default is "ccm").
+ * ks: keysize is only required if a value other than the sjcl default value (128 bits) is used (to know what size key to generate with Pbkdf2)
+ * iter: iterations for Pbkdf2
+ * salt: BitArray, a 64 bits salt it is created automatically if not provided when generating the key from a password (KDF).
+ * v: scjl version
+ * cipher: "aes"
+ */
+ export interface EncryptionParametersSJCL {
+    iv:     any;  // required sjcl.BitArray containing the random bytes for the Initialization Vector (nonce).
+    adata:  any;  // required sjcl.BitArray containing the AAD (Additional Authenticated Data), e.g.: JWE protected headers.
+    ts?:    number;         // tagsize is only required if a value other than the sjcl default value (64 bits) is used (to know what size authentication tag is part of the cipher text).
+    mode?:   string;        // "ccm", "gcm" (the default is "ccm").
+    ks?:    number;         // keysize is only required if a value other than the sjcl default value (128 bits) is used (to know what size key to generate with Pbkdf2)
+    iter?:  number;         // iterations for Pbkdf2
+    salt?:  any;  // sjcl.BitArray, a 64 bits salt it is created automatically if not provided when generating the key from a password (KDF).
+    v?:     number;         // scjl version (optional, 1 is the default)
+    cipher?: string;        // "aes"
+};

package/src/models/auth.ts

@@ -0,0 +1,38 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: src/models/auth.ts
+
+/**
+ * Defines the structure of the claims object decoded from a bearer access token.
+ * This object is typically attached to the request object by an authentication middleware.
+ */
+export interface IAccessTokenClaims {
+  /**
+   * Issuer of the token (e.g., the DID of the issuing tenant).
+   * This is the source of truth for identifying the tenant.
+   */
+  iss: string;
+  /**
+   * Subject of the token (e.g., the DID of the employee).
+   */
+  sub: string;
+  /**
+   * Audience for which the token is intended.
+   */
+  aud: string;
+  /**
+   * Expiration time (Unix timestamp).
+   */
+  exp: number;
+  /**
+   * Issued at time (Unix timestamp).
+   */
+  iat: number;
+  /**
+   * The scope of permissions granted by the token.
+   */
+  scope: string;
+  /**
+   * Client ID - The client that requested the token.
+   */
+  client_id: string;
+}

package/src/models/bundle.ts

@@ -0,0 +1,152 @@
+/**
+ * @file src/models/bundle.ts
+ * @copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+ *
+ * @summary
+ * This file defines the canonical data structures for "Bundles" and their "Entries"
+ * within this system, following a hybrid FHIR / JSON:API pattern. It is the single
+ * source of truth for the shape of request and response bodies.
+ *
+ * @architecture
+ * The models herein are critical for maintaining architectural consistency.
+ *
+ * 1.  **`BundleJsonApi`**: The top-level container for all batch operations. Corresponds
+ *     to the `body` of a DIDComm message or a standard API request.
+ *
+ * 2.  **`BundleEntry`**: The core component of a Bundle. Represents a single unit of work,
+ *     such as registering one organization or creating one employee. It has a strict
+ *     structure:
+ *     - `type`: A string that defines the business action (e.g., 'Organization-registration-offer-v1.0').
+ *     - `meta`: A **TOP-LEVEL** property containing the original `claims` for the operation.
+ *               This is crucial for both processing and error reporting.
+ *     - `resource`: A FHIR-like resource object that is the subject of the action. It
+ *                   contains the structured data derived from the claims.
+ *     - `request`/`response`: Contextual objects indicating the operation's details or result.
+ */
+
+import { OperationOutcome } from "./operation-outcome";
+
+// ===================================================================================
+// BUNDLE ENTRY COMPONENTS
+// ===================================================================================
+
+/**
+ * Defines the `request` property for an entry in a request Bundle.
+ * This indicates the intended action for the entry.
+ */
+export interface BundleRequest {
+  method: 'POST' | 'PUT' | 'DELETE' | 'GET';
+  url: string;
+}
+
+/**
+ * Defines the `response` property for an entry in a response Bundle.
+ * This indicates the outcome of the action for the entry.
+ */
+export interface BundleResponse {
+  /** The HTTP status code as a string (e.g., "201", "404"). */
+  status: string;
+  [key: string]: any;
+}
+
+/**
+ * Defines the `meta` property that holds the original, unprocessed claims for a BundleEntry.
+ * This ensures that the complete context of a request is preserved through the entire
+ * asynchronous workflow and is available for error reporting.
+ */
+export interface BundleEntryMeta {
+  /** The original, flattened claims record for this specific entry. */
+  claims?: Record<string, any>;
+}
+
+// ===================================================================================
+// BUNDLE ENTRY TYPES
+// ===================================================================================
+
+/**
+ * @deprecated Use `BundleEntry` instead. This will be removed in a future version.
+ * Represents a single entry in an INCOMING request Bundle.
+ */
+export interface BundleEntryRequest {
+  id?: string;
+  type: string;
+  request: BundleRequest;
+  resource?: Record<string, any>;
+  meta?: BundleEntryMeta;
+}
+
+/**
+ * @deprecated Use `BundleEntry` instead. This will be removed in a future version.
+ * Represents a single successful entry in an OUTGOING response Bundle.
+ */
+export interface BundleEntryResponse {
+  id?: string;
+  type: string;
+  response: BundleResponse;
+  resource?: Record<string, any>;
+  meta?: BundleEntryMeta;
+}
+
+/**
+ * Represents a single error entry in a response Bundle.
+ *
+ * @architecture
+ * CRITICAL: When an error occurs for a specific request entry, the corresponding error
+ * entry in the response MUST include the original, unprocessed `meta` object from that
+ * request entry. This allows the client to correlate the exact input that caused the failure.
+ */
+export interface ErrorEntry {
+  /** An optional unique identifier for this entry. */
+  id?: string;
+  /** The `type` of the original request entry that failed. */
+  type: string;
+  /** The original, unprocessed `meta` object from the request entry that failed. */
+  meta?: BundleEntryMeta;
+  /** The details of the error that occurred. */
+  response: {
+    /** The HTTP status code reflecting the error (e.g., "400", "500"). */
+    status: string;
+    /** A FHIR OperationOutcome resource providing detailed error diagnostics. */
+    outcome: OperationOutcome;
+  };
+}
+
+/**
+ * Represents a single, canonical entry within a `BundleJsonApi`.
+ * This structure is used for both requests and successful responses.
+ *
+ * @property {string} type - A string identifying the business action of the entry.
+ * @property {BundleEntryMeta} meta - **(TOP-LEVEL PROPERTY)** Contains the original, unprocessed claims.
+ * @property {object} resource - The primary FHIR-like resource that is the subject of the action.
+ * @property {BundleRequest} [request] - Details of the requested operation (for request bundles).
+ * @property {BundleResponse} [response] - Details of the operation outcome (for response bundles).
+ */
+export type BundleEntry = {
+  id?: string;
+  type: string;
+  meta?: BundleEntryMeta;
+  resource?: Record<string, any>;
+  request?: BundleRequest;
+  response?: BundleResponse;
+}
+
+// ===================================================================================
+// BUNDLE DEFINITION
+// ===================================================================================
+
+/**
+ * Represents the canonical Bundle structure used as the `body` of a request or response.
+ * The generic type `T` allows for specifying whether the `data` array contains request
+ * entries or response entries, providing strong type safety.
+ *
+ * @example
+ * const requestBundle: BundleJsonApi<BundleEntry> = { ... };
+ * const responseBundle: BundleJsonApi<BundleEntry | ErrorEntry> = { ... };
+ */
+export interface BundleJsonApi<T = BundleEntry | ErrorEntry> {
+  data: T[];
+  resourceType: 'Bundle';
+  total?: number;
+  type: string;
+}
+

package/src/models/bundle.txt

@@ -0,0 +1,93 @@
+// src/models/bundle.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import { OperationOutcome } from "./fhir/operation-outcome";
+
+// ===================================================================================
+// BUNDLE ENTRY COMPONENTS
+// ===================================================================================
+
+/**
+ * Defines the `request` property for an entry in a request Bundle.
+ */
+export interface BundleRequest {
+  method: 'POST' | 'PUT' | 'DELETE' | 'GET';
+  url: string;
+}
+
+/**
+ * Defines the `response` property for an entry in a response Bundle.
+ */
+export interface BundleResponse {
+  status: string; // e.g., "201"
+  [key: string]: any;
+}
+
+/**
+ * Defines the `meta` property that can hold contextual information.
+ */
+export interface BundleEntryMeta {
+  claims?: Record<string, any>;
+}
+
+// ===================================================================================
+// BUNDLE ENTRY TYPES
+// ===================================================================================
+
+/**
+ * Represents a single entry in an INCOMING request Bundle.
+ */
+export interface BundleEntryRequest {
+  id?: string;
+  type: string;
+  request: BundleRequest;
+  resource?: Record<string, any>;
+  meta?: BundleEntryMeta;
+}
+
+/**
+ * Represents a single successful entry in an OUTGOING response Bundle.
+ */
+export interface BundleEntryResponse {
+  id?: string;
+  type: string;
+  response: BundleResponse;
+  resource?: Record<string, any>;
+  meta?: BundleEntryMeta;
+}
+
+/**
+ * Represents a single error entry in an OUTGOING response Bundle.
+ */
+export interface ErrorEntry {
+  id?: string;
+  type: string;
+  meta?: BundleEntryMeta; // Preserves original context
+  response: {
+    status: string;
+    outcome: OperationOutcome;
+  };
+}
+
+/** A union type for backward compatibility where the distinction is not yet needed. */
+
+export type BundleEntry = BundleEntryRequest | BundleEntryResponse | ErrorEntry
+
+// ===================================================================================
+// BUNDLE DEFINITION
+// ===================================================================================
+
+/**
+ * Represents the canonical Bundle structure.
+ * The generic type `T` allows us to specify whether the `data` array
+ * contains request entries or response entries, providing strong type safety.
+ *
+ * @example
+ * const requestBundle: Bundle<BundleEntryRequest> = { ... };
+ * const responseBundle: Bundle<BundleEntryResponse | ErrorEntry> = { ... };
+ */
+export interface Bundle<T = BundleEntryRequest | BundleEntryResponse | ErrorEntry> {
+  type: string;
+  total?: number;
+  data: T[];
+}