gdc-common-utils-ts 2.6.4 → 2.7.1

package/README.md

@@ -59,6 +59,11 @@ It is intentionally not a full backend orchestration layer.
 - 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.
+- Claims-first aggregates may intentionally mix related resource families. A
+  Digital Twin `ResearchSubject.meta.claims` contains both `ResearchSubject.*`
+  and `Composition.*`; strict FHIR R4/R5 translates the Composition into
+  `ResearchSubject.contained[]`. Producers never invent a
+  `ResearchSubject.composition` wire property.
 - 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
@@ -147,6 +152,7 @@ entry types, FHIR-like resources, and `resource.meta.claims` fit together,
 read first:
 
 - [`docs/101-ID_TOKEN.md`](docs/101-ID_TOKEN.md)
+- [`docs/101-DIDCOMM-IDENTITY-BOUNDARY.md`](docs/101-DIDCOMM-IDENTITY-BOUNDARY.md)
 - [`docs/101-COMMUNICATION_LAYERING.md`](docs/101-COMMUNICATION_LAYERING.md)
 - [`docs/101-BUNDLE_EDITOR_READER.md`](docs/101-BUNDLE_EDITOR_READER.md)
 - [`docs/101-CLINICAL-IPS.md`](docs/101-CLINICAL-IPS.md)

package/dist/constants/didcomm.d.ts

@@ -10,6 +10,7 @@ export declare const DidcommMessageTypes: Readonly<{
     readonly CommunicationAttachedBundle: "Communication-attached-bundle-v1.0";
     readonly CommunicationBundleSubmit: "Communication-bundle-submit-v1.0";
     readonly CommunicationResponse: "Communication-response-v1.0";
+    readonly SmartTokenRequest: "Smart-token-request-v1.0";
 }>;
 /**
  * Canonical low-level DIDComm acknowledgement body keys used in shared tests

package/dist/constants/didcomm.js

@@ -10,6 +10,7 @@ export const DidcommMessageTypes = Object.freeze({
     CommunicationAttachedBundle: 'Communication-attached-bundle-v1.0',
     CommunicationBundleSubmit: 'Communication-bundle-submit-v1.0',
     CommunicationResponse: 'Communication-response-v1.0',
+    SmartTokenRequest: 'Smart-token-request-v1.0',
 });
 /**
  * Canonical low-level DIDComm acknowledgement body keys used in shared tests

package/dist/examples/didcomm-identity.d.ts

@@ -0,0 +1,23 @@
+import type { IDecodedDidcommPayload } from '../models/confidential-message';
+/** Signing verification method controlled by the direct actor DID. */
+export declare const EXAMPLE_DIRECT_ACTOR_SIGNING_KEY_ID: `${string}#communication-signing`;
+/** Signing verification method registered for the DCR client/device. */
+export declare const EXAMPLE_DCR_DEVICE_SIGNING_KEY_ID: "did:web:device-001#dcr-signing";
+/**
+ * Canonical direct DIDComm/FAPI message.
+ *
+ * `from` and `iss` identify the same direct sender. `kid` identifies the
+ * concrete signing key and therefore remains in the signed JWS header. The
+ * FHIR-like Communication stays inside `body`; transport identity never
+ * becomes a FHIR field.
+ */
+export declare const EXAMPLE_DIRECT_ACTOR_DIDCOMM_MESSAGE: IDecodedDidcommPayload;
+/**
+ * Canonical device-bound SMART request.
+ *
+ * The DCR client/device is the DIDComm/FAPI sender and issuer because it signs
+ * the request. Its registered `kid` selects the proof key. SMART `sub`
+ * separately identifies the professional actor and `scope` separately limits
+ * the subject data requested by that actor.
+ */
+export declare const EXAMPLE_DEVICE_BOUND_SMART_DIDCOMM_MESSAGE: IDecodedDidcommPayload;

package/dist/examples/didcomm-identity.js

@@ -0,0 +1,65 @@
+import { DidcommMessageTypes } from '../constants/didcomm.js';
+import { buildSmartCompositionReadScope } from '../utils/smart-scope.js';
+import { EXAMPLE_DEVICE_CLIENT_ID, EXAMPLE_HOSTING_OPERATOR_DID, EXAMPLE_PROFESSIONAL_DID, EXAMPLE_SUBJECT_DID, buildExampleCommunicationIngestionPayload, } from './shared.js';
+/** Signing verification method controlled by the direct actor DID. */
+export const EXAMPLE_DIRECT_ACTOR_SIGNING_KEY_ID = `${EXAMPLE_PROFESSIONAL_DID}#communication-signing`;
+/** Signing verification method registered for the DCR client/device. */
+export const EXAMPLE_DCR_DEVICE_SIGNING_KEY_ID = `${EXAMPLE_DEVICE_CLIENT_ID}#dcr-signing`;
+/**
+ * Canonical direct DIDComm/FAPI message.
+ *
+ * `from` and `iss` identify the same direct sender. `kid` identifies the
+ * concrete signing key and therefore remains in the signed JWS header. The
+ * FHIR-like Communication stays inside `body`; transport identity never
+ * becomes a FHIR field.
+ */
+export const EXAMPLE_DIRECT_ACTOR_DIDCOMM_MESSAGE = {
+    meta: {
+        jws: {
+            protected: {
+                alg: 'ES384',
+                kid: EXAMPLE_DIRECT_ACTOR_SIGNING_KEY_ID,
+                typ: 'JWT',
+                cty: 'application/didcomm-signed+json',
+            },
+        },
+    },
+    iss: EXAMPLE_PROFESSIONAL_DID,
+    from: EXAMPLE_PROFESSIONAL_DID,
+    aud: EXAMPLE_HOSTING_OPERATOR_DID,
+    jti: 'urn:uuid:didcomm-direct-example',
+    thid: 'didcomm-direct-example',
+    type: DidcommMessageTypes.CommunicationAttachedBundle,
+    body: buildExampleCommunicationIngestionPayload().body,
+};
+/**
+ * Canonical device-bound SMART request.
+ *
+ * The DCR client/device is the DIDComm/FAPI sender and issuer because it signs
+ * the request. Its registered `kid` selects the proof key. SMART `sub`
+ * separately identifies the professional actor and `scope` separately limits
+ * the subject data requested by that actor.
+ */
+export const EXAMPLE_DEVICE_BOUND_SMART_DIDCOMM_MESSAGE = {
+    meta: {
+        jws: {
+            protected: {
+                alg: 'ES384',
+                kid: EXAMPLE_DCR_DEVICE_SIGNING_KEY_ID,
+                typ: 'JWT',
+                cty: 'application/didcomm-signed+json',
+            },
+        },
+    },
+    iss: EXAMPLE_DEVICE_CLIENT_ID,
+    from: EXAMPLE_DEVICE_CLIENT_ID,
+    aud: EXAMPLE_HOSTING_OPERATOR_DID,
+    jti: 'urn:uuid:didcomm-smart-example',
+    thid: 'didcomm-smart-example',
+    type: DidcommMessageTypes.SmartTokenRequest,
+    body: {
+        client_id: EXAMPLE_DEVICE_CLIENT_ID,
+        sub: EXAMPLE_PROFESSIONAL_DID,
+        scope: buildSmartCompositionReadScope({ subjectDid: EXAMPLE_SUBJECT_DID }),
+    },
+};

package/dist/examples/index.d.ts

@@ -30,3 +30,4 @@ export * from './ips-bundle';
 export * from './vital-signs';
 export * from './wallet-mem';
 export * from './profile-manager-mem';
+export * from './didcomm-identity';

package/dist/examples/index.js

@@ -30,3 +30,4 @@ export * from './ips-bundle.js';
 export * from './vital-signs.js';
 export * from './wallet-mem.js';
 export * from './profile-manager-mem.js';
+export * from './didcomm-identity.js';

package/dist/examples/shared.d.ts

@@ -661,7 +661,7 @@ export declare function buildExampleCommunicationIngestionPayload({ subjectDid,
                 }[];
                 meta: {
                     claims: {
-                        '@context': "org.hl7.fhir.r4";
+                        '@context': "org.hl7.fhir.api";
                         "Communication.category": string;
                         "Communication.subject": string;
                         "Communication.sent": string;

package/dist/examples/shared.js

@@ -640,7 +640,9 @@ export function buildExampleCommunicationIngestionPayload({ subjectDid = EXAMPLE
                         note: [{ text: EXAMPLE_IPS_BUNDLE_NOTE_TEXT }],
                         meta: {
                             claims: {
-                                '@context': Format.FHIR_R4,
+                                // The surrounding resource is native FHIR R4, while flat
+                                // claims remain version-neutral and can later render as R4 or R5.
+                                '@context': Format.FHIR_API,
                                 [CommunicationClaim.Category]: CommunicationCategoryCodes.Notification.claim,
                                 [CommunicationClaim.Subject]: subjectDid,
                                 [CommunicationClaim.Sent]: sent,

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

@@ -43,8 +43,11 @@ export interface IDecodedDidcommPayload {
     /** Relevant information available through the decryption and verification process */
     meta?: DidCommDecodedMetadata;
     /**
-     * (Issuer) The DID of the entity that issued the message.
-     * REQUIRED for FAPI. MUST match the signer of the enclosing JWS.
+     * (Issuer) DID of the entity that issued and signed the message.
+     * REQUIRED for FAPI. It MUST be bound to the signer of the enclosing JWS.
+     * The signing key is identified separately by `meta.jws.protected.kid`;
+     * `iss` is never the key id. For a DCR-bound client this is normally the
+     * client/device DID, while a SMART human actor remains in `body.sub`.
      */
     iss: string;
     /**
@@ -71,7 +74,13 @@ export interface IDecodedDidcommPayload {
     pthid?: string;
     /** The DID of the intended recipient. Used for P2P messaging, informational in client-server requests. */
     to?: string[];
-    /** The DID of the sender. Used for P2P messaging, but `iss` is the authoritative value for FAPI. */
+    /**
+     * DIDComm sender DID. In a direct signed request this normally equals `iss`.
+     * It is never a raw email, telephone, card id or `urn:multibase` alias. When
+     * a DCR client acts for a human, `from`/`iss` identify the client and SMART
+     * `body.sub` identifies the human actor. `iss` remains authoritative for
+     * the FAPI signature boundary.
+     */
     from?: string;
     /**
      * The Message Type URI, identifying the type of data in the body or protocol used.

package/dist/utils/authority-resolution.js

@@ -4,7 +4,9 @@ function normalizeString(value) {
     return typeof value === 'string' ? value.trim() : '';
 }
 function encodeDidWebAuthority(authority) {
-    return authority.replace(/:/g, '%3A').toLowerCase();
+    // DNS hostnames are case-insensitive, while the canonical did:web spelling
+    // keeps URI percent escapes uppercase for exact DID-document comparisons.
+    return authority.toLowerCase().replace(/:/g, '%3A');
 }
 function normalizeAuthorityHost(value) {
     const raw = normalizeString(value).replace(/\/+$/, '');

package/dist/utils/bundle-document-builder.d.ts

@@ -51,6 +51,14 @@ export declare function getBundleDocumentPatientFullName(bundle: Record<string,
  * equal by accident.
  */
 export declare function normalizeFullNameForComparison(value: unknown): string;
+/**
+ * Detects the native FHIR resource represented by one version-neutral claims
+ * map. A Composition-only map is a complete resource input: it is not merely
+ * metadata for another resource and must remain translatable for strict FHIR
+ * `contained[]` output. When another resource prefix is present,
+ * `Composition.*` remains section-membership metadata and cannot replace that
+ * resource's type.
+ */
 export declare function detectClaimsResourceType(claims: BundleDocumentClaims): string | undefined;
 export declare function convertClaimsToFhirResource(claims: BundleDocumentClaims, version?: 'r4'): FhirResource;
 /**

package/dist/utils/bundle-document-builder.js

@@ -1,4 +1,5 @@
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { Format } from '../constants/Schemas.js';
 import { AllergyIntoleranceClaim } from '../models/interoperable-claims/allergy-intolerance-claims.js';
 import { CompositionClaim } from '../models/interoperable-claims/composition-claims.js';
 import { ConditionClaim } from '../models/interoperable-claims/condition-claims.js';
@@ -7,7 +8,13 @@ import { MedicationStatementClaim } from '../models/interoperable-claims/medicat
 import { ClaimConsent } from '../models/consent-rule.js';
 import { allergyIntoleranceFlatToFhirR4, appointmentResponseFlatToFhirR4, appointmentFlatToFhirR4, carePlanFlatToFhirR4, clinicalImpressionFlatToFhirR4, compositionFlatToFhirR4, conditionFlatToFhirR4, consentFlatToFhirR4, convertFhirResourceToClaims, coverageFlatToFhirR4, deviceFlatToFhirR4, deviceUseStatementFlatToFhirR4, documentReferenceFlatToFhirR4, diagnosticReportFlatToFhirR4, encounterFlatToFhirR4, flagFlatToFhirR4, flatClaimsToFhirResource, immunizationFlatToFhirR4, locationFlatToFhirR4, medicationStatementFlatToFhirR4, observationFromFlatToFhirR4, organizationFlatToFhirR4, procedureFlatToFhirR4, practitionerRoleFlatToFhirR4, relatedPersonFlatToFhirR4, } from './clinical-resource-converters.js';
 /** Version-independent FHIR SearchParameter claim context. */
-const FHIR_API_CLAIMS_CONTEXT = 'org.hl7.fhir.api';
+const FHIR_API_CLAIMS_CONTEXT = Format.FHIR_API;
+const READABLE_FHIR_CLAIMS_CONTEXTS = [
+    Format.FHIR_API,
+    // Deprecated response compatibility. New flat-claim writers use FHIR_API
+    // regardless of the selected native FHIR representation version.
+    Format.FHIR_R4,
+];
 function asTrimmedString(value) {
     if (value === undefined || value === null)
         return '';
@@ -23,9 +30,7 @@ export function getSimpleClaimAttributeName(key) {
     const value = asTrimmedString(key);
     if (!value)
         return '';
-    const knownPrefixes = [
-        `${FHIR_API_CLAIMS_CONTEXT}.`,
-    ];
+    const knownPrefixes = READABLE_FHIR_CLAIMS_CONTEXTS.map((context) => `${context}.`);
     for (const prefix of knownPrefixes) {
         if (value.startsWith(prefix)) {
             return value.slice(prefix.length);
@@ -40,15 +45,19 @@ export function extractFlatClaimValue(record, key) {
     const direct = record[normalizedKey];
     if (typeof direct === 'string' && direct.trim())
         return direct.trim();
-    const contextualizedApi = record[`${FHIR_API_CLAIMS_CONTEXT}.${normalizedKey}`];
-    if (typeof contextualizedApi === 'string' && contextualizedApi.trim())
-        return contextualizedApi.trim();
+    for (const context of READABLE_FHIR_CLAIMS_CONTEXTS) {
+        const contextualized = record[`${context}.${normalizedKey}`];
+        if (typeof contextualized === 'string' && contextualized.trim())
+            return contextualized.trim();
+    }
     const nested = record?.meta?.claims?.[normalizedKey];
     if (typeof nested === 'string' && nested.trim())
         return nested.trim();
-    const nestedApi = record?.meta?.claims?.[`${FHIR_API_CLAIMS_CONTEXT}.${normalizedKey}`];
-    if (typeof nestedApi === 'string' && nestedApi.trim())
-        return nestedApi.trim();
+    for (const context of READABLE_FHIR_CLAIMS_CONTEXTS) {
+        const nestedContextualized = record?.meta?.claims?.[`${context}.${normalizedKey}`];
+        if (typeof nestedContextualized === 'string' && nestedContextualized.trim())
+            return nestedContextualized.trim();
+    }
     return '';
 }
 function claimsToFlatStrings(claims) {
@@ -328,6 +337,14 @@ function mergeContainedResourceReferenceList(claims, references) {
         [claimKey]: next.join(','),
     };
 }
+/**
+ * Detects the native FHIR resource represented by one version-neutral claims
+ * map. A Composition-only map is a complete resource input: it is not merely
+ * metadata for another resource and must remain translatable for strict FHIR
+ * `contained[]` output. When another resource prefix is present,
+ * `Composition.*` remains section-membership metadata and cannot replace that
+ * resource's type.
+ */
 export function detectClaimsResourceType(claims) {
     const keys = Object.keys(claims || {});
     if (keys.some((key) => key.startsWith('MedicationStatement.')))
@@ -338,9 +355,10 @@ export function detectClaimsResourceType(claims) {
         return ResourceTypesFhirR4.Condition;
     if (keys.some((key) => key.startsWith('DocumentReference.')))
         return ResourceTypesFhirR4.DocumentReference;
-    const firstContextualized = keys
+    const qualifiedKeys = keys
         .map((key) => getSimpleClaimAttributeName(key))
-        .find((key) => key.includes('.') && !key.startsWith(`${ResourceTypesFhirR4.Composition}.`));
+        .filter((key) => key.includes('.') && !key.startsWith('@'));
+    const firstContextualized = qualifiedKeys.find((key) => !key.startsWith(`${ResourceTypesFhirR4.Composition}.`)) || qualifiedKeys.find((key) => key.startsWith(`${ResourceTypesFhirR4.Composition}.`));
     if (firstContextualized) {
         return firstContextualized.split('.')[0];
     }

package/dist/utils/did.js

@@ -224,12 +224,25 @@ export function getBaseUrlFromDidWeb(did) {
     const domainPart = didParts[0];
     const pathParts = didParts.slice(1);
     const decodedDomain = decodeURIComponent(domainPart);
-    const protocol = decodedDomain.startsWith('localhost') ? 'http' : 'https';
+    const protocol = isLoopbackDidWebAuthority(decodedDomain) ? 'http' : 'https';
     const path = pathParts.join('/').replace(/cds-(es|us|gb)/, (match, p1) => `cds-${p1.toUpperCase()}`);
     // Ensure a trailing slash for the base URL, without double slashes when no path is present.
     const normalizedPath = path ? `${path}/` : '';
     return `${protocol}://${decodedDomain}/${normalizedPath}`;
 }
+/** Keeps local did:web discovery usable without weakening non-loopback HTTPS. */
+function isLoopbackDidWebAuthority(authority) {
+    try {
+        const hostname = new URL(`http://${authority}`).hostname.toLowerCase().replace(/^\[|\]$/g, '');
+        return hostname === 'localhost'
+            || hostname.endsWith('.localhost')
+            || hostname === '::1'
+            || /^127(?:\.\d{1,3}){3}$/.test(hostname);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Builds the canonical hosted organization/tenant DID in the data space.
  *

package/dist/utils/license-list-search.js

@@ -179,15 +179,23 @@ export function readLicenseListRecords(body) {
     return data
         .filter((entry) => !!entry && typeof entry === 'object')
         .map((entry) => {
-        const claims = extractClaims(entry);
-        const meta = entry.meta && typeof entry.meta === 'object' ? entry.meta : {};
+        // Canonical search responses place one license row in `entry.resource`;
+        // deprecated aggregate responses placed rows in `resource.data[]`.
+        const primaryResource = entry.resource && typeof entry.resource === 'object' && !Array.isArray(entry.resource)
+            ? entry.resource
+            : undefined;
+        const row = primaryResource && !Array.isArray(primaryResource.data) && isLicenseListEntry(primaryResource)
+            ? primaryResource
+            : entry;
+        const claims = extractClaims(row);
+        const meta = row.meta && typeof row.meta === 'object' ? row.meta : {};
         return {
             id: normalizeText(claims[ClaimsIndividualProductSchemaorg.serialNumber]
                 || claims[ClaimsOfferSchemaorg.serialNumber]
-                || entry.id),
-            status: normalizeText(meta.status || entry.status),
-            subjectId: normalizeText(meta.subjectId || entry.subjectId),
-            ownerOrganizationId: normalizeText(meta.ownerOrganizationId || entry.ownerOrganizationId || claims['License.ownerOrganizationId']),
+                || row.id),
+            status: normalizeText(meta.status || row.status),
+            subjectId: normalizeText(meta.subjectId || row.subjectId),
+            ownerOrganizationId: normalizeText(meta.ownerOrganizationId || row.ownerOrganizationId || claims['License.ownerOrganizationId']),
             email: normalizeText(claims[ClaimsPersonSchemaorg.email]),
             telephone: normalizeText(claims[ClaimsPersonSchemaorg.telephone]),
             role: normalizeText(claims[ClaimsPersonSchemaorg.hasOccupationalRoleValue]),

package/package.json

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