gdc-common-utils-ts 2.8.8 → 2.9.0

package/README.md

@@ -427,7 +427,9 @@ The canonical API contract should live in JSDoc on exported code. The README act
     sections after six extensions, and the complete 82-section/classification
     catalog. The IPS document type lives separately in `HealthcareDocumentTypes`.
 - [`HealthcareConsentPurposes`, `HealthcareConsentActions`, `HealthcareActorRoles`, `HealthcareActorRoleCodes`](src/constants/healthcare.ts)
-  - Shared healthcare authorization and role constants.
+  - Shared healthcare authorization and role constants, including the
+    `health-lab`, `animal-lab`, and `onehealth-lab` sector catalogs. See
+    [Healthcare Roles and i18n 101](docs/101-HEALTHCARE_ROLES_I18N.md).
 - [`EXAMPLE_PROFESSIONAL_ACCESS_SCENARIOS`](src/examples/professional.ts)
   - Reusable professional role/permission examples tying actor role, consent action, SMART scope, and expected FHIR resource types together.
 - [`DeviceUserClasses`, `DeviceAppTypes`](src/constants/device.ts)
@@ -454,7 +456,7 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - do not teach its `entityId` as if it were the legal organization id
   - Derives the technical ML-DSA/ML-KEM communication identity for a device, portal, or app profile and returns JOSE header templates for `meta.jws.protected` and `meta.jwe.header`.
   - Uses explicit `seedMaterial` for deterministic derivation. Without `seedMaterial`, it defaults to random generation. `mode = deterministic` requires `seedMaterial`.
-- [`buildOrganizationDidWeb(...)`, `buildProfessionalDidWeb(...)`, `buildIndividualDidWeb(...)`](src/utils/did.ts)
+- [`buildOrganizationDidWeb(...)`, `buildProfessionalDidWeb(...)`, `buildIndividualDidWeb(...)`, `buildIndividualMemberDidWebFromPrivateIdentifiers(...)`](src/utils/did.ts)
   - Build canonical data-space `did:web` identifiers for hosted organizations, professionals, and individuals/family actors.
 - [`buildSmartCompositionReadScope(...)`](src/utils/smart-scope.ts)
   - Builds the current CORE GW pinned SMART root scope for `organization/Composition...` token requests.

package/dist/constants/healthcare.d.ts

@@ -1727,6 +1727,10 @@ export declare const HealthcareActorRoles: Readonly<{
     readonly MidwiferyProfessional: "ISCO-08|2222";
     readonly Paramedic: "ISCO-08|2240";
     readonly Veterinarian: "ISCO-08|2250";
+    /** ISCO-08 laboratory occupation for non-medical life-science work. */
+    readonly LifeScienceTechnician: "ISCO-08|3141";
+    /** ISCO-08 laboratory occupation for human medical/pathology work. */
+    readonly MedicalAndPathologyLaboratoryTechnician: "ISCO-08|3212";
     readonly VeterinaryTechnicianOrAssistant: "ISCO-08|3240";
     /** Administrative health occupation; it does not imply clinical authority. */
     readonly MedicalSecretary: "ISCO-08|3344";
@@ -1750,6 +1754,8 @@ export declare const HealthcareActorRoleCodes: Readonly<{
     readonly MidwiferyProfessional: "2222";
     readonly Paramedic: "2240";
     readonly Veterinarian: "2250";
+    readonly LifeScienceTechnician: "3141";
+    readonly MedicalAndPathologyLaboratoryTechnician: "3212";
     readonly VeterinaryTechnicianOrAssistant: "3240";
     readonly MedicalSecretary: "3344";
 }>;
@@ -1786,13 +1792,16 @@ export declare const HealthcareAllRolesByClaim: Readonly<Record<string, Healthca
 export declare const HealthcareProfessionalRoleCodesBySector: Readonly<{
     readonly "health-care": readonly ("RESPRSN" | "221" | "2211" | "2212" | "2221" | "2222" | "2240" | "3344")[];
     readonly "health-research": readonly ("RESPRSN" | "221" | "2211" | "2212" | "3344")[];
+    readonly "health-lab": readonly ("RESPRSN" | "221" | "2212" | "3212" | "3344")[];
     readonly "health-tech": readonly "RESPRSN"[];
     readonly "health-insurance": readonly "RESPRSN"[];
     readonly "animal-care": readonly ("RESPRSN" | "2250" | "3240")[];
     readonly "animal-research": readonly ("RESPRSN" | "2250" | "3240")[];
+    readonly "animal-lab": readonly ("RESPRSN" | "2250" | "3141" | "3240")[];
     readonly "animal-insurance": readonly "RESPRSN"[];
     readonly "animal-tech": readonly "RESPRSN"[];
     readonly "onehealth-research": readonly ("RESPRSN" | "221" | "2211" | "2212" | "2250" | "3240" | "3344")[];
+    readonly "onehealth-lab": readonly ("RESPRSN" | "221" | "2212" | "2250" | "3141" | "3212" | "3240" | "3344")[];
     readonly "onehealth-tech": readonly "RESPRSN"[];
 }>;
 export declare const HealthcareProfessionalRolesBySector: Readonly<{
@@ -1814,6 +1823,15 @@ export declare const HealthcareProfessionalRolesBySector: Readonly<{
         titleEn: string;
         definition?: string;
     }>>>;
+    readonly "health-lab": Readonly<Record<string, Readonly<{
+        family: HealthcareRoleFamily;
+        codingSystem: string;
+        code: string;
+        claim: string;
+        i18nKey: `org.ilo.isco-08.${string}` | `org.isco08.${string}` | `org.hl7.terminology.CodeSystem.v3-RoleCode.${string}`;
+        titleEn: string;
+        definition?: string;
+    }>>>;
     readonly "health-tech": Readonly<Record<string, Readonly<{
         family: HealthcareRoleFamily;
         codingSystem: string;
@@ -1850,6 +1868,15 @@ export declare const HealthcareProfessionalRolesBySector: Readonly<{
         titleEn: string;
         definition?: string;
     }>>>;
+    readonly "animal-lab": Readonly<Record<string, Readonly<{
+        family: HealthcareRoleFamily;
+        codingSystem: string;
+        code: string;
+        claim: string;
+        i18nKey: `org.ilo.isco-08.${string}` | `org.isco08.${string}` | `org.hl7.terminology.CodeSystem.v3-RoleCode.${string}`;
+        titleEn: string;
+        definition?: string;
+    }>>>;
     readonly "animal-insurance": Readonly<Record<string, Readonly<{
         family: HealthcareRoleFamily;
         codingSystem: string;
@@ -1877,6 +1904,15 @@ export declare const HealthcareProfessionalRolesBySector: Readonly<{
         titleEn: string;
         definition?: string;
     }>>>;
+    readonly "onehealth-lab": Readonly<Record<string, Readonly<{
+        family: HealthcareRoleFamily;
+        codingSystem: string;
+        code: string;
+        claim: string;
+        i18nKey: `org.ilo.isco-08.${string}` | `org.isco08.${string}` | `org.hl7.terminology.CodeSystem.v3-RoleCode.${string}`;
+        titleEn: string;
+        definition?: string;
+    }>>>;
     readonly "onehealth-tech": Readonly<Record<string, Readonly<{
         family: HealthcareRoleFamily;
         codingSystem: string;

package/dist/constants/healthcare.js

@@ -359,6 +359,10 @@ export const HealthcareActorRoles = Object.freeze({
     MidwiferyProfessional: 'ISCO-08|2222',
     Paramedic: 'ISCO-08|2240',
     Veterinarian: 'ISCO-08|2250',
+    /** ISCO-08 laboratory occupation for non-medical life-science work. */
+    LifeScienceTechnician: 'ISCO-08|3141',
+    /** ISCO-08 laboratory occupation for human medical/pathology work. */
+    MedicalAndPathologyLaboratoryTechnician: 'ISCO-08|3212',
     VeterinaryTechnicianOrAssistant: 'ISCO-08|3240',
     /** Administrative health occupation; it does not imply clinical authority. */
     MedicalSecretary: 'ISCO-08|3344',
@@ -382,6 +386,8 @@ export const HealthcareActorRoleCodes = Object.freeze({
     MidwiferyProfessional: '2222',
     Paramedic: '2240',
     Veterinarian: '2250',
+    LifeScienceTechnician: '3141',
+    MedicalAndPathologyLaboratoryTechnician: '3212',
     VeterinaryTechnicianOrAssistant: '3240',
     MedicalSecretary: '3344',
 });
@@ -464,6 +470,28 @@ function buildProfessionalIscoRoles() {
                 titleEn: 'Veterinarian',
             }),
         ],
+        [
+            HealthcareActorRoleCodes.LifeScienceTechnician,
+            Object.freeze({
+                family: HealthcareRoleFamilies.ProfessionalOccupationIsco08,
+                codingSystem: ISCO08_CODING_SYSTEM,
+                code: HealthcareActorRoleCodes.LifeScienceTechnician,
+                claim: HealthcareActorRoles.LifeScienceTechnician,
+                i18nKey: `${ISCO08_I18N_NAMESPACE}.${HealthcareActorRoleCodes.LifeScienceTechnician}`,
+                titleEn: 'Life science technician (excluding medical)',
+            }),
+        ],
+        [
+            HealthcareActorRoleCodes.MedicalAndPathologyLaboratoryTechnician,
+            Object.freeze({
+                family: HealthcareRoleFamilies.ProfessionalOccupationIsco08,
+                codingSystem: ISCO08_CODING_SYSTEM,
+                code: HealthcareActorRoleCodes.MedicalAndPathologyLaboratoryTechnician,
+                claim: HealthcareActorRoles.MedicalAndPathologyLaboratoryTechnician,
+                i18nKey: `${ISCO08_I18N_NAMESPACE}.${HealthcareActorRoleCodes.MedicalAndPathologyLaboratoryTechnician}`,
+                titleEn: 'Medical and pathology laboratory technician',
+            }),
+        ],
         [
             HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
             Object.freeze({
@@ -561,6 +589,13 @@ export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
         HealthcareActorRoleCodes.SpecialistMedicalPractitioner,
         HealthcareActorRoleCodes.MedicalSecretary,
     ]),
+    [DataspaceSectors.HealthLab]: Object.freeze([
+        HealthcareActorRoleCodes.Controller,
+        HealthcareActorRoleCodes.MedicalDoctors,
+        HealthcareActorRoleCodes.SpecialistMedicalPractitioner,
+        HealthcareActorRoleCodes.MedicalAndPathologyLaboratoryTechnician,
+        HealthcareActorRoleCodes.MedicalSecretary,
+    ]),
     [DataspaceSectors.HealthTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
     [DataspaceSectors.HealthInsurance]: Object.freeze([HealthcareActorRoleCodes.Controller]),
     [DataspaceSectors.AnimalCare]: Object.freeze([
@@ -573,6 +608,12 @@ export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
         HealthcareActorRoleCodes.Veterinarian,
         HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
     ]),
+    [DataspaceSectors.AnimalLab]: Object.freeze([
+        HealthcareActorRoleCodes.Controller,
+        HealthcareActorRoleCodes.Veterinarian,
+        HealthcareActorRoleCodes.LifeScienceTechnician,
+        HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
+    ]),
     [DataspaceSectors.AnimalInsurance]: Object.freeze([HealthcareActorRoleCodes.Controller]),
     [DataspaceSectors.AnimalTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
     [DataspaceSectors.OneHealthResearch]: Object.freeze([
@@ -584,18 +625,31 @@ export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
         HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
         HealthcareActorRoleCodes.MedicalSecretary,
     ]),
+    [DataspaceSectors.OneHealthLab]: Object.freeze([
+        HealthcareActorRoleCodes.Controller,
+        HealthcareActorRoleCodes.MedicalDoctors,
+        HealthcareActorRoleCodes.SpecialistMedicalPractitioner,
+        HealthcareActorRoleCodes.Veterinarian,
+        HealthcareActorRoleCodes.LifeScienceTechnician,
+        HealthcareActorRoleCodes.MedicalAndPathologyLaboratoryTechnician,
+        HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
+        HealthcareActorRoleCodes.MedicalSecretary,
+    ]),
     [DataspaceSectors.OneHealthTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
 });
 export const HealthcareProfessionalRolesBySector = Object.freeze({
     [DataspaceSectors.HealthCare]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthCare]),
     [DataspaceSectors.HealthResearch]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthResearch]),
+    [DataspaceSectors.HealthLab]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthLab]),
     [DataspaceSectors.HealthTech]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthTech]),
     [DataspaceSectors.HealthInsurance]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthInsurance]),
     [DataspaceSectors.AnimalCare]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalCare]),
     [DataspaceSectors.AnimalResearch]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalResearch]),
+    [DataspaceSectors.AnimalLab]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalLab]),
     [DataspaceSectors.AnimalInsurance]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalInsurance]),
     [DataspaceSectors.AnimalTech]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalTech]),
     [DataspaceSectors.OneHealthResearch]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.OneHealthResearch]),
+    [DataspaceSectors.OneHealthLab]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.OneHealthLab]),
     [DataspaceSectors.OneHealthTech]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.OneHealthTech]),
 });
 export const HealthcareProfessionalRolesBySectorAndClaim = Object.freeze(Object.fromEntries(Object.values(DataspaceSectors).map((sector) => [
@@ -614,7 +668,14 @@ export function getHealthcareRolesByFamily(family) {
     return HealthcareRolesByFamily[family];
 }
 export function getHealthcareRoleByClaim(claim) {
-    return HealthcareAllRolesByClaim[String(claim || '').trim()];
+    const normalized = String(claim || '').trim();
+    const direct = HealthcareAllRolesByClaim[normalized];
+    if (direct)
+        return direct;
+    const fullHl7Prefix = `${HL7_CODING_SYSTEM_V3_ROLE_CODE}|`;
+    return normalized.startsWith(fullHl7Prefix)
+        ? HealthcareAllRolesByClaim[`v3-RoleCode|${normalized.slice(fullHl7Prefix.length)}`]
+        : undefined;
 }
 export function getHealthcareProfessionalRolesBySector(sector) {
     return HealthcareProfessionalRolesBySector[sector] || {};

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

@@ -32,6 +32,31 @@ export declare const HL7_V2_0203_IDENTIFIER_CODES: Readonly<{
     readonly PatientIdentifier: "PI";
 }>;
 export type Hl7V20203IdentifierCode = typeof HL7_V2_0203_IDENTIFIER_CODES[keyof typeof HL7_V2_0203_IDENTIFIER_CODES];
+/**
+ * Identifier type tokens accepted by the hosted individual DID builders.
+ *
+ * `DL`, `PPN`, `NN`, and the other clinical identifier codes retain their
+ * HL7 v2-0203 meaning. `UUID`, `EMAIL`, and `PHONE` are GDC index identifier
+ * types and must not be described as HL7 codes.
+ */
+export declare const SecureIdTypesIndividual: 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 MemberNumber: "MB";
+    readonly SubscriberNumber: "SN";
+    readonly DonorRecord: "DR";
+    readonly PatientIdentifier: "PI";
+    readonly Uuid: "UUID";
+    readonly Email: "EMAIL";
+    readonly Phone: "PHONE";
+}>;
+export type SecureIdTypeIndividual = typeof SecureIdTypesIndividual[keyof typeof SecureIdTypesIndividual];
 /** Product-neutral document kinds used by subject identifier forms. */
 export declare const INDIVIDUAL_IDENTIFIER_KINDS: Readonly<{
     readonly NationalPerson: "national-person";

package/dist/constants/identity-identifiers.js

@@ -31,6 +31,19 @@ export const HL7_V2_0203_IDENTIFIER_CODES = Object.freeze({
     DonorRecord: 'DR',
     PatientIdentifier: 'PI',
 });
+/**
+ * Identifier type tokens accepted by the hosted individual DID builders.
+ *
+ * `DL`, `PPN`, `NN`, and the other clinical identifier codes retain their
+ * HL7 v2-0203 meaning. `UUID`, `EMAIL`, and `PHONE` are GDC index identifier
+ * types and must not be described as HL7 codes.
+ */
+export const SecureIdTypesIndividual = Object.freeze({
+    Uuid: 'UUID',
+    Email: 'EMAIL',
+    Phone: 'PHONE',
+    ...HL7_V2_0203_IDENTIFIER_CODES,
+});
 /** Product-neutral document kinds used by subject identifier forms. */
 export const INDIVIDUAL_IDENTIFIER_KINDS = Object.freeze({
     NationalPerson: 'national-person',

package/dist/constants/sectors.d.ts

@@ -11,14 +11,17 @@
  */
 export declare const DataspaceSectors: Readonly<{
     readonly HealthCare: "health-care";
+    readonly HealthLab: "health-lab";
     readonly HealthResearch: "health-research";
     readonly HealthTech: "health-tech";
     readonly HealthInsurance: "health-insurance";
     readonly AnimalCare: "animal-care";
+    readonly AnimalLab: "animal-lab";
     readonly AnimalResearch: "animal-research";
     readonly AnimalInsurance: "animal-insurance";
     readonly AnimalTech: "animal-tech";
     readonly OneHealthResearch: "onehealth-research";
+    readonly OneHealthLab: "onehealth-lab";
     readonly OneHealthTech: "onehealth-tech";
 }>;
 export type DataspaceSector = typeof DataspaceSectors[keyof typeof DataspaceSectors];

package/dist/constants/sectors.js

@@ -12,13 +12,16 @@
  */
 export const DataspaceSectors = Object.freeze({
     HealthCare: 'health-care',
+    HealthLab: 'health-lab',
     HealthResearch: 'health-research',
     HealthTech: 'health-tech',
     HealthInsurance: 'health-insurance',
     AnimalCare: 'animal-care',
+    AnimalLab: 'animal-lab',
     AnimalResearch: 'animal-research',
     AnimalInsurance: 'animal-insurance',
     AnimalTech: 'animal-tech',
     OneHealthResearch: 'onehealth-research',
+    OneHealthLab: 'onehealth-lab',
     OneHealthTech: 'onehealth-tech',
 });

package/dist/examples/shared.d.ts

@@ -149,6 +149,8 @@ export declare const EXAMPLE_PROVIDER_DOMAIN: "health-care.provider.example.org"
 /** Synthetic public portal domain used to derive organization path DIDs. */
 export declare const EXAMPLE_PUBLIC_PORTAL_DOMAIN: "portal.example.org";
 export declare const EXAMPLE_INDIVIDUAL_MULTIBASE_ID: string;
+/** Synthetic private UUID used to prove one-way hosted individual DID construction. */
+export declare const EXAMPLE_PRIVATE_INDIVIDUAL_UUID: "a87e5b15-aea4-4475-9c7c-40aa88354b6f";
 export declare const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_SECONDARY: string;
 export declare const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_TERTIARY: string;
 export declare const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_CONDITION: string;
@@ -212,7 +214,13 @@ export declare const EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN: "ISCO-08|2211";
 export declare const EXAMPLE_HEALTHCARE_ACTOR_ROLE_GENERALIST_MEDICAL_PRACTITIONER: "ISCO-08|2211";
 export declare const EXAMPLE_HEALTHCARE_ACTOR_ROLE_RECEPTIONIST: "ISCO-08|4226";
 export declare const EXAMPLE_HEALTHCARE_ROLE_PHYSICIAN_TEXT: "physician";
+export declare const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_TYPE = "http://terminology.hl7.org/CodeSystem/v3-RoleCode";
+export declare const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_VALUE: "RESPRSN";
 export declare const EXAMPLE_RELATED_PERSON_ROLE: "v3-RoleCode|RESPRSN";
+export declare const EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL: string;
+export declare const EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL_CONTROLLER: string;
+export declare const EXAMPLE_HOSTED_INDIVIDUAL_DID: string;
+export declare const EXAMPLE_HOSTED_INDIVIDUAL_CONTROLLER_DID: string;
 export declare const EXAMPLE_RELATED_PERSON_MEMBER_DID: string;
 export declare const EXAMPLE_CLINICAL_SECTION_RESULTS: "LOINC|30954-2";
 export declare const EXAMPLE_CLINICAL_SECTION_PATIENT_SUMMARY: "LOINC|60591-5";

package/dist/examples/shared.js

@@ -6,12 +6,13 @@ import { FhirCodeSystems } from '../constants/fhir-code-systems.js';
 import { Format } from '../constants/Schemas.js';
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
 import { BirthSex, GenderIdentity } from '../constants/identity-gender.js';
-import { IdKind } from '../constants/identity-identifiers.js';
+import { IdKind, SecureIdTypesIndividual } from '../constants/identity-identifiers.js';
+import { HL7_CODING_SYSTEM_V3_ROLE_CODE } from '../constants/hl7-roles.js';
 import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, HealthcareDocumentTypes, } from '../constants/healthcare.js';
 import { CommunicationCategoryCodes } from '../constants/communication.js';
 import { LOINC_SYSTEM_URL } from '../models/clinical-sections.js';
 import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
-import { buildHostedProviderDidWeb, buildIndividualDidWeb, buildIndividualMemberDidWeb, buildProfessionalDidWeb, buildProviderSectorDidWeb, } from '../utils/did.js';
+import { buildHostedProviderDidWeb, buildIndividualDidWeb, buildIndividualMemberDidWeb, buildSecureIdValueIndividual, buildSecureIdValueMember, buildProfessionalDidWeb, buildProviderSectorDidWeb, } from '../utils/did.js';
 import { encodeHexToMultibase58btc } from '../utils/multibase58.js';
 import { MedicationStatementClaim, MedicationStatementClaimsFhirApiExtended, } from '../models/interoperable-claims/medication-statement-claims.js';
 import { medicationStatementFlatToFhirR4 } from '../utils/clinical-resource-converters.js';
@@ -167,6 +168,8 @@ export const EXAMPLE_PROVIDER_DOMAIN = 'health-care.provider.example.org';
 /** Synthetic public portal domain used to derive organization path DIDs. */
 export const EXAMPLE_PUBLIC_PORTAL_DOMAIN = 'portal.example.org';
 export const EXAMPLE_INDIVIDUAL_MULTIBASE_ID = encodeHexToMultibase58btc('a87e5b15aea444759c7c40aa88354b6f');
+/** Synthetic private UUID used to prove one-way hosted individual DID construction. */
+export const EXAMPLE_PRIVATE_INDIVIDUAL_UUID = 'a87e5b15-aea4-4475-9c7c-40aa88354b6f';
 export const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_SECONDARY = encodeHexToMultibase58btc('b98f6c24bfb545849d8d51bb99465c7e');
 export const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_TERTIARY = encodeHexToMultibase58btc('c39f7d35c0c65695ae9e62cca0576d8f');
 export const EXAMPLE_INDIVIDUAL_MULTIBASE_ID_CONDITION = encodeHexToMultibase58btc('d4a08e46d1d767a6bfaf73ddb1687ea0');
@@ -251,7 +254,28 @@ export const EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN = HealthcareActorRoles.Phys
 export const EXAMPLE_HEALTHCARE_ACTOR_ROLE_GENERALIST_MEDICAL_PRACTITIONER = HealthcareActorRoles.GeneralistMedicalPractitioner;
 export const EXAMPLE_HEALTHCARE_ACTOR_ROLE_RECEPTIONIST = 'ISCO-08|4226';
 export const EXAMPLE_HEALTHCARE_ROLE_PHYSICIAN_TEXT = 'physician';
+export const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_TYPE = HL7_CODING_SYSTEM_V3_ROLE_CODE;
+export const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_VALUE = EXAMPLE_ORGANIZATION_CONTROLLER_ROLE;
 export const EXAMPLE_RELATED_PERSON_ROLE = 'v3-RoleCode|RESPRSN';
+export const EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL = buildSecureIdValueIndividual({
+    secureIdTypeIndividual: SecureIdTypesIndividual.Uuid,
+    privateIdValueIndividual: EXAMPLE_PRIVATE_INDIVIDUAL_UUID,
+});
+export const EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL_CONTROLLER = buildSecureIdValueMember({
+    secureIdTypeMember: SecureIdTypesIndividual.Email,
+    privateIdValueMember: EXAMPLE_EMAIL_CONTROLLER_INDIVIDUAL,
+});
+export const EXAMPLE_HOSTED_INDIVIDUAL_DID = buildIndividualDidWeb({
+    providerDidWeb: EXAMPLE_HOSTED_PROVIDER_DID,
+    secureIdTypeIndividual: SecureIdTypesIndividual.Uuid,
+    secureIdValueIndividual: EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL,
+});
+export const EXAMPLE_HOSTED_INDIVIDUAL_CONTROLLER_DID = buildIndividualMemberDidWeb({
+    individualDidWeb: EXAMPLE_HOSTED_INDIVIDUAL_DID,
+    memberId: EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL_CONTROLLER,
+    roleType: EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_TYPE,
+    roleValue: EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_VALUE,
+});
 export const EXAMPLE_RELATED_PERSON_MEMBER_DID = buildIndividualMemberDidWeb({
     individualDidWeb: EXAMPLE_SUBJECT_DID,
     role: EXAMPLE_RELATED_PERSON_ROLE,

package/dist/utils/did.d.ts

@@ -1,4 +1,5 @@
 import { ServiceEndpointSelector } from "../models/did";
+import { type SecureIdTypeIndividual } from '../constants/identity-identifiers';
 /**
  * Canonical DID path markers for hosted/provider individual identities.
  *
@@ -11,6 +12,19 @@ export declare const IndividualDidMarkers: {
     readonly Member: "member";
     readonly Role: "role";
 };
+export declare function buildSecureIdValueIndividual(input: {
+    secureIdTypeIndividual: SecureIdTypeIndividual | string;
+    privateIdValueIndividual: string;
+}): string;
+/**
+ * Builds the same SHA3-384 multihash path value for the private identifier of
+ * an individual member/controller. The member and represented individual
+ * remain distinct inputs even when both refer to the same natural person.
+ */
+export declare function buildSecureIdValueMember(input: {
+    secureIdTypeMember: SecureIdTypeIndividual | string;
+    privateIdValueMember: string;
+}): string;
 /**
  * Removes any coding-system prefix from a role claim when building a member DID.
  *
@@ -189,38 +203,71 @@ export declare function buildProfessionalDidWeb(input: {
  * Builds the canonical individual DID under either a hosted-provider DID root
  * or an external provider-sector DID root.
  *
- * Canonical supported forms:
- * - hosted:
- *   `did:web:<host.domain>:<sector>:organization:taxid:<provider-tax-id>:individual:multibase:<individualId>`
- * - external/provider-domain:
- *   `did:web:<sector.provider.domain>:individual:multibase:<individualId>`
+ * Canonical hosted form:
+ * `did:web:<provider-path>:individual:<secureIdTypeIndividual>:<secureIdValueIndividual>`
  *
  * Important semantics:
- * - `individualId` must be the canonical stable identity of the individual
- * - `individualId` should already be serialized in multibase form, typically
- *   `zBase58(UUID-bytes)`
- * - role is not part of the canonical individual DID; roles are only appended
- *   in member DIDs via `:member:role:<role-code-no-coding-system>`
+ * - the type remains an explicit upper-case path token such as `UUID`, `DL`,
+ *   `PPN`, `EMAIL`, or `PHONE`;
+ * - the value is always the one-way SHA3-384 multihash built by
+ *   `buildSecureIdValueIndividual`, never the private identifier in plain text;
+ * - role is not part of the individual DID.
  *
  * Backward-compatibility:
  * - `subjectId` is accepted as a legacy alias for `individualId`
  */
 export declare function buildIndividualDidWeb(input: {
     providerDidWeb: string;
+    secureIdTypeIndividual?: SecureIdTypeIndividual | string;
+    secureIdValueIndividual?: string;
+    /** @deprecated Use `secureIdTypeIndividual` plus `secureIdValueIndividual`. */
     individualId?: string;
+    /** @deprecated Use `secureIdTypeIndividual` plus `secureIdValueIndividual`. */
     subjectId?: string;
 }): string;
 /**
  * Builds the canonical member DID under an individual DID.
  *
  * Canonical form:
- * `did:web:...:individual:multibase:<individualId>:member:role:<role-code-no-coding-system>`
+ * `did:web:...:individual:<type>:<secure-value>:member:<secure-member-value>:<role-value>`
  *
- * The DID suffix intentionally strips coding-system prefixes because the DID is
- * a compact routing/identity string, while the full coded role still belongs in
- * the claims layer.
+ * `roleType` is mandatory input so callers cannot accidentally lose the coded
+ * role semantics. Only `roleValue` is serialized in the DID because the full
+ * FHIR token (`system|value`) remains in the protected claims/licence layer.
  */
 export declare function buildIndividualMemberDidWeb(input: {
     individualDidWeb: string;
-    role: string;
+    memberId?: string;
+    roleType?: string;
+    roleValue?: string;
+    /** @deprecated Use `roleType` plus `roleValue`. */
+    role?: string;
+}): string;
+/**
+ * Builds a complete hosted individual-member DID directly from the private
+ * identifiers already held by an authorized BFF.
+ *
+ * This is the integration helper for portals: the provider DID returned by GW,
+ * the individual's private UUID or other governed identifier, the logged-in
+ * member's email/phone/private identifier, and the protected role type/value
+ * are sufficient. Neither private identifier is serialized in the result.
+ */
+export declare function buildIndividualMemberDidWebFromPrivateIdentifiers(input: {
+    providerDidWeb: string;
+    secureIdTypeIndividual: SecureIdTypeIndividual | string;
+    privateIdValueIndividual: string;
+    secureIdTypeMember: SecureIdTypeIndividual | string;
+    privateIdValueMember: string;
+    roleType: string;
+    roleValue: string;
 }): string;
+/**
+ * Parses one hosted individual-member DID without interpreting its role value
+ * as authorization. The complete role system and value must still be checked
+ * against the protected licence or credential by the consuming gateway.
+ */
+export declare function parseIndividualMemberDidWeb(didWeb: string): {
+    individualDidWeb: string;
+    memberId: string;
+    roleValue: string;
+};

package/dist/utils/did.js

@@ -1,6 +1,9 @@
 // crypto-ts/utils/did.ts
 // Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { multibase58MultihashSha3_256 } from './same-as.js';
+import { SecureIdTypesIndividual, } from '../constants/identity-identifiers.js';
+import { normalizePhone } from './consent.js';
+import { encodeMultibaseSha3 } from './multibasehash.js';
 /**
  * Canonical DID path markers for hosted/provider individual identities.
  *
@@ -13,6 +16,63 @@ export const IndividualDidMarkers = {
     Member: 'member',
     Role: 'role',
 };
+const UUID_VALUE_PATTERN = /^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$/i;
+const MULTIBASE_SHA3_384_PATTERN = /^z[1-9A-HJ-NP-Za-km-z]+$/;
+/**
+ * Builds the privacy-preserving value used by a hosted individual DID.
+ *
+ * Wire profile: `multibase(base58btc(multihash(SHA3-384, canonical-bytes)))`.
+ * The returned value is the bare `z...` path token, not an
+ * `urn:multibase:...` value and not a CID.
+ *
+ * Canonical inputs:
+ * - `UUID`: remove hyphens, interpret the 32 hexadecimal digits as the UUID's
+ *   canonical 16 bytes, then hash those bytes;
+ * - `EMAIL`: remove `mailto:`, whitespace and letter-case differences;
+ * - `PHONE`: remove `tel:` and normalize the number through the shared phone
+ *   normalizer (including its E.164 leading `+` when supplied);
+ * - HL7 v2-0203 and other governed private identifiers: NFKC-normalized,
+ *   trimmed, upper-case UTF-8 text. Their type and jurisdiction remain
+ *   separate governed fields and are never inferred from the value.
+ */
+function buildSecureIdValue(typeInput, valueInput, context) {
+    const type = String(typeInput || '').trim().toUpperCase();
+    const rawValue = String(valueInput || '').trim();
+    if (!type)
+        throw new Error(`${context} requires a secure identifier type.`);
+    if (!rawValue)
+        throw new Error(`${context} requires a private identifier value.`);
+    if (type === SecureIdTypesIndividual.Uuid) {
+        if (!UUID_VALUE_PATTERN.test(rawValue)) {
+            throw new Error(`${context} requires a hexadecimal UUID value.`);
+        }
+        const hex = rawValue.replace(/-/g, '').toLowerCase();
+        const bytes = new Uint8Array(16);
+        for (let index = 0; index < bytes.length; index += 1) {
+            bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+        }
+        return encodeMultibaseSha3(bytes, 384);
+    }
+    const canonicalText = type === SecureIdTypesIndividual.Email
+        ? rawValue.replace(/^mailto:/i, '').replace(/\s+/g, '').toLowerCase()
+        : type === SecureIdTypesIndividual.Phone
+            ? normalizePhone(rawValue.replace(/^tel:/i, ''))
+            : rawValue.normalize('NFKC').toUpperCase();
+    if (!canonicalText)
+        throw new Error(`${context} requires a valid ${type} value.`);
+    return encodeMultibaseSha3(canonicalText, 384);
+}
+export function buildSecureIdValueIndividual(input) {
+    return buildSecureIdValue(input.secureIdTypeIndividual, input.privateIdValueIndividual, 'buildSecureIdValueIndividual');
+}
+/**
+ * Builds the same SHA3-384 multihash path value for the private identifier of
+ * an individual member/controller. The member and represented individual
+ * remain distinct inputs even when both refer to the same natural person.
+ */
+export function buildSecureIdValueMember(input) {
+    return buildSecureIdValue(input.secureIdTypeMember, input.privateIdValueMember, 'buildSecureIdValueMember');
+}
 /**
  * Removes any coding-system prefix from a role claim when building a member DID.
  *
@@ -334,27 +394,40 @@ export function buildProfessionalDidWeb(input) {
  * Builds the canonical individual DID under either a hosted-provider DID root
  * or an external provider-sector DID root.
  *
- * Canonical supported forms:
- * - hosted:
- *   `did:web:<host.domain>:<sector>:organization:taxid:<provider-tax-id>:individual:multibase:<individualId>`
- * - external/provider-domain:
- *   `did:web:<sector.provider.domain>:individual:multibase:<individualId>`
+ * Canonical hosted form:
+ * `did:web:<provider-path>:individual:<secureIdTypeIndividual>:<secureIdValueIndividual>`
  *
  * Important semantics:
- * - `individualId` must be the canonical stable identity of the individual
- * - `individualId` should already be serialized in multibase form, typically
- *   `zBase58(UUID-bytes)`
- * - role is not part of the canonical individual DID; roles are only appended
- *   in member DIDs via `:member:role:<role-code-no-coding-system>`
+ * - the type remains an explicit upper-case path token such as `UUID`, `DL`,
+ *   `PPN`, `EMAIL`, or `PHONE`;
+ * - the value is always the one-way SHA3-384 multihash built by
+ *   `buildSecureIdValueIndividual`, never the private identifier in plain text;
+ * - role is not part of the individual DID.
  *
  * Backward-compatibility:
  * - `subjectId` is accepted as a legacy alias for `individualId`
  */
 export function buildIndividualDidWeb(input) {
     const providerDidWeb = String(input.providerDidWeb || '').trim();
+    const secureIdTypeIndividual = String(input.secureIdTypeIndividual || '').trim().toUpperCase();
+    const secureIdValueIndividual = String(input.secureIdValueIndividual || '').trim();
     const individualId = String(input.individualId || input.subjectId || '').trim();
     if (!providerDidWeb)
         throw new Error('buildIndividualDidWeb requires providerDidWeb.');
+    if (secureIdTypeIndividual || secureIdValueIndividual) {
+        if (!secureIdTypeIndividual || !secureIdValueIndividual) {
+            throw new Error('buildIndividualDidWeb requires both secure individual id type and value.');
+        }
+        if (!MULTIBASE_SHA3_384_PATTERN.test(secureIdValueIndividual)) {
+            throw new Error('buildIndividualDidWeb requires secureIdValueIndividual as bare multibase base58btc.');
+        }
+        return [
+            providerDidWeb,
+            IndividualDidMarkers.Individual,
+            secureIdTypeIndividual,
+            secureIdValueIndividual,
+        ].join(':');
+    }
     if (!individualId)
         throw new Error('buildIndividualDidWeb requires individualId.');
     return [
@@ -368,20 +441,83 @@ export function buildIndividualDidWeb(input) {
  * Builds the canonical member DID under an individual DID.
  *
  * Canonical form:
- * `did:web:...:individual:multibase:<individualId>:member:role:<role-code-no-coding-system>`
+ * `did:web:...:individual:<type>:<secure-value>:member:<secure-member-value>:<role-value>`
  *
- * The DID suffix intentionally strips coding-system prefixes because the DID is
- * a compact routing/identity string, while the full coded role still belongs in
- * the claims layer.
+ * `roleType` is mandatory input so callers cannot accidentally lose the coded
+ * role semantics. Only `roleValue` is serialized in the DID because the full
+ * FHIR token (`system|value`) remains in the protected claims/licence layer.
  */
 export function buildIndividualMemberDidWeb(input) {
     const individualDidWeb = String(input.individualDidWeb || '').trim();
     if (!individualDidWeb)
         throw new Error('buildIndividualMemberDidWeb requires individualDidWeb.');
+    const memberId = String(input.memberId || '').trim();
+    const roleType = String(input.roleType || '').trim();
+    const roleValue = String(input.roleValue || '').trim();
+    if (memberId || roleType || roleValue) {
+        if (!MULTIBASE_SHA3_384_PATTERN.test(memberId)) {
+            throw new Error('buildIndividualMemberDidWeb requires memberId as bare multibase base58btc.');
+        }
+        if (!roleType || !roleValue) {
+            throw new Error('buildIndividualMemberDidWeb requires both roleType and roleValue.');
+        }
+        return [individualDidWeb, IndividualDidMarkers.Member, memberId, roleValue].join(':');
+    }
     return [
         individualDidWeb,
         IndividualDidMarkers.Member,
         IndividualDidMarkers.Role,
-        toDidMemberRoleCode(input.role),
+        toDidMemberRoleCode(String(input.role || '')),
     ].join(':');
 }
+/**
+ * Builds a complete hosted individual-member DID directly from the private
+ * identifiers already held by an authorized BFF.
+ *
+ * This is the integration helper for portals: the provider DID returned by GW,
+ * the individual's private UUID or other governed identifier, the logged-in
+ * member's email/phone/private identifier, and the protected role type/value
+ * are sufficient. Neither private identifier is serialized in the result.
+ */
+export function buildIndividualMemberDidWebFromPrivateIdentifiers(input) {
+    const individualDidWeb = buildIndividualDidWeb({
+        providerDidWeb: input.providerDidWeb,
+        secureIdTypeIndividual: input.secureIdTypeIndividual,
+        secureIdValueIndividual: buildSecureIdValueIndividual({
+            secureIdTypeIndividual: input.secureIdTypeIndividual,
+            privateIdValueIndividual: input.privateIdValueIndividual,
+        }),
+    });
+    return buildIndividualMemberDidWeb({
+        individualDidWeb,
+        memberId: buildSecureIdValueMember({
+            secureIdTypeMember: input.secureIdTypeMember,
+            privateIdValueMember: input.privateIdValueMember,
+        }),
+        roleType: input.roleType,
+        roleValue: input.roleValue,
+    });
+}
+/**
+ * Parses one hosted individual-member DID without interpreting its role value
+ * as authorization. The complete role system and value must still be checked
+ * against the protected licence or credential by the consuming gateway.
+ */
+export function parseIndividualMemberDidWeb(didWeb) {
+    const candidate = String(didWeb || '').trim();
+    const marker = `:${IndividualDidMarkers.Member}:`;
+    const markerOffset = candidate.lastIndexOf(marker);
+    if (!candidate.startsWith('did:web:') || markerOffset < 0) {
+        throw new Error('Invalid hosted individual member DID.');
+    }
+    const individualDidWeb = candidate.slice(0, markerOffset);
+    const suffix = candidate.slice(markerOffset + marker.length).split(':');
+    const [memberId, roleValue, ...unexpected] = suffix;
+    if (!individualDidWeb.includes(`:${IndividualDidMarkers.Individual}:`)
+        || unexpected.length > 0
+        || !MULTIBASE_SHA3_384_PATTERN.test(String(memberId || ''))
+        || !String(roleValue || '').trim()) {
+        throw new Error('Invalid hosted individual member DID.');
+    }
+    return { individualDidWeb, memberId, roleValue };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.8.8",
+  "version": "2.9.0",
   "publishConfig": {
     "access": "public"
   },