gdc-common-utils-ts 2.9.6 → 2.9.8

package/README.md

@@ -245,7 +245,10 @@ defines the two-step emergency flow: resolve the individual's index provider
 from an opaque subject-identifier ledger key, then ask any available trusted
 tenant to issue one token whose `aud` remains that resolved index provider.
 The ledger value is only `{ indexProviderDid: 'did:web:...' }`; the same opaque
-key is presented later to that provider to retrieve the protected card/index.
+hash stops at Fabric. After DID resolution, the authenticated human-facing
+request uses IHE PDQm `POST Patient/$match` with one FHIR `Parameters` body;
+the provider returns a FHIR search `Bundle` and projects private `sameAs`
+associations as governed `Patient.identifier` values.
 
 Example:
 
@@ -550,6 +553,9 @@ The canonical API contract should live in JSDoc on exported code. The README act
     signing key separate. The organization, EHR/portal or individual remains
     the document author; a registered PractitionerRole or RelatedPerson is the
     attester, including for content entered by that authenticated person.
+- [`normalizeClinicalCreatorBinding(...)`](src/utils/fhir-ips-creator-identity.ts)
+  - Accept stable UUIDs and governed bare role codes at the BFF boundary, then
+    add canonical UUID URNs and HL7/ISCO coding systems before transport.
 - [`src/examples/frontend-session.ts`](src/examples/frontend-session.ts)
   - Frontend profile/session bootstrap examples.
 - [`src/examples/lifecycle.ts`](src/examples/lifecycle.ts)

package/dist/utils/fhir-ips-creator-identity.d.ts

@@ -106,6 +106,30 @@ export type ClinicalCreatorBinding = ClinicalCreatorChannelAliases & Readonly<{
     /** Canonical governed ISCO/HL7 role claim; ONESELF is the subject relationship. */
     role: string;
 }>;
+/**
+ * High-level creator input accepted from SDK/BFF code.
+ *
+ * Stable person, assignment and individual-owner identifiers may be either a
+ * UUID or an already canonical `urn:uuid`. The role may be a governed bare
+ * code or its governed coding-system claim. Callers never concatenate wire
+ * prefixes themselves.
+ */
+export type ClinicalCreatorBindingInput = ClinicalCreatorChannelAliases & Readonly<{
+    kind: FhirIpsCreatorKind;
+    actorIdentifier: string;
+    authorIdentifier: string;
+    ownerIdentifier: string;
+    role: string;
+}>;
+/**
+ * Normalizes high-level creator identity before persistence or transport.
+ *
+ * Personal owners are canonical UUID URNs. Professional owners remain their
+ * legal Organization DID/URN. Bare personal and professional role codes are
+ * resolved through the governed HL7/ISCO catalog and emitted with their
+ * canonical coding system.
+ */
+export declare function normalizeClinicalCreatorBinding(input: ClinicalCreatorBindingInput): ClinicalCreatorBinding;
 export type AuthenticatedClinicalCreatorEvidence = Readonly<{
     actorDid?: string;
     verifiedContactIdentifiers?: readonly string[];

package/dist/utils/fhir-ips-creator-identity.js

@@ -3,6 +3,7 @@ import { getHealthcareRoleByClaim } from '../constants/healthcare.js';
 import { isStableActorIdentifier } from './actor-identifier.js';
 import { normalizeUuid } from './normalize-uuid.js';
 import { HL7_RELATED_PERSON_FUNCTIONAL_ROLES } from '../constants/hl7-roles.js';
+import { UrnPrefixes } from '../constants/urn.js';
 import { CompositionAttesterModes, } from '../models/interoperable-claims/composition-claims.js';
 export const FhirIpsCreatorKinds = Object.freeze({
     IndividualSubject: 'individual-subject',
@@ -118,6 +119,29 @@ export function buildFhirIpsCreatorAuthor(input) {
         ],
     };
 }
+/**
+ * Normalizes high-level creator identity before persistence or transport.
+ *
+ * Personal owners are canonical UUID URNs. Professional owners remain their
+ * legal Organization DID/URN. Bare personal and professional role codes are
+ * resolved through the governed HL7/ISCO catalog and emitted with their
+ * canonical coding system.
+ */
+export function normalizeClinicalCreatorBinding(input) {
+    const actorIdentifier = canonicalUuidUrn(input.actorIdentifier, 'actorIdentifier');
+    const authorIdentifier = canonicalUuidUrn(input.authorIdentifier, 'authorIdentifier');
+    const ownerIdentifier = input.kind === FhirIpsCreatorKinds.Professional
+        ? requireReference(input.ownerIdentifier, 'ownerIdentifier')
+        : canonicalUuidUrn(input.ownerIdentifier, 'ownerIdentifier');
+    const role = canonicalRoleClaim(input.role);
+    return {
+        ...input,
+        actorIdentifier,
+        authorIdentifier,
+        ownerIdentifier,
+        role,
+    };
+}
 /** Builds the stable actor-and-role pair consumed by Consent permission rules. */
 export function buildClinicalCreatorPermissionActor(binding) {
     requireUuidUrn(binding.actorIdentifier, 'binding.actorIdentifier');
@@ -160,6 +184,27 @@ function requireUuidUrn(value, label) {
     }
     return normalized;
 }
+function canonicalUuidUrn(value, label) {
+    const normalized = String(value || '').trim().toLowerCase();
+    const uuidValueInput = normalized.startsWith(UrnPrefixes.Uuid)
+        ? normalized.slice(UrnPrefixes.Uuid.length)
+        : normalized;
+    if (!/^(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/.test(uuidValueInput)) {
+        throw new TypeError(`${label} must be a UUID or urn:uuid identifier.`);
+    }
+    const hexadecimal = normalizeUuid(uuidValueInput);
+    if (!hexadecimal) {
+        throw new TypeError(`${label} must be a UUID or urn:uuid identifier.`);
+    }
+    const uuid = [
+        hexadecimal.slice(0, 8),
+        hexadecimal.slice(8, 12),
+        hexadecimal.slice(12, 16),
+        hexadecimal.slice(16, 20),
+        hexadecimal.slice(20),
+    ].join('-');
+    return `${UrnPrefixes.Uuid}${uuid}`;
+}
 function uuidValue(identifier) {
     return identifier.slice('urn:uuid:'.length);
 }
@@ -189,3 +234,7 @@ function requireRoleCoding(roleClaim) {
         display: functionalRole.display,
     };
 }
+function canonicalRoleClaim(roleClaim) {
+    const descriptor = requireRoleCoding(roleClaim);
+    return `${descriptor.system}|${descriptor.code}`;
+}

package/package.json

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