gdc-common-utils-ts 2.3.0 → 2.3.2

package/README.md

@@ -209,6 +209,11 @@ The `utils` export exposes reusable helpers for DID and message handling, such a
 - `utils/content`
 - `utils/normalize`
 - `utils/unified-health-id` for provider-scoped Damm control digits over normalized provider + personal numeric sequences
+- `utils/multibasehash` for `encodeMultibaseSha3(input, digestBits = 384)`,
+  returning a base58btc multibase-encoded SHA3 multihash
+- `utils/multiformat-profile` for
+  `buildRawCidV1FromUtf8String(canonicalValue)`, returning
+  `CIDv1(raw, SHA3-384)` by default
 - `utils/fhir-cid` for recursive FHIR canonicalization + CID generation + `meta.versionId` assignment
 - `utils/fhir-validator` for adapter-based FHIR validation (`validateFhirResource`, pluggable formal validator)
 - conversion, formatting, and multibase helpers
@@ -220,8 +225,25 @@ Example:
 ```ts
 import { normalizeDidWeb, generateServiceId } from 'gdc-common-utils-ts/utils/did';
 import { fhirResourceToCid, assignCidToFhirResourceVersionId } from 'gdc-common-utils-ts/utils/fhir-cid';
+import { encodeMultibaseSha3 } from 'gdc-common-utils-ts/utils/multibasehash';
+import { buildRawCidV1FromUtf8String } from 'gdc-common-utils-ts/utils/multiformat-profile';
+
+const lookupMultihash = encodeMultibaseSha3('DL|US-CA|D1234567');
+const blockchainAssetId = buildRawCidV1FromUtf8String('DL|US-CA|D1234567');
 ```
 
+Individual lookup tokens keep the identifier type and jurisdiction separate:
+`org.hl7.terminology.CodeSystem.v2-0203.NN|ES|12345678Z`. Import
+`buildIndividualIdentifierLedgerAssetId(...)` when a GW must derive the opaque
+SHA3-384 `urn:multibase` key used by the subject-identifier ledger. The raw
+identifier must never be written to that ledger.
+
+Both helpers hash the exact UTF-8 bytes supplied by the caller. Identifier,
+FHIR-token or JSON canonicalization belongs to the contract that owns the
+input. A multibase multihash is suitable as a deterministic lookup key; a CID
+is suitable when the key must identify a content-addressed record or
+blockchain asset.
+
 ### Convert
 
 The `convert` export exposes resource-specific FHIR R4 conversion helpers such as:

package/dist/CryptographyService.d.ts

@@ -49,6 +49,9 @@ export declare class CryptographyService implements ICryptography {
         derivedCekBytes: Uint8Array;
     }>;
     decapsulate(encapsulatedBytes: Uint8Array, secretKeyBytes: Uint8Array): Promise<Uint8Array>;
+    private wrapCekForRecipient;
+    private unwrapRecipientCek;
+    private deriveRecipientKek;
     signBytes(payloadBytes: Uint8Array, secretKeyBytes: Uint8Array, alg: MldsaAlg): Promise<Uint8Array>;
     verifyBytes(signatureBytes: Uint8Array, dataBytes: Uint8Array, publicKey: PublicJwk): Promise<boolean>;
     jwsToCompact(jws: DataCompactJWT): string;

package/dist/CryptographyService.js

@@ -4,6 +4,8 @@ import * as pako from 'pako';
 import * as jwtUtils from './utils/jwt.js';
 import { AesManager } from './AesManager.js';
 import { Content } from './utils/content.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
 /**
  * Implements the ICryptography interface, providing a complete suite of low-level,
  * stateless cryptographic functions. This service is the "engine" of the security layer,
@@ -113,23 +115,17 @@ export class CryptographyService {
     }
     // --- High-Level Workflows ---
     async encryptJwe(payload, protectedHeader, secretJWKey, recipientsJWKeys) {
-        // ARCHITECTURAL NOTE: This implementation is currently only suitable for a single recipient.
-        // A Key Encapsulation Mechanism (KEM) derives a *different* shared secret for each recipient's public key.
-        // A true multi-recipient JWE requires a single Content Encryption Key (CEK) that is then
-        // encrypted (wrapped) for each recipient. This code uses the KEM-derived shared secret as the CEK.
-        // This must be refactored to a key-wrapping approach to support multiple recipients correctly.
+        // v1 deliberately exposes one recipient while using a distinct random CEK.
+        // The recipient wrap is already compatible with a future General JWE profile.
         if (recipientsJWKeys.length !== 1) {
             // Temporarily throw until the architecture is fixed for multi-recipient.
             throw new Error("CryptographyService.encryptJwe currently only supports a single recipient.");
         }
         const recipient = recipientsJWKeys[0];
         const publicKeyBytes = Content.base64ToBytes(recipient.x);
-        // Per RFC 9278, we generate a random seed for the KEM. The KEM then derives both the
-        // final Content Encryption Key (CEK) and the encapsulated key from this seed.
-        const cekSeedBytes = await this.cryptoHelper.getRandomBytes(32);
-        const { derivedCekBytes, // This is the actual Content Encryption Key
-        encapsulatedCekBytes // This is the encrypted key for the recipient
-         } = await this.encapsulate(cekSeedBytes, secretJWKey.dBytes, publicKeyBytes);
+        const cekBytes = await this.cryptoHelper.getRandomBytes(32);
+        const kemSeedBytes = await this.cryptoHelper.getRandomBytes(32);
+        const { derivedCekBytes: sharedSecret, encapsulatedCekBytes } = await this.encapsulate(kemSeedBytes, secretJWKey.dBytes, publicKeyBytes);
         // 2. Now, use the *derived* CEK to encrypt the payload with AES.
         const protectedHeaderB64Url = Content.objectToRawBase64UrlSafe(protectedHeader);
         let payloadBytes = Content.objectToBytes(payload);
@@ -139,13 +135,13 @@ export class CryptographyService {
             payloadString = Content.bytesToRawBase64UrlSafe(payloadBytes);
         }
         else {
-            payloadString = Content.bytesToStringASCII(payloadBytes);
+            payloadString = Content.bytesToStringUTF8(payloadBytes);
         }
-        const encrypted = await this.encrypt(payloadString, derivedCekBytes, protectedHeaderB64Url);
-        // 3. Assemble the JWE. The `encrypted_key` is the result of the KEM encapsulation.
+        const encrypted = await this.encrypt(payloadString, cekBytes, protectedHeaderB64Url);
+        const wrappedCek = await this.wrapCekForRecipient(cekBytes, sharedSecret, encapsulatedCekBytes, protectedHeaderB64Url, recipient.kid);
         const recipientData = [{
-                header: { alg: recipient.crv, kid: recipient.kid },
-                encrypted_key: Content.bytesToRawBase64UrlSafe(encapsulatedCekBytes),
+                header: { alg: 'ML-KEM-768+HKDF-SHA256+A256GCMKW', kid: recipient.kid },
+                encrypted_key: Content.objectToRawBase64UrlSafe(wrappedCek),
             }];
         return {
             protected: protectedHeaderB64Url,
@@ -157,14 +153,16 @@ export class CryptographyService {
     }
     async encryptJweToCompact(payload, protectedHeader, secretJWKey, recipientJWKey) {
         // 1. Construct the complete, final protected header by merging the main and recipient headers.
-        const recipientHeader = { alg: recipientJWKey.crv, kid: recipientJWKey.kid };
+        const recipientHeader = { alg: 'ML-KEM-768+HKDF-SHA256+A256GCMKW', kid: recipientJWKey.kid };
         const finalProtectedHeader = { ...protectedHeader, ...recipientHeader };
         const protectedHeaderB64Url = Content.objectToRawBase64UrlSafe(finalProtectedHeader);
-        // 2. Perform KEM to derive the Content Encryption Key (CEK).
+        // 2. Generate a fresh content key, then protect it for the ML-KEM recipient.
         const publicKeyBytes = Content.base64ToBytes(recipientJWKey.x);
-        const cekSeedBytes = await this.cryptoHelper.getRandomBytes(32);
-        const { derivedCekBytes, encapsulatedCekBytes } = await this.encapsulate(cekSeedBytes, secretJWKey.dBytes, publicKeyBytes);
-        const encapsulatedKeyB64Url = Content.bytesToRawBase64UrlSafe(encapsulatedCekBytes);
+        const cekBytes = await this.cryptoHelper.getRandomBytes(32);
+        const kemSeedBytes = await this.cryptoHelper.getRandomBytes(32);
+        const { derivedCekBytes: sharedSecret, encapsulatedCekBytes } = await this.encapsulate(kemSeedBytes, secretJWKey.dBytes, publicKeyBytes);
+        const wrappedCek = await this.wrapCekForRecipient(cekBytes, sharedSecret, encapsulatedCekBytes, protectedHeaderB64Url, recipientJWKey.kid);
+        const encryptedKeyB64Url = Content.objectToRawBase64UrlSafe(wrappedCek);
         // 3. Encrypt the payload using the derived CEK and the *final* protected header as AAD.
         const payloadBytes = typeof payload === 'string'
             ? Content.stringToBytesUTF8(payload)
@@ -173,13 +171,13 @@ export class CryptographyService {
             // Note: Compressing a compact JWS string is often inefficient, but supported.
             const compressedPayload = pako.deflate(payloadBytes);
             const payloadString = Content.bytesToRawBase64UrlSafe(compressedPayload);
-            const encrypted = await this.encrypt(payloadString, derivedCekBytes, protectedHeaderB64Url);
-            return `${protectedHeaderB64Url}.${encapsulatedKeyB64Url}.${encrypted.iv}.${encrypted.ciphertext}.${encrypted.tag}`;
+            const encrypted = await this.encrypt(payloadString, cekBytes, protectedHeaderB64Url);
+            return `${protectedHeaderB64Url}.${encryptedKeyB64Url}.${encrypted.iv}.${encrypted.ciphertext}.${encrypted.tag}`;
         }
-        const payloadString = Content.bytesToStringASCII(payloadBytes);
-        const encrypted = await this.encrypt(payloadString, derivedCekBytes, protectedHeaderB64Url);
+        const payloadString = Content.bytesToStringUTF8(payloadBytes);
+        const encrypted = await this.encrypt(payloadString, cekBytes, protectedHeaderB64Url);
         // 4. Assemble the 5 parts of the compact JWE.
-        return `${protectedHeaderB64Url}.${encapsulatedKeyB64Url}.${encrypted.iv}.${encrypted.ciphertext}.${encrypted.tag}`;
+        return `${protectedHeaderB64Url}.${encryptedKeyB64Url}.${encrypted.iv}.${encrypted.ciphertext}.${encrypted.tag}`;
     }
     async decryptJwe(jwe, secretKeyJwk) {
         const jweObject = typeof jwe === 'string' ? this.parseCompactJwe(jwe) : jwe;
@@ -187,9 +185,7 @@ export class CryptographyService {
         if (!recipient || !recipient.encrypted_key) {
             throw new Error(`JWE does not contain a recipient with kid=${secretKeyJwk.kid}`);
         }
-        // Decapsulate to get the CEK
-        const encapsulatedKeyBytes = Content.base64ToBytes(recipient.encrypted_key);
-        const cekBytes = await this.decapsulate(encapsulatedKeyBytes, secretKeyJwk.dBytes);
+        const cekBytes = await this.unwrapRecipientCek(recipient.encrypted_key, secretKeyJwk, jweObject.protected);
         // Decrypt the payload
         const encryptedData = { ciphertext: jweObject.ciphertext, iv: jweObject.iv, tag: jweObject.tag };
         const decryptedPayloadString = await this.decrypt(encryptedData, cekBytes, jweObject.protected);
@@ -260,12 +256,9 @@ export class CryptographyService {
         return this.aesManager.decrypt(encryptedData, cekBytes, aad);
     }
     async encapsulate(cekSeedBytes, secretKeyBytes, recipientPublicKeyBytes) {
-        // According to RFC 9278 (JWE with ML-KEM), a seed is used for the KEM encapsulation.
-        // The KEM then derives a shared secret from this seed. It is this *derived* shared secret
-        // that is used to encrypt the content, NOT the original seed.
-        // The `encapsulate` function from the noble library handles this correctly by accepting the
-        // seed as the second argument. It returns both the encapsulated key (`cipherText`)
-        // and the derived shared secret, which we must use as the actual AES key.
+        // FIPS 203 ML-KEM encapsulation returns a ciphertext and a 32-byte shared secret.
+        // `secretKeyBytes` is retained only for public API compatibility; encapsulation
+        // requires the recipient public key, not a sender private key.
         const mlKem = await this.loadMlKem();
         const { sharedSecret, cipherText } = await mlKem.ml_kem768.encapsulate(recipientPublicKeyBytes, cekSeedBytes);
         return { derivedCekBytes: sharedSecret, encapsulatedCekBytes: cipherText };
@@ -274,6 +267,42 @@ export class CryptographyService {
         const mlKem = await this.loadMlKem();
         return mlKem.ml_kem768.decapsulate(encapsulatedBytes, secretKeyBytes);
     }
+    async wrapCekForRecipient(cekBytes, sharedSecret, kemCiphertext, protectedHeader, recipientKid) {
+        const kek = this.deriveRecipientKek(sharedSecret, protectedHeader, recipientKid);
+        const wrapped = await this.encrypt(Content.bytesToRawBase64UrlSafe(cekBytes), kek, `${protectedHeader}.${recipientKid}.cek`);
+        return {
+            v: 'gdc-mlkem-cek-wrap-v1',
+            kem: 'ML-KEM-768',
+            kdf: 'HKDF-SHA-256',
+            wrap: 'A256GCM',
+            kemCiphertext: Content.bytesToRawBase64UrlSafe(kemCiphertext),
+            iv: wrapped.iv,
+            ciphertext: wrapped.ciphertext,
+            tag: wrapped.tag,
+        };
+    }
+    async unwrapRecipientCek(encryptedKey, secretKeyJwk, protectedHeader) {
+        let wrapped;
+        try {
+            wrapped = Content.base64UrlSafeToJSON(encryptedKey);
+        }
+        catch {
+            // Legacy v0 used the raw ML-KEM ciphertext and the shared secret as CEK.
+            return this.decapsulate(Content.base64ToBytes(encryptedKey), secretKeyJwk.dBytes);
+        }
+        if (wrapped?.v !== 'gdc-mlkem-cek-wrap-v1' || wrapped.kem !== 'ML-KEM-768' || wrapped.kdf !== 'HKDF-SHA-256' || wrapped.wrap !== 'A256GCM') {
+            throw new Error('Unsupported ML-KEM CEK wrap profile.');
+        }
+        const sharedSecret = await this.decapsulate(Content.base64ToBytes(wrapped.kemCiphertext), secretKeyJwk.dBytes);
+        const kek = this.deriveRecipientKek(sharedSecret, protectedHeader, secretKeyJwk.kid);
+        const cek = Content.base64ToBytes(await this.decrypt({ iv: wrapped.iv, ciphertext: wrapped.ciphertext, tag: wrapped.tag }, kek, `${protectedHeader}.${secretKeyJwk.kid}.cek`));
+        if (cek.byteLength !== 32)
+            throw new Error('Invalid wrapped AES-256-GCM CEK.');
+        return cek;
+    }
+    deriveRecipientKek(sharedSecret, protectedHeader, recipientKid) {
+        return hkdf(sha256, sharedSecret, Content.stringToBytesUTF8('gdc-confidential-pqc-v1'), Content.stringToBytesUTF8(`${protectedHeader}.${recipientKid}.document-at-rest`), 32);
+    }
     async signBytes(payloadBytes, secretKeyBytes, alg) {
         const mlDsa = await this.loadMlDsa();
         switch (alg) {

package/dist/constants/identity-identifiers.d.ts

@@ -15,23 +15,76 @@
  * Reference:
  * http://terminology.hl7.org/CodeSystem/v2-0203
  */
+export declare const HL7_V2_0203_IDENTIFIER_SYSTEM: "http://terminology.hl7.org/CodeSystem/v2-0203";
+export declare const HL7_V2_0203_REVERSE_DNS_PREFIX: "org.hl7.terminology.CodeSystem.v2-0203";
+export declare const HL7_V2_0203_IDENTIFIER_CODES: Readonly<{
+    readonly DriverLicense: "DL";
+    readonly CitizenshipCard: "CZ";
+    readonly NationalNumber: "NN";
+    readonly PassportNumber: "PPN";
+    readonly JurisdictionalHealthNumber: "JHN";
+    readonly WorkPermit: "WP";
+    readonly StudyPermit: "SP";
+    readonly HealthCard: "HC";
+    readonly DonorRecord: "DR";
+    readonly PatientIdentifier: "PI";
+}>;
+export type Hl7V20203IdentifierCode = typeof HL7_V2_0203_IDENTIFIER_CODES[keyof typeof HL7_V2_0203_IDENTIFIER_CODES];
+/** Product-neutral document kinds used by subject identifier forms. */
+export declare const INDIVIDUAL_IDENTIFIER_KINDS: Readonly<{
+    readonly NationalPerson: "national-person";
+    readonly Passport: "passport";
+    readonly HealthNumber: "health-number";
+    readonly DriverLicense: "driver-license";
+    readonly WorkPermit: "work-permit";
+    readonly StudyPermit: "study-permit";
+}>;
+export type IndividualIdentifierKind = typeof INDIVIDUAL_IDENTIFIER_KINDS[keyof typeof INDIVIDUAL_IDENTIFIER_KINDS];
+export declare const INDIVIDUAL_IDENTIFIER_KIND_CODES: Readonly<{
+    readonly "national-person": "NN";
+    readonly passport: "PPN";
+    readonly "health-number": "JHN";
+    readonly "driver-license": "DL";
+    readonly "work-permit": "WP";
+    readonly "study-permit": "SP";
+}>;
 export declare enum IdKind {
     /** ISO 18013-5 mobile driving licence credential. */
     MobileDriverLicense = "org.iso.18013.5.1.mDL",
     /** HL7 driver license identifier. */
-    PersonalDriverLicense = "org.hl7.terminology.codesystem.v2-0203.DL",
+    PersonalDriverLicense = "org.hl7.terminology.CodeSystem.v2-0203.DL",
     /** HL7 citizenship card identifier. */
-    PersonalCitizenshipCard = "org.hl7.terminology.codesystem.v2-0203.CZ",
+    PersonalCitizenshipCard = "org.hl7.terminology.CodeSystem.v2-0203.CZ",
     /** HL7 national identity number. */
-    PersonalNationalNumber = "org.hl7.terminology.codesystem.v2-0203.NN",
+    PersonalNationalNumber = "org.hl7.terminology.CodeSystem.v2-0203.NN",
+    /** HL7 passport number. */
+    PersonalPassportNumber = "org.hl7.terminology.CodeSystem.v2-0203.PPN",
     /** HL7 jurisdictional health number. */
-    RegionalHeathCardNumber = "org.hl7.terminology.codesystem.v2-0203.JHN",
+    RegionalHealthCardNumber = "org.hl7.terminology.CodeSystem.v2-0203.JHN",
+    /** @deprecated Use `RegionalHealthCardNumber`. */
+    RegionalHeathCardNumber = "org.hl7.terminology.CodeSystem.v2-0203.JHN",
+    /** HL7 work permit. */
+    PersonalWorkPermit = "org.hl7.terminology.CodeSystem.v2-0203.WP",
+    /** HL7 study permit. */
+    PersonalStudyPermit = "org.hl7.terminology.CodeSystem.v2-0203.SP",
     /** HL7 local/private health card identifier. */
-    LocalHealthCard = "org.hl7.terminology.codesystem.v2-0203.HC",
+    LocalHealthCard = "org.hl7.terminology.CodeSystem.v2-0203.HC",
     /** HL7 donor record identifier. */
-    LocalDonorRecord = "org.hl7.terminology.codesystem.v2-0203.DR",
+    LocalDonorRecord = "org.hl7.terminology.CodeSystem.v2-0203.DR",
     /** HL7 local patient identifier. */
-    LocalPatientIdentifier = "org.hl7.terminology.codesystem.v2-0203.PI"
+    LocalPatientIdentifier = "org.hl7.terminology.CodeSystem.v2-0203.PI"
 }
+export declare const HL7_V2_0203_REVERSE_DNS_TYPES: Readonly<{
+    readonly DL: IdKind.PersonalDriverLicense;
+    readonly CZ: IdKind.PersonalCitizenshipCard;
+    readonly NN: IdKind.PersonalNationalNumber;
+    readonly PPN: IdKind.PersonalPassportNumber;
+    readonly JHN: IdKind.RegionalHealthCardNumber;
+    readonly WP: IdKind.PersonalWorkPermit;
+    readonly SP: IdKind.PersonalStudyPermit;
+    readonly HC: IdKind.LocalHealthCard;
+    readonly DR: IdKind.LocalDonorRecord;
+    readonly PI: IdKind.LocalPatientIdentifier;
+}>;
 /** Union helper for code that wants typed values without depending on the enum object. */
 export type IdKindValue = typeof IdKind[keyof typeof IdKind];

package/dist/constants/identity-identifiers.js

@@ -15,22 +15,73 @@
  * Reference:
  * http://terminology.hl7.org/CodeSystem/v2-0203
  */
+export const HL7_V2_0203_IDENTIFIER_SYSTEM = 'http://terminology.hl7.org/CodeSystem/v2-0203';
+export const HL7_V2_0203_REVERSE_DNS_PREFIX = 'org.hl7.terminology.CodeSystem.v2-0203';
+export const HL7_V2_0203_IDENTIFIER_CODES = Object.freeze({
+    DriverLicense: 'DL',
+    CitizenshipCard: 'CZ',
+    NationalNumber: 'NN',
+    PassportNumber: 'PPN',
+    JurisdictionalHealthNumber: 'JHN',
+    WorkPermit: 'WP',
+    StudyPermit: 'SP',
+    HealthCard: 'HC',
+    DonorRecord: 'DR',
+    PatientIdentifier: 'PI',
+});
+/** Product-neutral document kinds used by subject identifier forms. */
+export const INDIVIDUAL_IDENTIFIER_KINDS = Object.freeze({
+    NationalPerson: 'national-person',
+    Passport: 'passport',
+    HealthNumber: 'health-number',
+    DriverLicense: 'driver-license',
+    WorkPermit: 'work-permit',
+    StudyPermit: 'study-permit',
+});
+export const INDIVIDUAL_IDENTIFIER_KIND_CODES = Object.freeze({
+    [INDIVIDUAL_IDENTIFIER_KINDS.NationalPerson]: HL7_V2_0203_IDENTIFIER_CODES.NationalNumber,
+    [INDIVIDUAL_IDENTIFIER_KINDS.Passport]: HL7_V2_0203_IDENTIFIER_CODES.PassportNumber,
+    [INDIVIDUAL_IDENTIFIER_KINDS.HealthNumber]: HL7_V2_0203_IDENTIFIER_CODES.JurisdictionalHealthNumber,
+    [INDIVIDUAL_IDENTIFIER_KINDS.DriverLicense]: HL7_V2_0203_IDENTIFIER_CODES.DriverLicense,
+    [INDIVIDUAL_IDENTIFIER_KINDS.WorkPermit]: HL7_V2_0203_IDENTIFIER_CODES.WorkPermit,
+    [INDIVIDUAL_IDENTIFIER_KINDS.StudyPermit]: HL7_V2_0203_IDENTIFIER_CODES.StudyPermit,
+});
 export var IdKind;
 (function (IdKind) {
     /** ISO 18013-5 mobile driving licence credential. */
     IdKind["MobileDriverLicense"] = "org.iso.18013.5.1.mDL";
     /** HL7 driver license identifier. */
-    IdKind["PersonalDriverLicense"] = "org.hl7.terminology.codesystem.v2-0203.DL";
+    IdKind["PersonalDriverLicense"] = "org.hl7.terminology.CodeSystem.v2-0203.DL";
     /** HL7 citizenship card identifier. */
-    IdKind["PersonalCitizenshipCard"] = "org.hl7.terminology.codesystem.v2-0203.CZ";
+    IdKind["PersonalCitizenshipCard"] = "org.hl7.terminology.CodeSystem.v2-0203.CZ";
     /** HL7 national identity number. */
-    IdKind["PersonalNationalNumber"] = "org.hl7.terminology.codesystem.v2-0203.NN";
+    IdKind["PersonalNationalNumber"] = "org.hl7.terminology.CodeSystem.v2-0203.NN";
+    /** HL7 passport number. */
+    IdKind["PersonalPassportNumber"] = "org.hl7.terminology.CodeSystem.v2-0203.PPN";
     /** HL7 jurisdictional health number. */
-    IdKind["RegionalHeathCardNumber"] = "org.hl7.terminology.codesystem.v2-0203.JHN";
+    IdKind["RegionalHealthCardNumber"] = "org.hl7.terminology.CodeSystem.v2-0203.JHN";
+    /** @deprecated Use `RegionalHealthCardNumber`. */
+    IdKind["RegionalHeathCardNumber"] = "org.hl7.terminology.CodeSystem.v2-0203.JHN";
+    /** HL7 work permit. */
+    IdKind["PersonalWorkPermit"] = "org.hl7.terminology.CodeSystem.v2-0203.WP";
+    /** HL7 study permit. */
+    IdKind["PersonalStudyPermit"] = "org.hl7.terminology.CodeSystem.v2-0203.SP";
     /** HL7 local/private health card identifier. */
-    IdKind["LocalHealthCard"] = "org.hl7.terminology.codesystem.v2-0203.HC";
+    IdKind["LocalHealthCard"] = "org.hl7.terminology.CodeSystem.v2-0203.HC";
     /** HL7 donor record identifier. */
-    IdKind["LocalDonorRecord"] = "org.hl7.terminology.codesystem.v2-0203.DR";
+    IdKind["LocalDonorRecord"] = "org.hl7.terminology.CodeSystem.v2-0203.DR";
     /** HL7 local patient identifier. */
-    IdKind["LocalPatientIdentifier"] = "org.hl7.terminology.codesystem.v2-0203.PI";
+    IdKind["LocalPatientIdentifier"] = "org.hl7.terminology.CodeSystem.v2-0203.PI";
 })(IdKind || (IdKind = {}));
+export const HL7_V2_0203_REVERSE_DNS_TYPES = Object.freeze({
+    [HL7_V2_0203_IDENTIFIER_CODES.DriverLicense]: IdKind.PersonalDriverLicense,
+    [HL7_V2_0203_IDENTIFIER_CODES.CitizenshipCard]: IdKind.PersonalCitizenshipCard,
+    [HL7_V2_0203_IDENTIFIER_CODES.NationalNumber]: IdKind.PersonalNationalNumber,
+    [HL7_V2_0203_IDENTIFIER_CODES.PassportNumber]: IdKind.PersonalPassportNumber,
+    [HL7_V2_0203_IDENTIFIER_CODES.JurisdictionalHealthNumber]: IdKind.RegionalHealthCardNumber,
+    [HL7_V2_0203_IDENTIFIER_CODES.WorkPermit]: IdKind.PersonalWorkPermit,
+    [HL7_V2_0203_IDENTIFIER_CODES.StudyPermit]: IdKind.PersonalStudyPermit,
+    [HL7_V2_0203_IDENTIFIER_CODES.HealthCard]: IdKind.LocalHealthCard,
+    [HL7_V2_0203_IDENTIFIER_CODES.DonorRecord]: IdKind.LocalDonorRecord,
+    [HL7_V2_0203_IDENTIFIER_CODES.PatientIdentifier]: IdKind.LocalPatientIdentifier,
+});

package/dist/constants/schemaorg.d.ts

@@ -3,7 +3,9 @@ export declare enum ClaimsServiceSchemaorg {
     areaServed = "org.schema.Service.areaServed",
     additionalType = "org.schema.Service.additionalType",
     category = "org.schema.Service.category",
+    description = "org.schema.Service.description",
     identifier = "org.schema.Service.identifier",
+    name = "org.schema.Service.name",
     serviceType = "org.schema.Service.serviceType",
     termsOfService = "org.schema.Service.termsOfService",
     url = "org.schema.Service.url"
@@ -36,6 +38,8 @@ export declare enum ClaimsSoftwareApplicationSchemaorg {
  * based on Schema.org vocabulary.
  */
 export declare enum ClaimsOrganizationSchemaorg {
+    /** Public aliases used for exact organization or individual resolution. */
+    sameAs = "org.schema.Organization.sameAs",
     /** ISO 3166-1 alpha-2 (two-letter country code). The jurisdiction could be the country or the region (county, province or state) */
     addressCountry = "org.schema.Organization.address.addressCountry",
     /** ISO 3166-2 code for administrative divisions. The jurisdiction could be the country or the region (county, province or state) */

package/dist/constants/schemaorg.js

@@ -5,7 +5,9 @@ export var ClaimsServiceSchemaorg;
     ClaimsServiceSchemaorg["areaServed"] = "org.schema.Service.areaServed";
     ClaimsServiceSchemaorg["additionalType"] = "org.schema.Service.additionalType";
     ClaimsServiceSchemaorg["category"] = "org.schema.Service.category";
+    ClaimsServiceSchemaorg["description"] = "org.schema.Service.description";
     ClaimsServiceSchemaorg["identifier"] = "org.schema.Service.identifier";
+    ClaimsServiceSchemaorg["name"] = "org.schema.Service.name";
     ClaimsServiceSchemaorg["serviceType"] = "org.schema.Service.serviceType";
     ClaimsServiceSchemaorg["termsOfService"] = "org.schema.Service.termsOfService";
     ClaimsServiceSchemaorg["url"] = "org.schema.Service.url";
@@ -40,6 +42,8 @@ export var ClaimsSoftwareApplicationSchemaorg;
  */
 export var ClaimsOrganizationSchemaorg;
 (function (ClaimsOrganizationSchemaorg) {
+    /** Public aliases used for exact organization or individual resolution. */
+    ClaimsOrganizationSchemaorg["sameAs"] = "org.schema.Organization.sameAs";
     /** ISO 3166-1 alpha-2 (two-letter country code). The jurisdiction could be the country or the region (county, province or state) */
     ClaimsOrganizationSchemaorg["addressCountry"] = "org.schema.Organization.address.addressCountry";
     /** ISO 3166-2 code for administrative divisions. The jurisdiction could be the country or the region (county, province or state) */

package/dist/constants/urn.d.ts

@@ -7,5 +7,6 @@
  */
 export declare const UrnPrefixes: Readonly<{
     readonly JwkThumbprintSha256KeyId: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:";
+    readonly Multibase: "urn:multibase:";
 }>;
 export type UrnPrefix = typeof UrnPrefixes[keyof typeof UrnPrefixes];

package/dist/constants/urn.js

@@ -8,4 +8,5 @@
  */
 export const UrnPrefixes = Object.freeze({
     JwkThumbprintSha256KeyId: 'urn:ietf:params:oauth:jwk-thumbprint:sha-256:',
+    Multibase: 'urn:multibase:',
 });

package/dist/convert/index.d.ts

@@ -20,3 +20,4 @@ export * from './convert-encounter';
 export * from './convert-related-person';
 export * from './convert-coverage';
 export * from './convert-clinical-impression';
+export * from './schemaorg-to-gaia-x';

package/dist/convert/index.js

@@ -20,3 +20,4 @@ export * from './convert-encounter.js';
 export * from './convert-related-person.js';
 export * from './convert-coverage.js';
 export * from './convert-clinical-impression.js';
+export * from './schemaorg-to-gaia-x.js';

package/dist/convert/schemaorg-to-gaia-x.d.ts

@@ -0,0 +1,116 @@
+import type { ClaimsRecord } from '../models/resource-document';
+import { type GaiaXCredentialDraft, type GaiaXLegalPersonCredentialSubject, type GaiaXServiceOfferingCredentialSubject, type GaiaXVcJwtAttachment, type IcaMemberDiscoveryData } from '../models/gaia-x';
+import type { DidDocument } from '../models/did';
+export interface SchemaOrgOrganizationRegistrationIdentifier {
+    additionalType: string;
+    value: string;
+}
+/**
+ * Reads the canonical schema.org `PropertyValue` organization identifier.
+ * During migration it also accepts the historical nested
+ * `identifier.identifier` form. When the structure is absent, `taxID` becomes
+ * a VAT/TAX fallback, matching ICA's OrganizationCredential issuance rule.
+ */
+export declare function resolveSchemaOrgOrganizationRegistrationIdentifier(credentialSubject: Record<string, unknown>): SchemaOrgOrganizationRegistrationIdentifier;
+/**
+ * Converts canonical schema.org organization claims into an unsigned Gaia-X
+ * ICAM 25.11 LegalPerson VC draft.
+ *
+ * Semantic boundary:
+ * - Gaia-X `LegalPerson` is the juridical organization/legal entity. It is not
+ *   GDC's natural-person `LegalRepresentativeCredential`.
+ * - representative claims are intentionally never projected by this function.
+ * - VAT/tax remains in the source schema.org OrganizationCredential. Gaia-X's
+ *   `gx:legalRegistrationNumber` is a resolvable reference to the separate
+ *   registration/notary credential, not an assertion synthesized from VAT.
+ * - this function is deterministic and does not sign. The authoritative GW
+ *   signs the returned draft as VC-JWT; ICA caches and verifies that exact JWT.
+ *
+ * This projection targets the credential structure and semantic model described
+ * by Gaia-X ICAM 25.11. Passing the resulting shape tests neither Gaia-X policy
+ * compliance nor GXDCH/TCK conformance.
+ *
+ * @see https://docs.gaia-x.eu/technical-committee/identity-credential-access-management/25.11/gaia-x_credentials/
+ * @see https://docs.gaia-x.eu/technical-committee/identity-credential-access-management/25.11/semantic_model/
+ */
+export declare function buildGaiaXLegalPersonCredentialDraft(input: Readonly<{
+    claims: ClaimsRecord;
+    credentialId: string;
+    subjectId: string;
+    issuerId: string;
+    legalRegistrationNumberCredentialId: string;
+    validFrom: string;
+}>): GaiaXCredentialDraft<GaiaXLegalPersonCredentialSubject>;
+/**
+ * Projects an ICA/GDC schema.org OrganizationCredential into a Gaia-X
+ * LegalPerson draft while preserving the organization `credentialSubject.id`.
+ *
+ * The source VC and Gaia-X VC are different signed statements, so their
+ * credential IDs must not silently collide. By default the Gaia-X credential
+ * receives `<source credential id>#gaia-x-legal-person`; callers may provide a
+ * separately resolvable ID. `registrationIdentifier` is returned for the
+ * notary/GXDCH registration step, while `gx:legalRegistrationNumber` remains a
+ * reference to the resulting registration credential.
+ */
+export declare function buildGaiaXLegalPersonProjectionFromOrganizationCredential(input: Readonly<{
+    organizationCredential: Record<string, unknown>;
+    credentialId?: string;
+    issuerId: string;
+    legalRegistrationNumberCredentialId: string;
+    addressSubdivisionCode?: string;
+    addressCountryCode?: string;
+    validFrom: string;
+}>): Readonly<{
+    sourceCredentialId: string;
+    registrationIdentifier: SchemaOrgOrganizationRegistrationIdentifier;
+    credential: GaiaXCredentialDraft<GaiaXLegalPersonCredentialSubject>;
+}>;
+/**
+ * Converts schema.org service claims into an unsigned Gaia-X ServiceOffering
+ * VC draft. A service offering is independent from the participant credential:
+ * it references the LegalPerson credential through `gx:providedBy` and carries
+ * its own mandatory terms reference.
+ *
+ * The GW must sign this draft as a separate VC-JWT. A DCAT DataService is useful
+ * catalog metadata but is not a substitute for this credential.
+ */
+export declare function buildGaiaXServiceOfferingCredentialDraft(input: Readonly<{
+    claims: ClaimsRecord;
+    credentialId: string;
+    subjectId: string;
+    issuerId: string;
+    providedByCredentialId: string;
+    termsAndConditionsUrl: string;
+    termsAndConditionsHash: string;
+    validFrom: string;
+}>): GaiaXCredentialDraft<GaiaXServiceOfferingCredentialSubject>;
+/** Builds the mandatory first Gaia-X participant attachment for ICA discovery. */
+export declare function buildGaiaXParticipantAttachment(input: Readonly<{
+    id: string;
+    jwt: string;
+}>): GaiaXVcJwtAttachment;
+/** Wraps an exact signed Gaia-X VC-JWT without decoding or re-signing it. */
+export declare function buildGaiaXVcJwtAttachment(input: Readonly<{
+    id: string;
+    jwt: string;
+    role: GaiaXVcJwtAttachment['role'];
+}>): GaiaXVcJwtAttachment;
+/**
+ * Assembles one ICA member discovery entry and enforces the interoperable
+ * ordering contract: schema.org OrganizationCredential first in `vc[]`, and
+ * Gaia-X participant VC-JWT first in `attachments[]`.
+ *
+ * The caller owns signature verification and cache freshness. This helper does
+ * not derive or duplicate VAT outside `vc[]` and does not mutate signed data.
+ */
+export declare function buildIcaMemberDiscoveryData(input: Readonly<{
+    id: string;
+    vc: IcaMemberDiscoveryData['vc'];
+    did: {
+        document: DidDocument;
+        meta: IcaMemberDiscoveryData['did']['meta'];
+    };
+    attachments: GaiaXVcJwtAttachment[];
+    dcat?: IcaMemberDiscoveryData['dcat'];
+    meta?: IcaMemberDiscoveryData['meta'];
+}>): IcaMemberDiscoveryData;