gdc-common-utils-ts 2.9.0 → 2.9.2

package/README.md

@@ -458,6 +458,13 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - Uses explicit `seedMaterial` for deterministic derivation. Without `seedMaterial`, it defaults to random generation. `mode = deterministic` requires `seedMaterial`.
 - [`buildOrganizationDidWeb(...)`, `buildProfessionalDidWeb(...)`, `buildIndividualDidWeb(...)`, `buildIndividualMemberDidWebFromPrivateIdentifiers(...)`](src/utils/did.ts)
   - Build canonical data-space `did:web` identifiers for hosted organizations, professionals, and individuals/family actors.
+- [`buildOrganizationAuthorizationUrnCds(...)`, `buildOrganizationMemberAuthorizationUrnCds(...)`](src/utils/organization-authorization-urn.ts)
+  - Build host-independent legal organization/member identities such as
+    `urn:cds-es:v1:organization:tax:ES-B00112233` and its
+    `:member:<multibase-id>:<role-value>` child.
+  - Jurisdiction is mandatory so `BN`, `EIN`, `TAX` and subnational identifier
+    schemes cannot collide; `roleType` remains protected while only the compact
+    `roleValue` is serialized.
 - [`buildSmartCompositionReadScope(...)`](src/utils/smart-scope.ts)
   - Builds the current CORE GW pinned SMART root scope for `organization/Composition...` token requests.
   - This is the preferred first scope to teach when the backend only needs subject-scoped read access.
@@ -530,9 +537,9 @@ The canonical API contract should live in JSDoc on exported code. The README act
 - [`buildFhirIpsCreatorProvenance(...)`](src/utils/fhir-ips-creator-identity.ts)
   and [`docs/101-DIDCOMM-IDENTITY-BOUNDARY.md`](docs/101-DIDCOMM-IDENTITY-BOUNDARY.md)
   - Keep `Composition.author`, `Composition.attester`, DIDComm sender and
-    signing key separate. A member-created fact may use the registered
-    RelatedPerson as both author and personal attester; a dictated
-    individual-created fact keeps the individual as author.
+    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.
 - [`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/constants/healthcare.d.ts

@@ -1732,6 +1732,8 @@ export declare const HealthcareActorRoles: Readonly<{
     /** ISCO-08 laboratory occupation for human medical/pathology work. */
     readonly MedicalAndPathologyLaboratoryTechnician: "ISCO-08|3212";
     readonly VeterinaryTechnicianOrAssistant: "ISCO-08|3240";
+    /** General receptionist occupation usable across human, animal and one-health organizations. */
+    readonly Receptionist: "ISCO-08|4226";
     /** Administrative health occupation; it does not imply clinical authority. */
     readonly MedicalSecretary: "ISCO-08|3344";
 }>;
@@ -1757,6 +1759,7 @@ export declare const HealthcareActorRoleCodes: Readonly<{
     readonly LifeScienceTechnician: "3141";
     readonly MedicalAndPathologyLaboratoryTechnician: "3212";
     readonly VeterinaryTechnicianOrAssistant: "3240";
+    readonly Receptionist: "4226";
     readonly MedicalSecretary: "3344";
 }>;
 export declare const HealthcareRolesByFamily: Readonly<{
@@ -1790,19 +1793,19 @@ export declare const HealthcareRolesByFamily: Readonly<{
 }>;
 export declare const HealthcareAllRolesByClaim: Readonly<Record<string, HealthcareActorRoleDescriptor>>;
 export declare const HealthcareProfessionalRoleCodesBySector: Readonly<{
-    readonly "health-care": readonly ("RESPRSN" | "221" | "2211" | "2212" | "2221" | "2222" | "2240" | "3344")[];
-    readonly "health-research": readonly ("RESPRSN" | "221" | "2211" | "2212" | "3344")[];
-    readonly "health-lab": readonly ("RESPRSN" | "221" | "2212" | "3212" | "3344")[];
-    readonly "health-tech": readonly "RESPRSN"[];
-    readonly "health-insurance": readonly "RESPRSN"[];
-    readonly "animal-care": readonly ("RESPRSN" | "2250" | "3240")[];
-    readonly "animal-research": readonly ("RESPRSN" | "2250" | "3240")[];
-    readonly "animal-lab": readonly ("RESPRSN" | "2250" | "3141" | "3240")[];
-    readonly "animal-insurance": readonly "RESPRSN"[];
-    readonly "animal-tech": readonly "RESPRSN"[];
-    readonly "onehealth-research": readonly ("RESPRSN" | "221" | "2211" | "2212" | "2250" | "3240" | "3344")[];
-    readonly "onehealth-lab": readonly ("RESPRSN" | "221" | "2212" | "2250" | "3141" | "3212" | "3240" | "3344")[];
-    readonly "onehealth-tech": readonly "RESPRSN"[];
+    readonly "health-care": readonly ("RESPRSN" | "221" | "2211" | "2212" | "2221" | "2222" | "2240" | "4226" | "3344")[];
+    readonly "health-research": readonly ("RESPRSN" | "221" | "2211" | "2212" | "4226" | "3344")[];
+    readonly "health-lab": readonly ("RESPRSN" | "221" | "2212" | "3212" | "4226" | "3344")[];
+    readonly "health-tech": readonly ("RESPRSN" | "4226")[];
+    readonly "health-insurance": readonly ("RESPRSN" | "4226")[];
+    readonly "animal-care": readonly ("RESPRSN" | "2250" | "3240" | "4226")[];
+    readonly "animal-research": readonly ("RESPRSN" | "2250" | "3240" | "4226")[];
+    readonly "animal-lab": readonly ("RESPRSN" | "2250" | "3141" | "3240" | "4226")[];
+    readonly "animal-insurance": readonly ("RESPRSN" | "4226")[];
+    readonly "animal-tech": readonly ("RESPRSN" | "4226")[];
+    readonly "onehealth-research": readonly ("RESPRSN" | "221" | "2211" | "2212" | "2250" | "3240" | "4226" | "3344")[];
+    readonly "onehealth-lab": readonly ("RESPRSN" | "221" | "2212" | "2250" | "3141" | "3212" | "3240" | "4226" | "3344")[];
+    readonly "onehealth-tech": readonly ("RESPRSN" | "4226")[];
 }>;
 export declare const HealthcareProfessionalRolesBySector: Readonly<{
     readonly "health-care": Readonly<Record<string, Readonly<{

package/dist/constants/healthcare.js

@@ -364,6 +364,8 @@ export const HealthcareActorRoles = Object.freeze({
     /** ISCO-08 laboratory occupation for human medical/pathology work. */
     MedicalAndPathologyLaboratoryTechnician: 'ISCO-08|3212',
     VeterinaryTechnicianOrAssistant: 'ISCO-08|3240',
+    /** General receptionist occupation usable across human, animal and one-health organizations. */
+    Receptionist: 'ISCO-08|4226',
     /** Administrative health occupation; it does not imply clinical authority. */
     MedicalSecretary: 'ISCO-08|3344',
 });
@@ -389,6 +391,7 @@ export const HealthcareActorRoleCodes = Object.freeze({
     LifeScienceTechnician: '3141',
     MedicalAndPathologyLaboratoryTechnician: '3212',
     VeterinaryTechnicianOrAssistant: '3240',
+    Receptionist: '4226',
     MedicalSecretary: '3344',
 });
 function buildProfessionalIscoRoles() {
@@ -503,6 +506,17 @@ function buildProfessionalIscoRoles() {
                 titleEn: 'Veterinary technician or assistant',
             }),
         ],
+        [
+            HealthcareActorRoleCodes.Receptionist,
+            Object.freeze({
+                family: HealthcareRoleFamilies.ProfessionalOccupationIsco08,
+                codingSystem: ISCO08_CODING_SYSTEM,
+                code: HealthcareActorRoleCodes.Receptionist,
+                claim: HealthcareActorRoles.Receptionist,
+                i18nKey: `${ISCO08_I18N_NAMESPACE}.${HealthcareActorRoleCodes.Receptionist}`,
+                titleEn: 'Receptionists (general)',
+            }),
+        ],
         [
             HealthcareActorRoleCodes.MedicalSecretary,
             Object.freeze({
@@ -580,6 +594,7 @@ export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
         HealthcareActorRoleCodes.NursingProfessional,
         HealthcareActorRoleCodes.MidwiferyProfessional,
         HealthcareActorRoleCodes.Paramedic,
+        HealthcareActorRoleCodes.Receptionist,
         HealthcareActorRoleCodes.MedicalSecretary,
     ]),
     [DataspaceSectors.HealthResearch]: Object.freeze([
@@ -587,6 +602,7 @@ export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
         HealthcareActorRoleCodes.MedicalDoctors,
         HealthcareActorRoleCodes.GeneralistMedicalPractitioner,
         HealthcareActorRoleCodes.SpecialistMedicalPractitioner,
+        HealthcareActorRoleCodes.Receptionist,
         HealthcareActorRoleCodes.MedicalSecretary,
     ]),
     [DataspaceSectors.HealthLab]: Object.freeze([
@@ -594,28 +610,32 @@ export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
         HealthcareActorRoleCodes.MedicalDoctors,
         HealthcareActorRoleCodes.SpecialistMedicalPractitioner,
         HealthcareActorRoleCodes.MedicalAndPathologyLaboratoryTechnician,
+        HealthcareActorRoleCodes.Receptionist,
         HealthcareActorRoleCodes.MedicalSecretary,
     ]),
-    [DataspaceSectors.HealthTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
-    [DataspaceSectors.HealthInsurance]: Object.freeze([HealthcareActorRoleCodes.Controller]),
+    [DataspaceSectors.HealthTech]: Object.freeze([HealthcareActorRoleCodes.Controller, HealthcareActorRoleCodes.Receptionist]),
+    [DataspaceSectors.HealthInsurance]: Object.freeze([HealthcareActorRoleCodes.Controller, HealthcareActorRoleCodes.Receptionist]),
     [DataspaceSectors.AnimalCare]: Object.freeze([
         HealthcareActorRoleCodes.Controller,
         HealthcareActorRoleCodes.Veterinarian,
         HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
+        HealthcareActorRoleCodes.Receptionist,
     ]),
     [DataspaceSectors.AnimalResearch]: Object.freeze([
         HealthcareActorRoleCodes.Controller,
         HealthcareActorRoleCodes.Veterinarian,
         HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
+        HealthcareActorRoleCodes.Receptionist,
     ]),
     [DataspaceSectors.AnimalLab]: Object.freeze([
         HealthcareActorRoleCodes.Controller,
         HealthcareActorRoleCodes.Veterinarian,
         HealthcareActorRoleCodes.LifeScienceTechnician,
         HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
+        HealthcareActorRoleCodes.Receptionist,
     ]),
-    [DataspaceSectors.AnimalInsurance]: Object.freeze([HealthcareActorRoleCodes.Controller]),
-    [DataspaceSectors.AnimalTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
+    [DataspaceSectors.AnimalInsurance]: Object.freeze([HealthcareActorRoleCodes.Controller, HealthcareActorRoleCodes.Receptionist]),
+    [DataspaceSectors.AnimalTech]: Object.freeze([HealthcareActorRoleCodes.Controller, HealthcareActorRoleCodes.Receptionist]),
     [DataspaceSectors.OneHealthResearch]: Object.freeze([
         HealthcareActorRoleCodes.Controller,
         HealthcareActorRoleCodes.MedicalDoctors,
@@ -623,6 +643,7 @@ export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
         HealthcareActorRoleCodes.SpecialistMedicalPractitioner,
         HealthcareActorRoleCodes.Veterinarian,
         HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
+        HealthcareActorRoleCodes.Receptionist,
         HealthcareActorRoleCodes.MedicalSecretary,
     ]),
     [DataspaceSectors.OneHealthLab]: Object.freeze([
@@ -633,9 +654,10 @@ export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
         HealthcareActorRoleCodes.LifeScienceTechnician,
         HealthcareActorRoleCodes.MedicalAndPathologyLaboratoryTechnician,
         HealthcareActorRoleCodes.VeterinaryTechnicianOrAssistant,
+        HealthcareActorRoleCodes.Receptionist,
         HealthcareActorRoleCodes.MedicalSecretary,
     ]),
-    [DataspaceSectors.OneHealthTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
+    [DataspaceSectors.OneHealthTech]: Object.freeze([HealthcareActorRoleCodes.Controller, HealthcareActorRoleCodes.Receptionist]),
 });
 export const HealthcareProfessionalRolesBySector = Object.freeze({
     [DataspaceSectors.HealthCare]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthCare]),

package/dist/examples/ica-verify-response.d.ts

@@ -159,7 +159,7 @@ export declare const EXAMPLE_VERIFY_RESPONSE_ORG_CREDENTIAL: Readonly<{
         id: "did:web:globaldatacare.es:onehealth:organization:taxid:VATES-B00112233";
         '@type': "Organization";
         legalName: "ACME Health Provider";
-        taxID: "VATES-B00112233";
+        taxID: "ES-B00112233";
         sameAs: "did:web:provider.example.org";
         url: "health-care.provider.example.org";
         alternateName: string;
@@ -210,7 +210,7 @@ export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL: Readonly<{
         memberOf: {
             '@type': "Organization";
             legalName: "ACME Health Provider";
-            taxID: "VATES-B00112233";
+            taxID: "ES-B00112233";
         };
         alternateName: "controller-es384-001";
         additionalType: "ES384";
@@ -240,7 +240,7 @@ export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_CREDENTIAL: Readonly<{
         provider: {
             '@type': "Organization";
             legalName: "ACME Health Provider";
-            taxID: "VATES-B00112233";
+            taxID: "ES-B00112233";
         };
         owner: {
             '@type': "Person";

package/dist/examples/shared.d.ts

@@ -144,7 +144,10 @@ export declare const EXAMPLE_HOST_PUBLIC_HOSTNAME: "host.example.com";
 export declare const EXAMPLE_HOST_PUBLIC_DID: "did:web:host.example.com";
 export declare const EXAMPLE_PERSON_CARD_URI: "urn:example:card:person:subject-001";
 export declare const EXAMPLE_ANIMAL_CARD_URI: "urn:example:card:animal:subject-002";
-export declare const EXAMPLE_PROVIDER_TAX_ID: "VATES-B00112233";
+export declare const EXAMPLE_PROVIDER_TAX_ID: "ES-B00112233";
+/** Jurisdiction-scoped synthetic legal identifier used by stable CDS URNs. */
+export declare const EXAMPLE_PROVIDER_LEGAL_IDENTIFIER_VALUE_CDS: "ES-B00112233";
+export declare const EXAMPLE_PROVIDER_ORGANIZATION_AUTHORIZATION_URN_CDS: string;
 export declare const EXAMPLE_PROVIDER_DOMAIN: "health-care.provider.example.org";
 /** Synthetic public portal domain used to derive organization path DIDs. */
 export declare const EXAMPLE_PUBLIC_PORTAL_DOMAIN: "portal.example.org";
@@ -216,6 +219,7 @@ export declare const EXAMPLE_HEALTHCARE_ACTOR_ROLE_RECEPTIONIST: "ISCO-08|4226";
 export declare const EXAMPLE_HEALTHCARE_ROLE_PHYSICIAN_TEXT: "physician";
 export declare const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_TYPE = "http://terminology.hl7.org/CodeSystem/v3-RoleCode";
 export declare const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_VALUE: "RESPRSN";
+export declare const EXAMPLE_PROFESSIONAL_AUTHORIZATION_URN_CDS: string;
 export declare const EXAMPLE_RELATED_PERSON_ROLE: "v3-RoleCode|RESPRSN";
 export declare const EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL: string;
 export declare const EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL_CONTROLLER: string;

package/dist/examples/shared.js

@@ -8,12 +8,13 @@ import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
 import { BirthSex, GenderIdentity } from '../constants/identity-gender.js';
 import { IdKind, SecureIdTypesIndividual } from '../constants/identity-identifiers.js';
 import { HL7_CODING_SYSTEM_V3_ROLE_CODE } from '../constants/hl7-roles.js';
-import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, HealthcareDocumentTypes, } from '../constants/healthcare.js';
+import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, HealthcareDocumentTypes, ISCO08_CODING_SYSTEM, } from '../constants/healthcare.js';
 import { CommunicationCategoryCodes } from '../constants/communication.js';
 import { LOINC_SYSTEM_URL } from '../models/clinical-sections.js';
 import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
 import { buildHostedProviderDidWeb, buildIndividualDidWeb, buildIndividualMemberDidWeb, buildSecureIdValueIndividual, buildSecureIdValueMember, buildProfessionalDidWeb, buildProviderSectorDidWeb, } from '../utils/did.js';
 import { encodeHexToMultibase58btc } from '../utils/multibase58.js';
+import { buildOrganizationAuthorizationUrnCds, buildOrganizationMemberAuthorizationUrnCds, } from '../utils/organization-authorization-urn.js';
 import { MedicationStatementClaim, MedicationStatementClaimsFhirApiExtended, } from '../models/interoperable-claims/medication-statement-claims.js';
 import { medicationStatementFlatToFhirR4 } from '../utils/clinical-resource-converters.js';
 /**
@@ -163,7 +164,15 @@ export const EXAMPLE_HOST_PUBLIC_HOSTNAME = 'host.example.com';
 export const EXAMPLE_HOST_PUBLIC_DID = `did:web:${EXAMPLE_HOST_PUBLIC_HOSTNAME}`;
 export const EXAMPLE_PERSON_CARD_URI = 'urn:example:card:person:subject-001';
 export const EXAMPLE_ANIMAL_CARD_URI = 'urn:example:card:animal:subject-002';
-export const EXAMPLE_PROVIDER_TAX_ID = 'VATES-B00112233';
+export const EXAMPLE_PROVIDER_TAX_ID = 'ES-B00112233';
+/** Jurisdiction-scoped synthetic legal identifier used by stable CDS URNs. */
+export const EXAMPLE_PROVIDER_LEGAL_IDENTIFIER_VALUE_CDS = 'ES-B00112233';
+export const EXAMPLE_PROVIDER_ORGANIZATION_AUTHORIZATION_URN_CDS = buildOrganizationAuthorizationUrnCds({
+    jurisdiction: EXAMPLE_JURISDICTION,
+    version: EXAMPLE_ROUTE_VERSION,
+    identifierType: 'TAX',
+    identifierValue: EXAMPLE_PROVIDER_LEGAL_IDENTIFIER_VALUE_CDS,
+});
 export const EXAMPLE_PROVIDER_DOMAIN = 'health-care.provider.example.org';
 /** Synthetic public portal domain used to derive organization path DIDs. */
 export const EXAMPLE_PUBLIC_PORTAL_DOMAIN = 'portal.example.org';
@@ -256,6 +265,15 @@ export const EXAMPLE_HEALTHCARE_ACTOR_ROLE_RECEPTIONIST = 'ISCO-08|4226';
 export const EXAMPLE_HEALTHCARE_ROLE_PHYSICIAN_TEXT = 'physician';
 export const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_TYPE = HL7_CODING_SYSTEM_V3_ROLE_CODE;
 export const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_VALUE = EXAMPLE_ORGANIZATION_CONTROLLER_ROLE;
+export const EXAMPLE_PROFESSIONAL_AUTHORIZATION_URN_CDS = buildOrganizationMemberAuthorizationUrnCds({
+    organizationUrn: EXAMPLE_PROVIDER_ORGANIZATION_AUTHORIZATION_URN_CDS,
+    memberId: buildSecureIdValueMember({
+        secureIdTypeMember: SecureIdTypesIndividual.Email,
+        privateIdValueMember: EXAMPLE_EMAIL_PROFESSIONAL,
+    }),
+    roleType: ISCO08_CODING_SYSTEM,
+    roleValue: HealthcareActorRoles.GeneralistMedicalPractitioner,
+});
 export const EXAMPLE_RELATED_PERSON_ROLE = 'v3-RoleCode|RESPRSN';
 export const EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL = buildSecureIdValueIndividual({
     secureIdTypeIndividual: SecureIdTypesIndividual.Uuid,

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

@@ -33,10 +33,11 @@ export type FhirIpsCreatorAuthor = Readonly<{
 }>;
 export type FhirIpsCreatorProvenanceInput = FhirIpsCreatorAuthorInput & Readonly<{
     /**
-     * Explicit source originator. Defaults to the owning organization or
-     * individual. When the authenticated member/professional actually authored
-     * the content, pass its registered RelatedPerson/PractitionerRole assignment
-     * reference; that same assignment may also remain the attester.
+     * Explicit document/source author. Defaults to the owning organization or
+     * individual. A registered RelatedPerson/PractitionerRole is an attester,
+     * never a substitute for the organization, EHR/portal or individual that
+     * authors the document. Passing the assignment reference is normalized to
+     * the owner for compatibility with the former creator-as-author contract.
      */
     compositionAuthorReference?: string;
     /** Defaults to professional for employees and personal for individual members. */
@@ -58,13 +59,11 @@ export type FhirIpsCreatorProvenance = Readonly<{
 /**
  * Builds source authorship separately from the person or role that attests it.
  *
- * Defaults model delegated flows: an organization's professional attests an
- * organization-authored record, while a member/caregiver attests a
- * subject-authored record. For content actually created by that authenticated
- * member or professional, set `compositionAuthorReference` to its registered
- * RelatedPerson or PractitionerRole assignment. Author and attester may then
- * intentionally reference the same assignment; neither is the transport
- * sender or signing key.
+ * An organization's employee attests an organization/EHR-authored record,
+ * while a controller/member/caregiver attests an individual-authored record.
+ * Neither the attester nor the document author is the transport sender or
+ * signing key merely because the same authenticated person performed the
+ * submission.
  */
 export declare function buildFhirIpsCreatorProvenance(input: FhirIpsCreatorProvenanceInput): FhirIpsCreatorProvenance;
 /**

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

@@ -2,6 +2,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 { CompositionAttesterModes, } from '../models/interoperable-claims/composition-claims.js';
 export const FhirIpsCreatorKinds = Object.freeze({
     IndividualSubject: 'individual-subject',
@@ -11,13 +12,11 @@ export const FhirIpsCreatorKinds = Object.freeze({
 /**
  * Builds source authorship separately from the person or role that attests it.
  *
- * Defaults model delegated flows: an organization's professional attests an
- * organization-authored record, while a member/caregiver attests a
- * subject-authored record. For content actually created by that authenticated
- * member or professional, set `compositionAuthorReference` to its registered
- * RelatedPerson or PractitionerRole assignment. Author and attester may then
- * intentionally reference the same assignment; neither is the transport
- * sender or signing key.
+ * An organization's employee attests an organization/EHR-authored record,
+ * while a controller/member/caregiver attests an individual-authored record.
+ * Neither the attester nor the document author is the transport sender or
+ * signing key merely because the same authenticated person performed the
+ * submission.
  */
 export function buildFhirIpsCreatorProvenance(input) {
     if (input.kind === FhirIpsCreatorKinds.IndividualSubject) {
@@ -31,11 +30,14 @@ export function buildFhirIpsCreatorProvenance(input) {
     const defaultAuthor = input.kind === FhirIpsCreatorKinds.Professional
         ? input.organizationReference
         : input.subjectReference;
+    const requestedAuthor = input.compositionAuthorReference === creator.authorReference
+        ? defaultAuthor
+        : input.compositionAuthorReference;
     const mode = input.attesterMode || (input.kind === FhirIpsCreatorKinds.Professional
         ? CompositionAttesterModes.Professional
         : CompositionAttesterModes.Personal);
     return {
-        authorReference: requireReference(input.compositionAuthorReference || defaultAuthor, 'compositionAuthorReference'),
+        authorReference: requireReference(requestedAuthor || defaultAuthor, 'compositionAuthorReference'),
         attesters: [{
                 mode,
                 party: { reference: creator.authorReference },
@@ -89,6 +91,13 @@ export function buildFhirIpsCreatorAuthor(input) {
     return {
         authorReference: authorIdentifier,
         entries: [
+            {
+                fullUrl: organizationReference,
+                resource: {
+                    resourceType: 'Organization',
+                    identifier: [{ value: organizationReference }],
+                },
+            },
             {
                 fullUrl: actorIdentifier,
                 resource: {
@@ -163,12 +172,22 @@ function requireReference(value, label) {
     return normalized;
 }
 function requireRoleCoding(roleClaim) {
-    const descriptor = getHealthcareRoleByClaim(String(roleClaim || '').trim());
-    if (!descriptor)
-        throw new TypeError('role must be a canonical governed healthcare role.');
+    const normalizedRole = String(roleClaim || '').trim();
+    const descriptor = getHealthcareRoleByClaim(normalizedRole);
+    if (descriptor) {
+        return {
+            system: descriptor.codingSystem,
+            code: descriptor.code,
+            ...(descriptor.titleEn ? { display: descriptor.titleEn } : {}),
+        };
+    }
+    const functionalRole = HL7_RELATED_PERSON_FUNCTIONAL_ROLES.find((candidate) => normalizedRole === `${candidate.codingSystem}|${candidate.code}`);
+    if (!functionalRole) {
+        throw new TypeError('role must be a canonical governed healthcare or RelatedPerson functional role.');
+    }
     return {
-        system: descriptor.codingSystem,
-        code: descriptor.code,
-        ...(descriptor.titleEn ? { display: descriptor.titleEn } : {}),
+        system: functionalRole.codingSystem,
+        code: functionalRole.code,
+        display: functionalRole.display,
     };
 }

package/dist/utils/organization-authorization-urn.d.ts

@@ -3,6 +3,25 @@ export type OrganizationAuthorizationUrnInput = Readonly<{
     identifierType: string;
     identifierValue: string;
 }>;
+export type OrganizationAuthorizationUrnCdsInput = Readonly<{
+    /** ISO country or governed subdivision such as ES, US, US-WA or CA-BC. */
+    jurisdiction: string;
+    /** Version of the stable CDS identifier grammar. Defaults to v1. */
+    version?: string;
+    /** Governed legal identifier type such as TAX, EIN or BN. */
+    identifierType: string;
+    /** Canonical value issued by that jurisdiction's identifier authority. */
+    identifierValue: string;
+}>;
+export type OrganizationMemberAuthorizationUrnCdsInput = Readonly<{
+    organizationUrn: string;
+    /** Bare base58btc multibase identifier (`z...`); never raw email/phone. */
+    memberId: string;
+    /** Required protected coding system; deliberately not serialized. */
+    roleType: string;
+    /** Coded role value serialized as the final compact path segment. */
+    roleValue: string;
+}>;
 export type MemberAuthorizationUrnInput = Readonly<{
     organizationUrn?: string;
     identifierType?: string;
@@ -15,6 +34,10 @@ export type MemberAuthorizationUrnInput = Readonly<{
  * Canonical organization authorization identifier used by ledger, consent-like
  * rules, and inter-tenant authorization persistence.
  *
+ * @deprecated For new cross-jurisdiction identities use
+ * `buildOrganizationAuthorizationUrnCds`, which requires jurisdiction and
+ * grammar version. This legacy form remains readable during migration.
+ *
  * Format:
  * - `urn:org:<identifierType-lowercase>:<identifierValue-as-canonical-input>`
  *
@@ -23,6 +46,22 @@ export type MemberAuthorizationUrnInput = Readonly<{
  * - `urn:org:tax:acme-id`
  */
 export declare function buildOrganizationAuthorizationUrn(input: OrganizationAuthorizationUrnInput): string;
+/**
+ * Builds the globally scoped, host-independent legal organization identifier.
+ *
+ * Format:
+ * `urn:cds-<jurisdiction>:<version>:organization:<identifier-type>:<identifier-value>`
+ *
+ * Jurisdiction is mandatory because identifier schemes such as BN, EIN and
+ * TAX are interpreted by different national/subnational authorities.
+ */
+export declare function buildOrganizationAuthorizationUrnCds(input: OrganizationAuthorizationUrnCdsInput): string;
+/**
+ * Builds a stable organization-member authorization identifier without a host.
+ * `roleType` is mandatory input but only `roleValue` is serialized, matching
+ * the compact role convention used by member did:web paths.
+ */
+export declare function buildOrganizationMemberAuthorizationUrnCds(input: OrganizationMemberAuthorizationUrnCdsInput): string;
 /**
  * Accepts either the legacy `TYPE|VALUE` input or an already-canonical
  * `urn:org:...` identifier and always returns the canonical URN form.

package/dist/utils/organization-authorization-urn.js

@@ -1,6 +1,8 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { ClaimsOrganizationSchemaorg } from '../constants/schemaorg.js';
 const ORGANIZATION_URN_PREFIX = 'urn:org:';
+const CDS_ORGANIZATION_URN_PATTERN = /^urn:cds-([a-z]{2}(?:-[a-z0-9]{2,3})?):(v[1-9][0-9]*):organization:([a-z][a-z0-9-]*):([^:]+)$/;
+const BARE_MULTIBASE_PATTERN = /^z[1-9A-HJ-NP-Za-km-z]+$/;
 function normalizeTypeSegment(identifierType) {
     return String(identifierType || '').trim().toLowerCase();
 }
@@ -11,6 +13,10 @@ function normalizeValueSegment(identifierValue) {
  * Canonical organization authorization identifier used by ledger, consent-like
  * rules, and inter-tenant authorization persistence.
  *
+ * @deprecated For new cross-jurisdiction identities use
+ * `buildOrganizationAuthorizationUrnCds`, which requires jurisdiction and
+ * grammar version. This legacy form remains readable during migration.
+ *
  * Format:
  * - `urn:org:<identifierType-lowercase>:<identifierValue-as-canonical-input>`
  *
@@ -26,6 +32,52 @@ export function buildOrganizationAuthorizationUrn(input) {
     }
     return `${ORGANIZATION_URN_PREFIX}${identifierType}:${identifierValue}`;
 }
+/**
+ * Builds the globally scoped, host-independent legal organization identifier.
+ *
+ * Format:
+ * `urn:cds-<jurisdiction>:<version>:organization:<identifier-type>:<identifier-value>`
+ *
+ * Jurisdiction is mandatory because identifier schemes such as BN, EIN and
+ * TAX are interpreted by different national/subnational authorities.
+ */
+export function buildOrganizationAuthorizationUrnCds(input) {
+    const jurisdiction = String(input.jurisdiction || '').trim().toLowerCase();
+    const version = String(input.version || 'v1').trim().toLowerCase();
+    const identifierType = normalizeTypeSegment(input.identifierType);
+    const identifierValue = normalizeValueSegment(input.identifierValue);
+    if (!/^[a-z]{2}(?:-[a-z0-9]{2,3})?$/.test(jurisdiction)) {
+        throw new Error('CDS organization authorization URN requires an ISO jurisdiction such as ES, US or CA-BC.');
+    }
+    if (!/^v[1-9][0-9]*$/.test(version)) {
+        throw new Error('CDS organization authorization URN requires a version such as v1.');
+    }
+    if (!/^[a-z][a-z0-9-]*$/.test(identifierType) || !identifierValue || identifierValue.includes(':')) {
+        throw new Error('CDS organization authorization URN requires a legal identifier type and colon-free value.');
+    }
+    return `urn:cds-${jurisdiction}:${version}:organization:${identifierType}:${identifierValue}`;
+}
+/**
+ * Builds a stable organization-member authorization identifier without a host.
+ * `roleType` is mandatory input but only `roleValue` is serialized, matching
+ * the compact role convention used by member did:web paths.
+ */
+export function buildOrganizationMemberAuthorizationUrnCds(input) {
+    const organizationUrn = String(input.organizationUrn || '').trim();
+    const memberId = String(input.memberId || '').trim();
+    const roleType = String(input.roleType || '').trim();
+    const roleValue = String(input.roleValue || '').trim();
+    if (!CDS_ORGANIZATION_URN_PATTERN.test(organizationUrn)) {
+        throw new Error('CDS organization member authorization URN requires a canonical CDS organization URN.');
+    }
+    if (!BARE_MULTIBASE_PATTERN.test(memberId)) {
+        throw new Error('CDS organization member authorization URN requires memberId as bare base58btc multibase.');
+    }
+    if (!roleType || !roleValue || roleValue.includes(':')) {
+        throw new Error('CDS organization member authorization URN requires roleType and a colon-free roleValue.');
+    }
+    return `${organizationUrn}:member:${memberId}:${roleValue}`;
+}
 /**
  * Accepts either the legacy `TYPE|VALUE` input or an already-canonical
  * `urn:org:...` identifier and always returns the canonical URN form.

package/package.json

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