gdc-common-utils-ts 2.7.0 → 2.7.1

package/README.md

@@ -152,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/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) {

package/package.json

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