gdc-common-utils-ts 2.3.5 → 2.3.7

package/README.md

@@ -59,6 +59,10 @@ boundaries used in `gdc-common-utils-ts`.
 - Only define custom names when no canonical FHIR SearchParameter exists.
 - `resource.meta.claims` is the canonical project-specific claims container and must be preserved across conversions/transports.
 - `resource.meta.claims` is not part of base FHIR; it is a claims-first extension carried by FHIR-like resources in GDC contracts.
+- Native FHIR resources received from EHR systems do not need that extension:
+  normalize them with `normalizeClaimsFromFhirResource(...)` at the processing
+  boundary before indexed storage. Existing `resource.meta.claims` take
+  precedence so SDK-authored semantics survive transport conversion.
 
 ## Identity Continuity
 

package/dist/convert/convert-allergy-intolerance.js

@@ -17,6 +17,9 @@ export function allergyIntoleranceFlatToFhirR4(claims) {
         code: claims[AllergyIntoleranceClaim.Code] ? { coding: codingFromValue(claims[AllergyIntoleranceClaim.Code]) } : undefined,
         clinicalStatus: claims[AllergyIntoleranceClaim.ClinicalStatus] ? { coding: [{ code: claims[AllergyIntoleranceClaim.ClinicalStatus] }] } : undefined,
         verificationStatus: claims[AllergyIntoleranceClaim.VerificationStatus] ? { coding: [{ code: claims[AllergyIntoleranceClaim.VerificationStatus] }] } : undefined,
+        category: claims[AllergyIntoleranceClaim.Category] ? [claims[AllergyIntoleranceClaim.Category]] : undefined,
+        criticality: claims[AllergyIntoleranceClaim.Criticality],
+        onsetDateTime: claims[AllergyIntoleranceClaim.OnsetDateTime],
         recorder: recorder ? { reference: recorder } : undefined,
     };
 }
@@ -30,6 +33,9 @@ export function allergyIntoleranceFhirR4ToFlat(resource) {
         [AllergyIntoleranceClaim.Code]: codingToValue(code?.coding?.[0]) || code?.text,
         [AllergyIntoleranceClaim.ClinicalStatus]: resource.clinicalStatus?.coding?.[0]?.code,
         [AllergyIntoleranceClaim.VerificationStatus]: resource.verificationStatus?.coding?.[0]?.code,
+        [AllergyIntoleranceClaim.Category]: resource.category?.[0],
+        [AllergyIntoleranceClaim.Criticality]: resource.criticality,
+        [AllergyIntoleranceClaim.OnsetDateTime]: resource.onsetDateTime,
         [AllergyIntoleranceClaim.Recorder]: resource.recorder?.reference,
     };
 }

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

@@ -1,5 +1,5 @@
 import type { ClaimsRecord } from '../models/resource-document';
-import { type GaiaXCredentialDraft, type GaiaXLegalPersonCredentialSubject, type GaiaXServiceOfferingCredentialSubject, type GaiaXVcJwtAttachment, type IcaMemberDiscoveryData } from '../models/gaia-x';
+import { type GaiaXCredentialAttachmentRoleValue, 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;
@@ -94,6 +94,27 @@ export declare function buildGaiaXVcJwtAttachment(input: Readonly<{
     jwt: string;
     role: GaiaXVcJwtAttachment['role'];
 }>): GaiaXVcJwtAttachment;
+/**
+ * Enforces the semantic contract of a signed Gaia-X discovery VC-JWT.
+ *
+ * This assertion deliberately does not verify the cryptographic signature.
+ * Signature, issuer, status and trust-chain verification remain the verifier's
+ * responsibility. It prevents a validly shaped schema.org
+ * OrganizationCredential from being merely serialized as JWT and mislabeled
+ * as the distinct Gaia-X participant credential.
+ *
+ * Participant attachments require `gx:LegalPerson` with the ICAM 25.11 legal
+ * properties. Service-offering attachments require `gx:ServiceOffering`,
+ * `gx:providedBy` and `gx:serviceOfferingTermsAndConditions`.
+ *
+ * This validates member-level `data[].attachments[]`; it does not describe
+ * `_retrieve?format=vc+jwt` or credential-internal
+ * `credential.evidence[].attachments`.
+ *
+ * @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 assertGaiaXDiscoveryAttachmentSemantics(jwt: string, role: GaiaXCredentialAttachmentRoleValue): void;
 /**
  * Assembles one ICA member discovery entry and enforces the interoperable
  * ordering contract: schema.org OrganizationCredential first in `vc[]`, and

package/dist/convert/schemaorg-to-gaia-x.js

@@ -174,14 +174,90 @@ export function buildGaiaXParticipantAttachment(input) {
 }
 /** Wraps an exact signed Gaia-X VC-JWT without decoding or re-signing it. */
 export function buildGaiaXVcJwtAttachment(input) {
+    const jwt = requiredInput(input.jwt, 'VC-JWT');
+    assertGaiaXDiscoveryAttachmentSemantics(jwt, input.role);
     return {
         id: requiredInput(input.id, 'attachment id'),
         format: GaiaXCredentialAttachmentFormat,
         role: input.role,
         media_type: GaiaXCredentialMediaType.VcJwt,
-        data: { json: { jwt: requiredInput(input.jwt, 'VC-JWT') } },
+        data: { json: { jwt } },
     };
 }
+function decodeVcJwtCredential(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3 || parts.some((part) => !part)) {
+        throw new Error('Gaia-X attachment must contain one compact three-part VC-JWT.');
+    }
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error('Gaia-X attachment VC-JWT payload is not valid base64url JSON.');
+    }
+    return asObject(payload.vc) || payload;
+}
+function gaiaXCredentialSubject(document) {
+    const raw = document.credentialSubject;
+    if (Array.isArray(raw)) {
+        return raw.map(asObject).find((value) => Boolean(value));
+    }
+    return asObject(raw);
+}
+function requireGaiaXProperties(subject, names, role) {
+    const missing = names.filter((name) => !(name in subject));
+    if (missing.length) {
+        throw new Error(`Gaia-X ${role} VC-JWT is missing required semantic properties: ${missing.join(', ')}.`);
+    }
+}
+/**
+ * Enforces the semantic contract of a signed Gaia-X discovery VC-JWT.
+ *
+ * This assertion deliberately does not verify the cryptographic signature.
+ * Signature, issuer, status and trust-chain verification remain the verifier's
+ * responsibility. It prevents a validly shaped schema.org
+ * OrganizationCredential from being merely serialized as JWT and mislabeled
+ * as the distinct Gaia-X participant credential.
+ *
+ * Participant attachments require `gx:LegalPerson` with the ICAM 25.11 legal
+ * properties. Service-offering attachments require `gx:ServiceOffering`,
+ * `gx:providedBy` and `gx:serviceOfferingTermsAndConditions`.
+ *
+ * This validates member-level `data[].attachments[]`; it does not describe
+ * `_retrieve?format=vc+jwt` or credential-internal
+ * `credential.evidence[].attachments`.
+ *
+ * @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 function assertGaiaXDiscoveryAttachmentSemantics(jwt, role) {
+    const document = decodeVcJwtCredential(jwt);
+    const subject = gaiaXCredentialSubject(document);
+    if (!subject)
+        throw new Error(`Gaia-X ${role} VC-JWT requires one credentialSubject object.`);
+    const subjectType = asString(subject.type);
+    if (role === GaiaXCredentialAttachmentRole.Participant) {
+        if (subjectType !== 'gx:LegalPerson') {
+            throw new Error('Gaia-X participant VC-JWT credentialSubject.type must be gx:LegalPerson.');
+        }
+        requireGaiaXProperties(subject, [
+            'gx:legalName',
+            'gx:legalRegistrationNumber',
+            'gx:headquarterAddress',
+            'gx:legalAddress',
+        ], 'participant');
+    }
+    if (role === GaiaXCredentialAttachmentRole.ServiceOffering) {
+        if (subjectType !== 'gx:ServiceOffering') {
+            throw new Error('Gaia-X service-offering VC-JWT credentialSubject.type must be gx:ServiceOffering.');
+        }
+        requireGaiaXProperties(subject, [
+            'gx:providedBy',
+            'gx:serviceOfferingTermsAndConditions',
+        ], 'service-offering');
+    }
+}
 /**
  * Assembles one ICA member discovery entry and enforces the interoperable
  * ordering contract: schema.org OrganizationCredential first in `vc[]`, and

package/dist/examples/individual-controller.d.ts

@@ -88,9 +88,7 @@ export declare const EXAMPLE_CONSENT_GRANT_INPUT: {
 };
 export declare const EXAMPLE_LIVE_CONSENT_GRANT_INPUT: {
     readonly subjectDid: string;
-    readonly actor: {
-        readonly identifier: "did:web:api.acme.org";
-    };
+    readonly actorId: string;
     readonly actorRole: "ISCO-08|2211";
     readonly purpose: "TREAT";
     readonly actions: readonly [string];

package/dist/examples/individual-controller.js

@@ -1,5 +1,5 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-import { EXAMPLE_CONTROLLER_DID, EXAMPLE_API_ORGANIZATION_DID, EXAMPLE_CLINICAL_CODE_PROBLEM, EXAMPLE_CLINICAL_DATE_RANGE, EXAMPLE_CLINICAL_SECTION_ALLERGIES, EXAMPLE_CLINICAL_SECTION_PATIENT_SUMMARY, EXAMPLE_CONSENT_PURPOSE_TREATMENT, EXAMPLE_EMAIL_CONTROLLER_INDIVIDUAL, EXAMPLE_GENERIC_SUBJECT_DID, EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN, EXAMPLE_HEALTHCARE_JURISDICTION, EXAMPLE_HEALTHCARE_ROLE_PHYSICIAN_TEXT, EXAMPLE_PRACTITIONER_DID, EXAMPLE_PROFESSIONAL_DID, EXAMPLE_SUBJECT_DID, EXAMPLE_FORM_CONTROLLER_PHONE, } from './shared.js';
+import { EXAMPLE_CONTROLLER_DID, EXAMPLE_CLINICAL_CODE_PROBLEM, EXAMPLE_CLINICAL_DATE_RANGE, EXAMPLE_CLINICAL_SECTION_ALLERGIES, EXAMPLE_CLINICAL_SECTION_PATIENT_SUMMARY, EXAMPLE_CONSENT_PURPOSE_TREATMENT, EXAMPLE_EMAIL_CONTROLLER_INDIVIDUAL, EXAMPLE_GENERIC_SUBJECT_DID, EXAMPLE_HEALTHCARE_ACTOR_ROLE_GENERALIST_MEDICAL_PRACTITIONER, EXAMPLE_HEALTHCARE_JURISDICTION, EXAMPLE_HEALTHCARE_ROLE_PHYSICIAN_TEXT, EXAMPLE_PRACTITIONER_DID, EXAMPLE_PROFESSIONAL_DID, EXAMPLE_SUBJECT_DID, EXAMPLE_FORM_CONTROLLER_PHONE, } from './shared.js';
 export const EXAMPLE_INDIVIDUAL_ORGANIZATION_START_INPUT = {
     alternateName: 'ana',
     controllerEmail: EXAMPLE_EMAIL_CONTROLLER_INDIVIDUAL,
@@ -57,8 +57,8 @@ export const EXAMPLE_CONSENT_GRANT_INPUT = {
 };
 export const EXAMPLE_LIVE_CONSENT_GRANT_INPUT = {
     subjectDid: EXAMPLE_SUBJECT_DID,
-    actor: { identifier: EXAMPLE_API_ORGANIZATION_DID },
-    actorRole: EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN,
+    actorId: EXAMPLE_PROFESSIONAL_DID,
+    actorRole: EXAMPLE_HEALTHCARE_ACTOR_ROLE_GENERALIST_MEDICAL_PRACTITIONER,
     purpose: EXAMPLE_CONSENT_PURPOSE_TREATMENT,
     actions: [EXAMPLE_CLINICAL_SECTION_ALLERGIES],
 };

package/dist/examples/professional.d.ts

@@ -75,36 +75,36 @@ export declare const EXAMPLE_SEARCH_CLINICAL_BUNDLE_INPUT: {
  *
  * - use `EXAMPLE_TOKEN_EXCHANGE_SMART_INPUT` or `EXAMPLE_OPENID_SMART_TOKEN_INPUT`
  *   for the first read-only examples
- * - use the scenarios below when you explicitly want the composition read scope
- *   plus `organization/Consent.cruds`
+ * - do not append `organization/Consent.cruds` to a clinical read unless a
+ *   separate rule explicitly grants that resource capability
  */
 export declare const EXAMPLE_PROFESSIONAL_ACCESS_SCENARIOS: Readonly<{
     readonly physicianAllergiesRead: {
         readonly actorRole: "ISCO-08|2211";
         readonly purpose: "TREAT";
         readonly consentActions: readonly [string];
-        readonly smartScopes: readonly [string, "organization/Consent.cruds"];
+        readonly smartScopes: readonly [string];
         readonly includedTypes: readonly ["Composition", "AllergyIntolerance", "DocumentReference"];
     };
     readonly nursingMedicationRead: {
         readonly actorRole: "ISCO-08|2221";
         readonly purpose: "TREAT";
         readonly consentActions: readonly [string];
-        readonly smartScopes: readonly [string, "organization/Consent.cruds"];
+        readonly smartScopes: readonly [string];
         readonly includedTypes: readonly ["Composition", "MedicationStatement", "DocumentReference"];
     };
     readonly paramedicEmergencySummaryRead: {
         readonly actorRole: "ISCO-08|2240";
         readonly purpose: "ETREAT";
         readonly consentActions: readonly [string];
-        readonly smartScopes: readonly [string, "organization/Consent.cruds"];
+        readonly smartScopes: readonly [string];
         readonly includedTypes: readonly ["Composition", "DocumentReference", "Observation"];
     };
     readonly physicianResultsAndProblemsRead: {
         readonly actorRole: "ISCO-08|2211";
         readonly purpose: "TREAT";
         readonly consentActions: readonly [string, string];
-        readonly smartScopes: readonly [string, "organization/Consent.cruds"];
+        readonly smartScopes: readonly [string];
         readonly includedTypes: readonly ["Composition", "Condition", "DiagnosticReport", "DocumentReference"];
     };
 }>;

package/dist/examples/professional.js

@@ -1,7 +1,6 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, } from '../constants/healthcare.js';
+import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentActions, HealthcareConsentPurposes, } from '../constants/healthcare.js';
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
-import { SmartGatewayScopesFhirR4 } from '../constants/smart.js';
 import { buildSmartCompositionReadScope } from '../utils/smart-scope.js';
 import { EXAMPLE_CLINICAL_SECTION_ALLERGIES, EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_HEALTHCARE_JURISDICTION, EXAMPLE_PATIENT_DID, EXAMPLE_PROVIDER_ORGANIZATION_URL, EXAMPLE_SUBJECT_DID, } from './shared.js';
 /**
@@ -12,7 +11,7 @@ import { EXAMPLE_CLINICAL_SECTION_ALLERGIES, EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE
  * - the actor role of the professional (`Physician`, `NursingProfessional`, ...)
  * - the consented action/section over an individual subject
  * - the SMART scope ultimately requested against GW CORE
- * - the difference between a minimal read scope and an elevated consent-management scope
+ * - a read scope containing only capabilities covered by the consent
  *
  * This differs from organization-controller and individual-owner bootstrap
  * examples, where the main concern is identity/bootstrap rather than
@@ -28,10 +27,6 @@ const EXAMPLE_CANONICAL_SMART_READ_SCOPES = [
         sections: EXAMPLE_CLINICAL_SECTION_ALLERGIES,
     }),
 ];
-const EXAMPLE_CANONICAL_SMART_SCOPES = [
-    ...EXAMPLE_CANONICAL_SMART_READ_SCOPES,
-    SmartGatewayScopesFhirR4.ConsentCruds,
-];
 export const EXAMPLE_TOKEN_EXCHANGE_SMART_INPUT = {
     idToken: 'employee-id-token-001',
     scopes: [...EXAMPLE_CANONICAL_SMART_READ_SCOPES],
@@ -99,20 +94,19 @@ export const EXAMPLE_SEARCH_CLINICAL_BUNDLE_INPUT = {
  *
  * - use `EXAMPLE_TOKEN_EXCHANGE_SMART_INPUT` or `EXAMPLE_OPENID_SMART_TOKEN_INPUT`
  *   for the first read-only examples
- * - use the scenarios below when you explicitly want the composition read scope
- *   plus `organization/Consent.cruds`
+ * - do not append `organization/Consent.cruds` to a clinical read unless a
+ *   separate rule explicitly grants that resource capability
  */
 export const EXAMPLE_PROFESSIONAL_ACCESS_SCENARIOS = Object.freeze({
     physicianAllergiesRead: {
-        actorRole: HealthcareActorRoles.Physician,
+        actorRole: HealthcareActorRoles.GeneralistMedicalPractitioner,
         purpose: HealthcareConsentPurposes.Treatment,
-        consentActions: [HealthcareBasicSections.AllergiesAndIntolerances.claim],
+        consentActions: [HealthcareConsentActions.AllergiesAndIntolerances],
         smartScopes: [
             buildSmartCompositionReadScope({
                 subjectDid: EXAMPLE_SMART_SUBJECT_DID,
-                sections: HealthcareBasicSections.AllergiesAndIntolerances.claim,
+                sections: HealthcareConsentActions.AllergiesAndIntolerances,
             }),
-            SmartGatewayScopesFhirR4.ConsentCruds,
         ],
         includedTypes: [
             ResourceTypesFhirR4.Composition,
@@ -129,7 +123,6 @@ export const EXAMPLE_PROFESSIONAL_ACCESS_SCENARIOS = Object.freeze({
                 subjectDid: EXAMPLE_SMART_SUBJECT_DID,
                 sections: HealthcareBasicSections.HistoryOfMedicationUse.claim,
             }),
-            SmartGatewayScopesFhirR4.ConsentCruds,
         ],
         includedTypes: [
             ResourceTypesFhirR4.Composition,
@@ -146,7 +139,6 @@ export const EXAMPLE_PROFESSIONAL_ACCESS_SCENARIOS = Object.freeze({
                 subjectDid: EXAMPLE_SMART_SUBJECT_DID,
                 sections: HealthcareBasicSections.PatientSummaryDocument.claim,
             }),
-            SmartGatewayScopesFhirR4.ConsentCruds,
         ],
         includedTypes: [
             ResourceTypesFhirR4.Composition,
@@ -155,7 +147,7 @@ export const EXAMPLE_PROFESSIONAL_ACCESS_SCENARIOS = Object.freeze({
         ],
     },
     physicianResultsAndProblemsRead: {
-        actorRole: HealthcareActorRoles.Physician,
+        actorRole: HealthcareActorRoles.GeneralistMedicalPractitioner,
         purpose: HealthcareConsentPurposes.Treatment,
         consentActions: [
             HealthcareBasicSections.Results.claim,
@@ -169,7 +161,6 @@ export const EXAMPLE_PROFESSIONAL_ACCESS_SCENARIOS = Object.freeze({
                     HealthcareBasicSections.ProblemList.claim,
                 ],
             }),
-            SmartGatewayScopesFhirR4.ConsentCruds,
         ],
         includedTypes: [
             ResourceTypesFhirR4.Composition,
@@ -190,7 +181,6 @@ function buildConsentDecisionScenario(params) {
                 subjectDid: EXAMPLE_SMART_SUBJECT_DID,
                 sections: params.requestedSections,
             }),
-            SmartGatewayScopesFhirR4.ConsentCruds,
         ],
         includedTypes: [...params.includedTypes],
         expectedSmartTokenDecision: params.expectedSmartTokenDecision,
@@ -210,4 +200,115 @@ function buildConsentDecisionScenario(params) {
  * consent state + actor target + role + purpose + requested scope.
  */
 export const EXAMPLE_PROFESSIONAL_CONSENT_SCENARIOS = Object.freeze({
-    physicianB
+    physicianByEmailContinuousCareAllergiesAllowed: buildConsentDecisionScenario({
+        actorId: EXAMPLE_PHYSICIAN_EMAIL,
+        actorRole: HealthcareActorRoles.GeneralistMedicalPractitioner,
+        purpose: HealthcareConsentPurposes.Treatment,
+        consentActions: [HealthcareBasicSections.AllergiesAndIntolerances.claim],
+        requestedSections: HealthcareBasicSections.AllergiesAndIntolerances.claim,
+        includedTypes: [
+            ResourceTypesFhirR4.Composition,
+            ResourceTypesFhirR4.AllergyIntolerance,
+            ResourceTypesFhirR4.DocumentReference,
+        ],
+        expectedSmartTokenDecision: 'allowed',
+        reason: 'physician is targeted directly by email and role for continuous care over allergies section',
+    }),
+    physicianByEmailEmergencySummaryAllowed: buildConsentDecisionScenario({
+        actorId: EXAMPLE_PHYSICIAN_EMAIL,
+        actorRole: HealthcareActorRoles.GeneralistMedicalPractitioner,
+        purpose: HealthcareConsentPurposes.EmergencyTreatment,
+        consentActions: [HealthcareBasicSections.PatientSummaryDocument.claim],
+        requestedSections: HealthcareBasicSections.PatientSummaryDocument.claim,
+        includedTypes: [
+            ResourceTypesFhirR4.Composition,
+            ResourceTypesFhirR4.DocumentReference,
+            ResourceTypesFhirR4.Observation,
+        ],
+        expectedSmartTokenDecision: 'allowed',
+        reason: 'physician is targeted directly by email and role for emergency summary access',
+    }),
+    physicianByOrganizationResultsAllowed: buildConsentDecisionScenario({
+        actorId: { organizationUrl: EXAMPLE_PROVIDER_ORG_URL },
+        actorRole: HealthcareActorRoles.GeneralistMedicalPractitioner,
+        purpose: HealthcareConsentPurposes.Treatment,
+        consentActions: [HealthcareBasicSections.Results.claim],
+        requestedSections: HealthcareBasicSections.Results.claim,
+        includedTypes: [
+            ResourceTypesFhirR4.Composition,
+            ResourceTypesFhirR4.DiagnosticReport,
+            ResourceTypesFhirR4.DocumentReference,
+        ],
+        expectedSmartTokenDecision: 'allowed',
+        reason: 'consent is granted to a physician role within a given organization for continuous care results access',
+    }),
+    physicianByJurisdictionEmergencySummaryAllowed: buildConsentDecisionScenario({
+        actorId: EXAMPLE_JURISDICTION,
+        actorRole: HealthcareActorRoles.GeneralistMedicalPractitioner,
+        purpose: HealthcareConsentPurposes.EmergencyTreatment,
+        consentActions: [HealthcareBasicSections.PatientSummaryDocument.claim],
+        requestedSections: HealthcareBasicSections.PatientSummaryDocument.claim,
+        includedTypes: [
+            ResourceTypesFhirR4.Composition,
+            ResourceTypesFhirR4.DocumentReference,
+            ResourceTypesFhirR4.Observation,
+        ],
+        expectedSmartTokenDecision: 'allowed',
+        reason: 'consent is granted at jurisdiction level for physician emergency access',
+    }),
+    nursingByOrganizationMedicationHistoryAllowed: buildConsentDecisionScenario({
+        actorId: { organizationUrl: EXAMPLE_PROVIDER_ORG_URL },
+        actorRole: HealthcareActorRoles.NursingProfessional,
+        purpose: HealthcareConsentPurposes.Treatment,
+        consentActions: [HealthcareBasicSections.HistoryOfMedicationUse.claim],
+        requestedSections: HealthcareBasicSections.HistoryOfMedicationUse.claim,
+        includedTypes: [
+            ResourceTypesFhirR4.Composition,
+            ResourceTypesFhirR4.MedicationStatement,
+            ResourceTypesFhirR4.DocumentReference,
+        ],
+        expectedSmartTokenDecision: 'allowed',
+        reason: 'nursing professional is allowed to read medication history for treatment through organization-scoped consent',
+    }),
+    paramedicByJurisdictionEmergencySummaryAllowed: buildConsentDecisionScenario({
+        actorId: EXAMPLE_JURISDICTION,
+        actorRole: HealthcareActorRoles.Paramedic,
+        purpose: HealthcareConsentPurposes.EmergencyTreatment,
+        consentActions: [HealthcareBasicSections.PatientSummaryDocument.claim],
+        requestedSections: HealthcareBasicSections.PatientSummaryDocument.claim,
+        includedTypes: [
+            ResourceTypesFhirR4.Composition,
+            ResourceTypesFhirR4.DocumentReference,
+            ResourceTypesFhirR4.Observation,
+        ],
+        expectedSmartTokenDecision: 'allowed',
+        reason: 'paramedic receives emergency-only jurisdiction-scoped access to patient summary',
+    }),
+    physicianObstetricianDeniedWhenOnlyAllergiesConsent: buildConsentDecisionScenario({
+        actorId: EXAMPLE_PHYSICIAN_EMAIL,
+        actorRole: `${HealthcareActorRoles.GeneralistMedicalPractitioner}:obstetrician`,
+        purpose: HealthcareConsentPurposes.Treatment,
+        consentActions: [HealthcareBasicSections.AllergiesAndIntolerances.claim],
+        requestedSections: HealthcareBasicSections.Results.claim,
+        includedTypes: [
+            ResourceTypesFhirR4.Composition,
+            ResourceTypesFhirR4.DiagnosticReport,
+            ResourceTypesFhirR4.DocumentReference,
+        ],
+        expectedSmartTokenDecision: 'denied',
+        reason: 'requested SMART scope targets results but active consent only covers allergies section',
+    }),
+    physicianByEmailDeniedWhenConsentRevokedAndNoOrgNorJurisdictionConsentIsActive: buildConsentDecisionScenario({
+        actorId: EXAMPLE_PHYSICIAN_EMAIL,
+        actorRole: HealthcareActorRoles.GeneralistMedicalPractitioner,
+        purpose: HealthcareConsentPurposes.EmergencyTreatment,
+        consentActions: [HealthcareBasicSections.PatientSummaryDocument.claim],
+        requestedSections: HealthcareBasicSections.PatientSummaryDocument.claim,
+        includedTypes: [
+            ResourceTypesFhirR4.Composition,
+            ResourceTypesFhirR4.DocumentReference,
+        ],
+        expectedSmartTokenDecision: 'denied',
+        reason: 'matching consent rule existed before but is no longer active after controller deactivation/revocation',
+    }),
+});

package/dist/examples/shared.js

@@ -128,7 +128,7 @@ export const EXAMPLE_SERVICE_PUBLIC_DID = 'did:web:public.acme.org';
 export const EXAMPLE_PROFESSIONAL_DID = buildProfessionalDidWeb({
     organizationDidWeb: 'did:web:api.acme.org',
     email: 'doctor.oncall@example.org',
-    role: HealthcareActorRoles.Physician,
+    role: HealthcareActorRoles.GeneralistMedicalPractitioner,
 });
 export const EXAMPLE_PROVIDER_ORGANIZATION_DID = 'did:web:hospital.acme.org';
 export const EXAMPLE_PROVIDER_ORGANIZATION_URL = 'https://hospital.acme.org';

package/dist/models/indexing.js

@@ -193,7 +193,7 @@ export function buildIndexParametersFromClaims(claims, allowedClaims) {
         const parameter = {
             name: claimKey,
             value: value,
-            type: inferPa     type: inferParameterTypeFromClaimKey(claimKey, rawValue),
+            type: inferParameterTypeFromClaimKey(claimKey, rawValue),
             ...(claimKey === ObservationClaim.ValueQuantityUnit && typeof rawValue === 'string'
                 ? { unit: rawValue }
                 : {}),

package/dist/utils/bundle-reader.js

@@ -136,7 +136,13 @@ export class BundleReader {
         }
         const entries = this.getEntries();
         for (let index = 0; index < entries.length; index += 1) {
-            if (this.resolveEntryIdentifier(entries[index]) === normalizedIdentifier) {
+            const resource = asRecord(entries[index].resource);
+            const resourceType = asNonEmptyString(resource.resourceType) || 'resource';
+            const candidates = new Set([
+                ...this.resolveEntryReferenceCandidates(entries[index]),
+                `${resourceType}#${index}`,
+            ]);
+            if (candidates.has(normalizedIdentifier)) {
                 return index;
             }
         }

package/dist/utils/did.d.ts

@@ -148,7 +148,13 @@ export declare function buildOrganizationDidWeb(input: {
 /**
  * Builds a professional/member DID under a hosted organization DID.
  *
- * The stable actor identifier is derived from the email using multibase(base58btc(multihash(sha384))).
+ * The stable actor path identifier is derived from the lower-cased email using
+ * multibase(base58btc(multihash(SHA3-256))). The raw email is never embedded
+ * in the DID.
+ *
+ * This is the same multibase payload used by the ICA-compatible credential
+ * `sameAs`; only the representation differs: the DID path uses `z...` and the
+ * credential alias uses `urn:multibase:z...`.
  *
  * @param input.organizationDidWeb Canonical hosted organization DID.
  * @param input.email Professional email used to derive a stable member identifier.

package/dist/utils/did.js

@@ -1,6 +1,6 @@
 // crypto-ts/utils/did.ts
 // Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
-import { encodeMultibaseSha384 } from './multibasehash.js';
+import { multibase58MultihashSha3_256 } from './same-as.js';
 /**
  * Canonical DID path markers for hosted/provider individual identities.
  *
@@ -240,7 +240,13 @@ export function buildOrganizationDidWeb(input) {
 /**
  * Builds a professional/member DID under a hosted organization DID.
  *
- * The stable actor identifier is derived from the email using multibase(base58btc(multihash(sha384))).
+ * The stable actor path identifier is derived from the lower-cased email using
+ * multibase(base58btc(multihash(SHA3-256))). The raw email is never embedded
+ * in the DID.
+ *
+ * This is the same multibase payload used by the ICA-compatible credential
+ * `sameAs`; only the representation differs: the DID path uses `z...` and the
+ * credential alias uses `urn:multibase:z...`.
  *
  * @param input.organizationDidWeb Canonical hosted organization DID.
  * @param input.email Professional email used to derive a stable member identifier.
@@ -254,7 +260,7 @@ export function buildProfessionalDidWeb(input) {
         throw new Error('buildProfessionalDidWeb requires email.');
     if (!role)
         throw new Error('buildProfessionalDidWeb requires role.');
-    const memberId = encodeMultibaseSha384(normalizedEmail);
+    const memberId = multibase58MultihashSha3_256(normalizedEmail);
     return [
         String(input.organizationDidWeb).trim(),
         'employee',

package/dist/utils/professional-smart.d.ts

@@ -29,6 +29,10 @@ export type ProfessionalSmartVpPayloadInput = Readonly<{
  * - otherwise the public employee email
  *
  * When both are present they are merged and deduplicated after normalization.
+ * Plain emails become ICA-compatible
+ * `urn:multibase:<base58btc(multihash(SHA3-256))>` values. The multibase
+ * payload is the same value used in the professional DID actor path; `sameAs`
+ * adds only the `urn:multibase:` prefix.
  *
  * @param input Professional identity source values.
  */

package/dist/utils/professional-smart.js

@@ -11,6 +11,10 @@ import { buildUnsignedVpJwt } from './jwt.js';
  * - otherwise the public employee email
  *
  * When both are present they are merged and deduplicated after normalization.
+ * Plain emails become ICA-compatible
+ * `urn:multibase:<base58btc(multihash(SHA3-256))>` values. The multibase
+ * payload is the same value used in the professional DID actor path; `sameAs`
+ * adds only the `urn:multibase:` prefix.
  *
  * @param input Professional identity source values.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "publishConfig": {
     "access": "public"
   },
@@ -19,7 +19,10 @@
     "test": "jest",
     "test:coverage": "jest --coverage",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "build": "tsc -p tsconfig.build.json && node patch-esm-imports.mjs",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node patch-esm-imports.mjs",
+    "verify:dist": "node scripts/verify-dist-syntax.mjs",
+    "prepack": "npm run verify:dist",
     "prepublishOnly": "npm run typecheck && npm test -- --watchman=false && npm run build"
   },
   "main": "./dist/index.js",

package/dist/utils/clinical-resource-filter-editor.d.ts

@@ -1,39 +0,0 @@
-import type { BundleResourceDateFilter, BundleResourceIdFilters } from './bundle-query';
-/**
- * Canonical high-level filter accepted by both Bundle section readers and
- * `FhirDocumentFacade`.
- */
-export type ClinicalResourceFilter = Readonly<{
-    sections?: string[];
-    types?: string[];
-    date?: BundleResourceDateFilter;
-}>;
-/**
- * Chainable editor for one clinical document resource filter.
- *
- * The built value can be passed unchanged to:
- *
- * - `BundleReader.getDocumentSectionResourceIds(...)`
- * - `BundleReader.getDocumentSectionResourceEntries(...)`
- * - `FhirDocumentFacade.getResourcesByFilter(...)`
- * - `FhirDocumentFacade.getResourceCount(...)`
- */
-export declare class ClinicalResourceFilterEditor {
-    private sections?;
-    private types?;
-    private date?;
-    /** Replaces the selected Composition sections. An empty list means all. */
-    setSections(values: readonly string[]): this;
-    /** Replaces the selected FHIR resource types. An empty list means all. */
-    setTypes(values: readonly string[]): this;
-    /** Sets the complete clinical date interval. Either boundary may be omitted. */
-    setPeriod(start?: string, end?: string): this;
-    /** Sets or clears only the start boundary of the clinical date interval. */
-    setPeriodStart(start?: string): this;
-    /** Sets or clears only the end boundary of the clinical date interval. */
-    setPeriodEnd(end?: string): this;
-    /** Removes both clinical date boundaries. */
-    clearPeriod(): this;
-    /** Returns a detached canonical filter safe for either public reader. */
-    build(): ClinicalResourceFilter & BundleResourceIdFilters;
-}

package/dist/utils/clinical-resource-filter-editor.js

@@ -1,84 +0,0 @@
-// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-/**
- * Chainable editor for one clinical document resource filter.
- *
- * The built value can be passed unchanged to:
- *
- * - `BundleReader.getDocumentSectionResourceIds(...)`
- * - `BundleReader.getDocumentSectionResourceEntries(...)`
- * - `FhirDocumentFacade.getResourcesByFilter(...)`
- * - `FhirDocumentFacade.getResourceCount(...)`
- */
-export class ClinicalResourceFilterEditor {
-    sections;
-    types;
-    date;
-    /** Replaces the selected Composition sections. An empty list means all. */
-    setSections(values) {
-        this.sections = normalizeTokens(values);
-        return this;
-    }
-    /** Replaces the selected FHIR resource types. An empty list means all. */
-    setTypes(values) {
-        this.types = normalizeTokens(values);
-        return this;
-    }
-    /** Sets the complete clinical date interval. Either boundary may be omitted. */
-    setPeriod(start, end) {
-        this.date = buildDateFilter(start, end);
-        return this;
-    }
-    /** Sets or clears only the start boundary of the clinical date interval. */
-    setPeriodStart(start) {
-        this.date = buildDateFilter(start, this.date?.end);
-        return this;
-    }
-    /** Sets or clears only the end boundary of the clinical date interval. */
-    setPeriodEnd(end) {
-        this.date = buildDateFilter(this.date?.start, end);
-        return this;
-    }
-    /** Removes both clinical date boundaries. */
-    clearPeriod() {
-        this.date = undefined;
-        return this;
-    }
-    /** Returns a detached canonical filter safe for either public reader. */
-    build() {
-        return {
-            ...(this.sections?.length ? { sections: [...this.sections] } : {}),
-            ...(this.types?.length ? { types: [...this.types] } : {}),
-            ...(this.date ? { date: { ...this.date } } : {}),
-        };
-    }
-}
-function normalizeTokens(values) {
-    const normalized = [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))];
-    return normalized.length ? normalized : undefined;
-}
-function buildDateFilter(start, end) {
-    const normalizedStart = normalizeDate(start, 'start');
-    const normalizedEnd = normalizeDate(end, 'end');
-    if (normalizedStart && normalizedEnd) {
-        if (Date.parse(normalizedStart) > Date.parse(normalizedEnd)) {
-            throw new RangeError('Clinical resource filter period start must not be after end.');
-        }
-    }
-    if (!normalizedStart && !normalizedEnd) {
-        return undefined;
-    }
-    return {
-        ...(normalizedStart ? { start: normalizedStart } : {}),
-        ...(normalizedEnd ? { end: normalizedEnd } : {}),
-    };
-}
-function normalizeDate(value, boundary) {
-    const normalized = String(value || '').trim();
-    if (!normalized) {
-        return undefined;
-    }
-    if (!Number.isFinite(Date.parse(normalized))) {
-        throw new TypeError(`Clinical resource filter period ${boundary} must be a valid date.`);
-    }
-    return normalized;
-}