gdc-common-utils-ts 2.9.25 → 2.9.26

package/README.md

@@ -759,6 +759,18 @@ Example:
 import { ICryptography, MlkemPublicJwk } from 'gdc-common-utils-ts/interfaces/Cryptography.types';
 ```
 
+## Sector tenant identity
+
+Use `buildLegalSectorOrganizationUrn(...)` to derive the stable public identity
+of one legal organization inside one data-space sector. Use
+`buildLegalSectorOrganizationAssetId(...)` for its opaque Fabric lookup key.
+Changing the hosting provider or tenant DID does not change that key.
+
+For tenant lifecycle calls, keep the neutral legal identifier in
+`setIdentifierValue(...)` and select the exact hosted tenant with
+`setTenantDid(...)`. Obtain that DID from the registered tenant/profile or
+authority response; do not reconstruct it from display names.
+
 ## Auth-Flow Boundaries
 
 This package provides primitives, not orchestration.

package/dist/utils/index.d.ts

@@ -69,6 +69,7 @@ export * from './individual-smart.js';
 export * from './individual-organization-claims.js';
 export * from './inter-tenant-access-contract.js';
 export * from './legal-organization-onboarding-editor.js';
+export * from './legal-sector-organization-urn.js';
 export * from './organization-lifecycle.js';
 export * from './organization-employee-lifecycle.js';
 export * from './organization-did-binding.js';

package/dist/utils/index.js

@@ -69,6 +69,7 @@ export * from './individual-smart.js';
 export * from './individual-organization-claims.js';
 export * from './inter-tenant-access-contract.js';
 export * from './legal-organization-onboarding-editor.js';
+export * from './legal-sector-organization-urn.js';
 export * from './organization-lifecycle.js';
 export * from './organization-employee-lifecycle.js';
 export * from './organization-did-binding.js';

package/dist/utils/legal-sector-organization-urn.d.ts

@@ -0,0 +1,33 @@
+export type LegalSectorOrganizationUrnInput = Readonly<{
+    /** Governed data-space sector, for example `health-care` or `animal-care`. */
+    sector: string;
+    /** ISO 3166-1 alpha-2 country code. */
+    country: string;
+    /** Optional ISO 3166-2 or governed first administrative subdivision. */
+    administrativeSublevel1?: string;
+    /** Optional second administrative subdivision. */
+    administrativeSublevel2?: string;
+    /** Optional third administrative subdivision. */
+    administrativeSublevel3?: string;
+    /** HL7 v2-0203-derived or governed extension code, such as TAX, EN or BN. */
+    identifierType: string;
+    /** Issuer-defined official identifier. Its casing is preserved. */
+    identifierValue: string;
+}>;
+/**
+ * Builds the organization-level public identifier from the governed legal URN
+ * grammar. All structural tokens are lower-cased; the official identifier is
+ * preserved exactly after trimming and NFKC normalization.
+ *
+ * Format:
+ * `urn:legal:<sector>:<country>:<admin1>:<admin2>:<admin3>:organization:<type>:<official-id>`
+ */
+export declare function buildLegalSectorOrganizationUrn(input: LegalSectorOrganizationUrnInput): string;
+/**
+ * Builds the stable Fabric lookup key for one organization-sector binding.
+ *
+ * The exact canonical legal-sector URN UTF-8 bytes are encoded as
+ * `urn:multibase:base58btc(multihash(SHA3-256))`. A provider/DID rotation does
+ * not change this key; only the binding asset state and history change.
+ */
+export declare function buildLegalSectorOrganizationAssetId(organizationUrn: string): string;

package/dist/utils/legal-sector-organization-urn.js

@@ -0,0 +1,78 @@
+// Copyright 2026 ConnectHealth.info (Connectin Solution & Applications Ltd.) under the Apache License, Version 2.0.
+import { UrnPrefixes } from '../constants/urn.js';
+import { encodeMultibaseSha3 } from './multibasehash.js';
+const NORMALIZED_SEGMENT_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+function normalizeRequiredSegment(value, field) {
+    const normalized = String(value || '').trim().normalize('NFKC').toLowerCase();
+    if (!NORMALIZED_SEGMENT_PATTERN.test(normalized)) {
+        throw new Error(`Legal sector organization URN requires a valid ${field}.`);
+    }
+    return normalized;
+}
+function normalizeOptionalSegment(value, field) {
+    if (!String(value || '').trim())
+        return '';
+    return normalizeRequiredSegment(String(value), field);
+}
+/**
+ * Builds the organization-level public identifier from the governed legal URN
+ * grammar. All structural tokens are lower-cased; the official identifier is
+ * preserved exactly after trimming and NFKC normalization.
+ *
+ * Format:
+ * `urn:legal:<sector>:<country>:<admin1>:<admin2>:<admin3>:organization:<type>:<official-id>`
+ */
+export function buildLegalSectorOrganizationUrn(input) {
+    const sector = normalizeRequiredSegment(input.sector, 'sector');
+    const country = normalizeRequiredSegment(input.country, 'country');
+    if (!/^[a-z]{2}$/.test(country)) {
+        throw new Error('Legal sector organization URN requires an ISO 3166-1 alpha-2 country.');
+    }
+    const administrativeSublevel1 = normalizeOptionalSegment(input.administrativeSublevel1, 'administrativeSublevel1');
+    const administrativeSublevel2 = normalizeOptionalSegment(input.administrativeSublevel2, 'administrativeSublevel2');
+    const administrativeSublevel3 = normalizeOptionalSegment(input.administrativeSublevel3, 'administrativeSublevel3');
+    const identifierType = normalizeRequiredSegment(input.identifierType, 'identifierType');
+    const identifierValue = String(input.identifierValue || '').trim().normalize('NFKC');
+    if (!identifierValue || /[:\s]/u.test(identifierValue)) {
+        throw new Error('Legal sector organization URN requires a colon-free identifierValue.');
+    }
+    return [
+        'urn',
+        'legal',
+        sector,
+        country,
+        administrativeSublevel1,
+        administrativeSublevel2,
+        administrativeSublevel3,
+        'organization',
+        identifierType,
+        identifierValue,
+    ].join(':');
+}
+/**
+ * Builds the stable Fabric lookup key for one organization-sector binding.
+ *
+ * The exact canonical legal-sector URN UTF-8 bytes are encoded as
+ * `urn:multibase:base58btc(multihash(SHA3-256))`. A provider/DID rotation does
+ * not change this key; only the binding asset state and history change.
+ */
+export function buildLegalSectorOrganizationAssetId(organizationUrn) {
+    const canonicalUrn = String(organizationUrn || '').trim().normalize('NFKC');
+    const parts = canonicalUrn.split(':');
+    if (parts.length !== 10 || parts[0] !== 'urn' || parts[1] !== 'legal' || parts[7] !== 'organization') {
+        throw new Error('Legal sector organization asset ID requires a canonical organization-level urn:legal identifier.');
+    }
+    const rebuilt = buildLegalSectorOrganizationUrn({
+        sector: parts[2],
+        country: parts[3],
+        administrativeSublevel1: parts[4],
+        administrativeSublevel2: parts[5],
+        administrativeSublevel3: parts[6],
+        identifierType: parts[8],
+        identifierValue: parts[9],
+    });
+    if (rebuilt !== canonicalUrn) {
+        throw new Error('Legal sector organization asset ID requires an already-canonical urn:legal identifier.');
+    }
+    return `${UrnPrefixes.Multibase}${encodeMultibaseSha3(canonicalUrn, 256)}`;
+}

package/dist/utils/organization-lifecycle.d.ts

@@ -39,6 +39,8 @@ export declare class OrganizationLifecycleEditor {
     setIdentifierValue(identifierValue: string): this;
     /** Sets the jurisdiction-defined identifier type independently from its complete value. */
     setIdentifierType(identifierType: string): this;
+    /** Selects the exact hosted tenant DID when one legal organization has multiple sector tenants. */
+    setTenantDid(tenantDid: string): this;
     setTaxId(taxId: string): this;
     setOperation(operation: OrganizationLifecycleOperation): this;
     setRequestType(requestType: string): this;
@@ -48,6 +50,8 @@ export declare class OrganizationLifecycleEditor {
     getIdentifierValue(): string | undefined;
     /** Returns the jurisdiction-defined identifier type used by lifecycle authorization. */
     getIdentifierType(): string | undefined;
+    /** Returns the exact hosted tenant DID selected for this lifecycle operation. */
+    getTenantDid(): string | undefined;
     getTaxId(): string | undefined;
     getOperation(): OrganizationLifecycleOperation;
     getRequestType(): string | undefined;

package/dist/utils/organization-lifecycle.js

@@ -83,6 +83,16 @@ export class OrganizationLifecycleEditor {
         });
         return this;
     }
+    /** Selects the exact hosted tenant DID when one legal organization has multiple sector tenants. */
+    setTenantDid(tenantDid) {
+        this.draft = patchDraft(this.draft, {
+            claims: {
+                ...this.draft.claims,
+                [ClaimsOrganizationSchemaorg.sameAs]: String(tenantDid).trim(),
+            },
+        });
+        return this;
+    }
     setTaxId(taxId) {
         this.draft = patchDraft(this.draft, {
             claims: {
@@ -117,6 +127,10 @@ export class OrganizationLifecycleEditor {
     getIdentifierType() {
         return normalizeText(this.draft.claims[ClaimsOrganizationSchemaorg.identifierType]) || undefined;
     }
+    /** Returns the exact hosted tenant DID selected for this lifecycle operation. */
+    getTenantDid() {
+        return normalizeText(this.draft.claims[ClaimsOrganizationSchemaorg.sameAs]) || undefined;
+    }
     getTaxId() {
         return normalizeText(this.draft.claims[ClaimsOrganizationSchemaorg.taxId]) || undefined;
     }

package/package.json

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