gdc-common-utils-ts 2.9.1 → 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.

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.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',
@@ -171,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.1",
+  "version": "2.9.2",
   "publishConfig": {
     "access": "public"
   },