gdc-common-utils-ts 2.7.0 → 2.7.2

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/models/consent-rule.d.ts

@@ -47,6 +47,22 @@ export declare const ConsentDecisions: Readonly<{
     readonly Deny: "deny";
 }>;
 export type ConsentDecision = typeof ConsentDecisions[keyof typeof ConsentDecisions];
+/**
+ * Canonical FHIR R5 Consent lifecycle states.
+ *
+ * `draft` is the only state used for a professional permission request. A
+ * draft is carried to the controller for review and must never participate in
+ * authorization evaluation. Only `active` consent rules can grant access.
+ */
+export declare const ConsentStatuses: Readonly<{
+    readonly Draft: "draft";
+    readonly Active: "active";
+    readonly Inactive: "inactive";
+    readonly NotDone: "not-done";
+    readonly EnteredInError: "entered-in-error";
+    readonly Unknown: "unknown";
+}>;
+export type ConsentStatus = typeof ConsentStatuses[keyof typeof ConsentStatuses];
 /**
  * Defines the structured, query-optimized format for storing a single, atomic consent rule
  * in the vault (e.g., Firestore, CouchDB).
@@ -67,6 +83,8 @@ export interface ConsentRule {
      * Value MUST be "org.hl7.fhir.api".
      */
     '@context': 'org.hl7.fhir.api';
+    /** FHIR Consent lifecycle state; authorization evaluators accept only `active`. */
+    'Consent.status'?: ConsentStatus;
     /**
      * The decision of the rule: permit or deny.
      * Derived from the `org.hl7.fhir.api.Consent.decision` claim.

package/dist/models/consent-rule.js

@@ -48,3 +48,18 @@ export const ConsentDecisions = Object.freeze({
     Permit: 'permit',
     Deny: 'deny',
 });
+/**
+ * Canonical FHIR R5 Consent lifecycle states.
+ *
+ * `draft` is the only state used for a professional permission request. A
+ * draft is carried to the controller for review and must never participate in
+ * authorization evaluation. Only `active` consent rules can grant access.
+ */
+export const ConsentStatuses = Object.freeze({
+    Draft: 'draft',
+    Active: 'active',
+    Inactive: 'inactive',
+    NotDone: 'not-done',
+    EnteredInError: 'entered-in-error',
+    Unknown: 'unknown',
+});

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/dist/utils/consent-entry-editor.d.ts

@@ -3,7 +3,7 @@
  * - Read `ARCHITECTURE.md` and `CONTRIBUTING.md` before changing this module.
  * - This file owns only the typed editor for one staged Consent entry.
  */
-import { type ConsentDecision } from '../models/consent-rule';
+import { type ConsentDecision, type ConsentStatus } from '../models/consent-rule';
 import { BundleEntryEditor } from './bundle-entry-editor';
 /**
  * Typed editor for one Consent permission staged inside a Bundle.
@@ -17,6 +17,8 @@ export declare class ConsentEntryEditor extends BundleEntryEditor {
     ensureIdentifier(): string;
     setSubject(value?: string | null): this;
     getSubject(): string | undefined;
+    setStatus(value?: ConsentStatus | null): this;
+    getStatus(): string | undefined;
     setDecision(value?: ConsentDecision | null): this;
     getDecision(): string | undefined;
     setActorIdentifierList(values: readonly string[]): this;

package/dist/utils/consent-entry-editor.js

@@ -43,6 +43,8 @@ export class ConsentEntryEditor extends BundleEntryEditor {
     }
     setSubject(value) { return this.setOptionalText(ClaimConsent.subject, value); }
     getSubject() { return this.getOptionalText(ClaimConsent.subject); }
+    setStatus(value) { return this.setOptionalText(ClaimConsent.status, value); }
+    getStatus() { return this.getOptionalText(ClaimConsent.status); }
     setDecision(value) { return this.setOptionalText(ClaimConsent.decision, value); }
     getDecision() { return this.getOptionalText(ClaimConsent.decision); }
     setActorIdentifierList(values) { return this.setList(ClaimConsent.actorIdentifier, values); }

package/dist/utils/consent.d.ts

@@ -197,6 +197,7 @@ export declare function resolveConsentActor(actor: ConsentActorDescriptor): Reso
  *
  * A rule is active when:
  * - it matches the requested subject when one is provided
+ * - `Consent.status` is absent for legacy compatibility or is exactly `active`
  * - `Consent.period-start` is absent or already effective
  * - `Consent.period-end` is absent or still in the future
  *

package/dist/utils/consent.js

@@ -1,5 +1,5 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-import { ClaimConsent } from '../models/consent-rule.js';
+import { ClaimConsent, ConsentStatuses } from '../models/consent-rule.js';
 import { assignCidToClaimsId } from './fhir-cid.js';
 /**
  * Normalizes a phone string into a compact token form.
@@ -512,6 +512,7 @@ export function resolveConsentActor(actor) {
  *
  * A rule is active when:
  * - it matches the requested subject when one is provided
+ * - `Consent.status` is absent for legacy compatibility or is exactly `active`
  * - `Consent.period-start` is absent or already effective
  * - `Consent.period-end` is absent or still in the future
  *
@@ -523,6 +524,9 @@ export function isConsentRuleActive(rule, options = {}) {
     if (options.subject && String(readConsentRuleClaim(rule, ClaimConsent.subject) || '').trim() !== String(options.subject || '').trim()) {
         return false;
     }
+    const status = String(readConsentRuleClaim(rule, ClaimConsent.status) || '').trim();
+    if (status && status !== ConsentStatuses.Active)
+        return false;
     const now = options.now instanceof Date
         ? options.now.getTime()
         : options.now

package/package.json

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