gdc-common-utils-ts 2.4.1 → 2.5.1

package/README.md

@@ -243,11 +243,18 @@ const lookupMultihash = encodeMultibaseSha3('DL|US-CA|D1234567');
 const blockchainAssetId = buildRawCidV1FromUtf8String('DL|US-CA|D1234567');
 ```
 
-Individual lookup tokens keep the identifier type and jurisdiction separate:
-`org.hl7.terminology.CodeSystem.v2-0203.NN|ES|12345678Z`. Import
-`buildIndividualIdentifierLedgerAssetId(...)` when a GW must derive the opaque
-SHA3-384 `urn:multibase` key used by the subject-identifier ledger. The raw
-identifier must never be written to that ledger.
+Canonical Subject-collection lookup tokens use `codingSystem|codeValue`, for
+example `org.hl7.terminology.CodeSystem.v2-0203.NN.ES|12345678Z` or
+`urn:iso:std:iso:11784-11785|981020000123456`. Import
+`buildSubjectIdentifierAssetId(...)` when a GW must derive the opaque SHA3-384
+`urn:multibase` key used by the distributed subject index. The semantic
+`Person`/`Animal` entry keeps the private claims and its `sameAs` points to the
+stable public unified card; the raw identifier must never be written to the
+ledger.
+
+`buildIndividualIdentifierLedgerAssetId(...)` remains the older
+type/jurisdiction/value compatibility helper. Do not use its former
+`Organization.sameAs` convention for new Subject collection writes.
 
 Both helpers hash the exact UTF-8 bytes supplied by the caller. Identifier,
 FHIR-token or JSON canonicalization belongs to the contract that owns the
@@ -443,8 +450,10 @@ The canonical API contract should live in JSDoc on exported code. The README act
 - [`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.
-- [`getOrganizationCredentialFromVpToken(...)`, `getLegalRepresentativeCredentialFromVpToken(...)`](src/utils/vp-token.ts)
+- [`getOrganizationCredentialFromVpToken(...)`, `getLegalRepresentativeCredentialFromVpToken(...)`, `getOrganizationControllerCredentialFromVpToken(...)`](src/utils/vp-token.ts)
   - Extract typed VC objects from a VP token when GW/SDK flows carry canonical proof only in `vp_token`.
+- [`readOrganizationControllerCredentialsFromResponseBody(...)`](src/utils/legal-organization-verification-result.ts)
+  - Reads every independently issued controller service VC from direct ICA or projected GW responses; companion helpers expose `owner.sameAs` and its JWK-thumbprint binding without falling back to the legal representative.
 - [`docs/101-VP_TOKEN.md`](docs/101-VP_TOKEN.md)
   - Step-by-step guide for building the canonical compact `vp_token` string from organization and representative VCs.
 - [`validateCommunicationResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)

package/dist/constants/healthcare.d.ts

@@ -1711,7 +1711,8 @@ export declare const HealthcareConsentPurposes: Readonly<{
     readonly RecordsManagement: "RECORDMGT";
 }>;
 export declare const HealthcareActorRoles: Readonly<{
-    readonly Controller: "ISCO-08|1120";
+    /** Bare HL7 v3 RoleCode used for an organization controller. */
+    readonly Controller: "RESPRSN";
     readonly MedicalDoctors: "ISCO-08|221";
     readonly GeneralistMedicalPractitioner: "ISCO-08|2211";
     readonly SpecialistMedicalPractitioner: "ISCO-08|2212";
@@ -1728,7 +1729,7 @@ export declare const HealthcareActorRoles: Readonly<{
     readonly MedicalSecretary: "ISCO-08|3344";
 }>;
 export declare const HealthcareActorRoleCodes: Readonly<{
-    readonly Controller: "1120";
+    readonly Controller: "RESPRSN";
     readonly MedicalDoctors: "221";
     readonly GeneralistMedicalPractitioner: "2211";
     readonly SpecialistMedicalPractitioner: "2212";
@@ -1779,16 +1780,16 @@ export declare const HealthcareRolesByFamily: Readonly<{
 }>;
 export declare const HealthcareAllRolesByClaim: Readonly<Record<string, HealthcareActorRoleDescriptor>>;
 export declare const HealthcareProfessionalRoleCodesBySector: Readonly<{
-    readonly "health-care": readonly ("1120" | "221" | "2211" | "2212" | "2221" | "2222" | "2240" | "3344")[];
-    readonly "health-research": readonly ("1120" | "221" | "2211" | "2212" | "3344")[];
-    readonly "health-tech": readonly "1120"[];
-    readonly "health-insurance": readonly "1120"[];
-    readonly "animal-care": readonly ("1120" | "2250")[];
-    readonly "animal-research": readonly ("1120" | "2250")[];
-    readonly "animal-insurance": readonly "1120"[];
-    readonly "animal-tech": readonly "1120"[];
-    readonly "onehealth-research": readonly ("1120" | "221" | "2211" | "2212" | "2250" | "3344")[];
-    readonly "onehealth-tech": readonly "1120"[];
+    readonly "health-care": readonly ("RESPRSN" | "221" | "2211" | "2212" | "2221" | "2222" | "2240" | "3344")[];
+    readonly "health-research": readonly ("RESPRSN" | "221" | "2211" | "2212" | "3344")[];
+    readonly "health-tech": readonly "RESPRSN"[];
+    readonly "health-insurance": readonly "RESPRSN"[];
+    readonly "animal-care": readonly ("RESPRSN" | "2250")[];
+    readonly "animal-research": readonly ("RESPRSN" | "2250")[];
+    readonly "animal-insurance": readonly "RESPRSN"[];
+    readonly "animal-tech": readonly "RESPRSN"[];
+    readonly "onehealth-research": readonly ("RESPRSN" | "221" | "2211" | "2212" | "2250" | "3344")[];
+    readonly "onehealth-tech": readonly "RESPRSN"[];
 }>;
 export declare const HealthcareProfessionalRolesBySector: Readonly<{
     readonly "health-care": Readonly<Record<string, Readonly<{

package/dist/constants/healthcare.js

@@ -343,7 +343,8 @@ export const HealthcareConsentPurposes = Object.freeze({
     RecordsManagement: 'RECORDMGT',
 });
 export const HealthcareActorRoles = Object.freeze({
-    Controller: 'ISCO-08|1120',
+    /** Bare HL7 v3 RoleCode used for an organization controller. */
+    Controller: 'RESPRSN',
     MedicalDoctors: 'ISCO-08|221',
     GeneralistMedicalPractitioner: 'ISCO-08|2211',
     SpecialistMedicalPractitioner: 'ISCO-08|2212',
@@ -360,7 +361,7 @@ export const HealthcareActorRoles = Object.freeze({
     MedicalSecretary: 'ISCO-08|3344',
 });
 export const HealthcareActorRoleCodes = Object.freeze({
-    Controller: '1120',
+    Controller: 'RESPRSN',
     MedicalDoctors: '221',
     GeneralistMedicalPractitioner: '2211',
     SpecialistMedicalPractitioner: '2212',
@@ -382,17 +383,6 @@ export const HealthcareActorRoleCodes = Object.freeze({
 });
 function buildProfessionalIscoRoles() {
     const entries = [
-        [
-            HealthcareActorRoleCodes.Controller,
-            Object.freeze({
-                family: HealthcareRoleFamilies.ProfessionalOccupationIsco08,
-                codingSystem: ISCO08_CODING_SYSTEM,
-                code: HealthcareActorRoleCodes.Controller,
-                claim: HealthcareActorRoles.Controller,
-                i18nKey: `${ISCO08_I18N_NAMESPACE}.${HealthcareActorRoleCodes.Controller}`,
-                titleEn: 'Controller',
-            }),
-        ],
         [
             HealthcareActorRoleCodes.MedicalDoctors,
             Object.freeze({
@@ -519,15 +509,25 @@ export const HealthcareRolesByFamily = Object.freeze({
 });
 export const HealthcareAllRolesByClaim = Object.freeze(Object.fromEntries(Object.values(HealthcareRolesByFamily)
     .flatMap((catalog) => Object.values(catalog))
-    .map((descriptor) => [descriptor.claim, descriptor])));
+    .flatMap((descriptor) => [
+    [descriptor.claim, descriptor],
+    [descriptor.code, descriptor],
+])));
 function pickRoleCatalogByCodes(catalog, codes) {
     return Object.freeze(Object.fromEntries(codes
         .map((code) => [code, catalog[code]])
         .filter((entry) => Boolean(entry[1]))));
 }
 function reindexRoleCatalogByClaim(catalog) {
-    return Object.freeze(Object.fromEntries(Object.values(catalog).map((descriptor) => [descriptor.claim, descriptor])));
+    return Object.freeze(Object.fromEntries(Object.values(catalog).flatMap((descriptor) => [
+        [descriptor.claim, descriptor],
+        [descriptor.code, descriptor],
+    ])));
 }
+const HealthcareProfessionalAndControllerRoles = Object.freeze({
+    ...HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08],
+    [HealthcareActorRoleCodes.Controller]: HealthcareRolesByFamily[HealthcareRoleFamilies.LegalRepresentativeHl7][HealthcareActorRoleCodes.Controller],
+});
 export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
     [DataspaceSectors.HealthCare]: Object.freeze([
         HealthcareActorRoleCodes.Controller,
@@ -569,16 +569,16 @@ export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
     [DataspaceSectors.OneHealthTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
 });
 export const HealthcareProfessionalRolesBySector = Object.freeze({
-    [DataspaceSectors.HealthCare]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthCare]),
-    [DataspaceSectors.HealthResearch]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthResearch]),
-    [DataspaceSectors.HealthTech]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthTech]),
-    [DataspaceSectors.HealthInsurance]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthInsurance]),
-    [DataspaceSectors.AnimalCare]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalCare]),
-    [DataspaceSectors.AnimalResearch]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalResearch]),
-    [DataspaceSectors.AnimalInsurance]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalInsurance]),
-    [DataspaceSectors.AnimalTech]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalTech]),
-    [DataspaceSectors.OneHealthResearch]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.OneHealthResearch]),
-    [DataspaceSectors.OneHealthTech]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.OneHealthTech]),
+    [DataspaceSectors.HealthCare]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthCare]),
+    [DataspaceSectors.HealthResearch]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthResearch]),
+    [DataspaceSectors.HealthTech]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthTech]),
+    [DataspaceSectors.HealthInsurance]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthInsurance]),
+    [DataspaceSectors.AnimalCare]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalCare]),
+    [DataspaceSectors.AnimalResearch]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalResearch]),
+    [DataspaceSectors.AnimalInsurance]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalInsurance]),
+    [DataspaceSectors.AnimalTech]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalTech]),
+    [DataspaceSectors.OneHealthResearch]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.OneHealthResearch]),
+    [DataspaceSectors.OneHealthTech]: pickRoleCatalogByCodes(HealthcareProfessionalAndControllerRoles, HealthcareProfessionalRoleCodesBySector[DataspaceSectors.OneHealthTech]),
 });
 export const HealthcareProfessionalRolesBySectorAndClaim = Object.freeze(Object.fromEntries(Object.values(DataspaceSectors).map((sector) => [
     sector,

package/dist/constants/schemaorg.d.ts

@@ -175,6 +175,8 @@ export declare enum ClaimsPersonSchemaorg {
     identifier = "org.schema.Person.identifier",// the URN (composed by the provider)
     identifierType = "org.schema.Person.identifier.additionalType",// retrieved from a form
     identifierValue = "org.schema.Person.identifier.value",// retrieved from a form
+    /** Stable public unified-card URI shared by private identity representations. */
+    sameAs = "org.schema.Person.sameAs",
     /** ICAO transliteration of official given name (including middlenames), family name and addtional surname */
     name = "org.schema.Person.name",
     memberOf = "org.schema.Person.memberOf",// for employees

package/dist/constants/schemaorg.js

@@ -183,6 +183,8 @@ export var ClaimsPersonSchemaorg;
     ClaimsPersonSchemaorg["identifier"] = "org.schema.Person.identifier";
     ClaimsPersonSchemaorg["identifierType"] = "org.schema.Person.identifier.additionalType";
     ClaimsPersonSchemaorg["identifierValue"] = "org.schema.Person.identifier.value";
+    /** Stable public unified-card URI shared by private identity representations. */
+    ClaimsPersonSchemaorg["sameAs"] = "org.schema.Person.sameAs";
     /** ICAO transliteration of official given name (including middlenames), family name and addtional surname */
     ClaimsPersonSchemaorg["name"] = "org.schema.Person.name";
     ClaimsPersonSchemaorg["memberOf"] = "org.schema.Person.memberOf";

package/dist/constants/verifiable-credentials.d.ts

@@ -28,6 +28,7 @@ export declare const ActivationCredentialTypes: Readonly<{
     OrganizationCredential: "OrganizationCredential";
     LegalOrganizationCredential: "LegalOrganizationCredential";
     LegalRepresentativeCredential: "LegalRepresentativeCredential";
+    OrganizationControllerCredential: "OrganizationControllerCredential";
     PersonCredential: "PersonCredential";
 }>;
 /**
@@ -59,6 +60,13 @@ export declare const IndividualCredentialTypes: Readonly<{
  */
 export declare const ContractCredentialTypes: Readonly<{
     InterTenantAccessContractCredential: "InterTenantAccessContractCredential";
+    /** Host/ICA-issued evidence that permits one controller to submit tenant registration. */
+    OrganizationRegistrationAuthorizationCredential: "OrganizationRegistrationAuthorizationCredential";
 }>;
 export declare const ORGANIZATION_ACTIVATION_VC_TYPES: readonly ("OrganizationCredential" | "LegalOrganizationCredential")[];
 export declare const REPRESENTATIVE_ACTIVATION_VC_TYPES: readonly ("LegalRepresentativeCredential" | "PersonCredential")[];
+/**
+ * Canonical credential subtype used to bind an organization tenant service to
+ * one independently authenticated controller actor and its signing key.
+ */
+export declare const ORGANIZATION_CONTROLLER_ACTIVATION_VC_TYPES: readonly "OrganizationControllerCredential"[];

package/dist/constants/verifiable-credentials.js

@@ -30,6 +30,7 @@ export const ActivationCredentialTypes = Object.freeze({
     OrganizationCredential: 'OrganizationCredential',
     LegalOrganizationCredential: 'LegalOrganizationCredential',
     LegalRepresentativeCredential: 'LegalRepresentativeCredential',
+    OrganizationControllerCredential: 'OrganizationControllerCredential',
     PersonCredential: 'PersonCredential',
 });
 /**
@@ -61,6 +62,8 @@ export const IndividualCredentialTypes = Object.freeze({
  */
 export const ContractCredentialTypes = Object.freeze({
     InterTenantAccessContractCredential: 'InterTenantAccessContractCredential',
+    /** Host/ICA-issued evidence that permits one controller to submit tenant registration. */
+    OrganizationRegistrationAuthorizationCredential: 'OrganizationRegistrationAuthorizationCredential',
 });
 export const ORGANIZATION_ACTIVATION_VC_TYPES = Object.freeze([
     ActivationCredentialTypes.OrganizationCredential,
@@ -70,3 +73,10 @@ export const REPRESENTATIVE_ACTIVATION_VC_TYPES = Object.freeze([
     ActivationCredentialTypes.LegalRepresentativeCredential,
     ActivationCredentialTypes.PersonCredential,
 ]);
+/**
+ * Canonical credential subtype used to bind an organization tenant service to
+ * one independently authenticated controller actor and its signing key.
+ */
+export const ORGANIZATION_CONTROLLER_ACTIVATION_VC_TYPES = Object.freeze([
+    ActivationCredentialTypes.OrganizationControllerCredential,
+]);

package/dist/examples/employee.d.ts

@@ -27,7 +27,7 @@ export declare const ExampleEmployeeCredentialMaterials: Readonly<{
     readonly SharedProfessionalSigningKid: "did:key:z6Mkt2p7vKov6R6By7QjFv2F5x8f4H9g2m3c4n5p6q7r8s9t#z6Mkt2p7vKov6R6By7QjFv2F5x8f4H9g2m3c4n5p6q7r8s9t";
 }>;
 export declare const ExampleEmployeeRoles: Readonly<{
-    readonly Controller: "ISCO-08|1120";
+    readonly Controller: "RESPRSN";
     readonly Doctor: "ISCO-08|2211";
 }>;
 export declare const EXAMPLE_EMPLOYEE_CONTROLLER_ACTIVE: ExampleEmployeeRecord;

package/dist/examples/employee.js

@@ -9,12 +9,12 @@ export const ExampleEmployeeCredentialMaterials = Object.freeze({
     SharedProfessionalSigningKid: 'did:key:z6Mkt2p7vKov6R6By7QjFv2F5x8f4H9g2m3c4n5p6q7r8s9t#z6Mkt2p7vKov6R6By7QjFv2F5x8f4H9g2m3c4n5p6q7r8s9t',
 });
 export const ExampleEmployeeRoles = Object.freeze({
-    Controller: 'ISCO-08|1120',
+    Controller: 'RESPRSN',
     Doctor: 'ISCO-08|2211',
 });
 export const EXAMPLE_EMPLOYEE_CONTROLLER_ACTIVE = Object.freeze({
     resourceId: 'urn:uuid:11111111-1111-4111-8111-111111111111',
-    identifier: 'did:web:api.example.org:employee:shared.professional@example.org:ISCO-08|1120',
+    identifier: 'did:web:api.example.org:employee:shared.professional@example.org:RESPRSN',
     email: ExampleEmployeeEmails.SharedProfessional,
     role: ExampleEmployeeRoles.Controller,
     status: 'active',

package/dist/examples/ica-activation-proof.d.ts

@@ -24,8 +24,6 @@ export declare const EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID: "urn:ietf:params:oau
 export declare const EXAMPLE_PRESENTATION_AUDIENCE_HOST_ID: "host:node-operator-es";
 export declare const EXAMPLE_ORGANIZATION_TAX_ID: "ESB00112233";
 export declare const EXAMPLE_REPRESENTATIVE_ROLE_CODE: "RESPRSN";
-export declare const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_CODE: "1120";
-export declare const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_IDENTIFIER: "urn:ilo:ilostat:isco-08:1120";
 export declare const EXAMPLE_REPRESENTATIVE_IDENTIFIER: "IDCES-99999999R";
 export declare const EXAMPLE_REPRESENTATIVE_EMAIL: "legal.rep@example.org";
 export declare const EXAMPLE_REPRESENTATIVE_SUBJECT_URN: "urn:person:identifier:IDCES-99999999R";
@@ -57,7 +55,7 @@ export declare const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL: Rea
             taxID: "ESB00112233";
         };
         hasOccupation: {
-            identifier: "urn:ilo:ilostat:isco-08:1120";
+            identifier: "RESPRSN";
         };
         hasCredential: {
             material: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";

package/dist/examples/ica-activation-proof.js

@@ -30,8 +30,6 @@ export const EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID = `${UrnPrefixes.JwkThumbprin
 export const EXAMPLE_PRESENTATION_AUDIENCE_HOST_ID = 'host:node-operator-es';
 export const EXAMPLE_ORGANIZATION_TAX_ID = 'ESB00112233';
 export const EXAMPLE_REPRESENTATIVE_ROLE_CODE = 'RESPRSN';
-export const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_CODE = '1120';
-export const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_IDENTIFIER = 'urn:ilo:ilostat:isco-08:1120';
 export const EXAMPLE_REPRESENTATIVE_IDENTIFIER = 'IDCES-99999999R';
 export const EXAMPLE_REPRESENTATIVE_EMAIL = 'legal.rep@example.org';
 export const EXAMPLE_REPRESENTATIVE_SUBJECT_URN = `urn:person:identifier:${EXAMPLE_REPRESENTATIVE_IDENTIFIER}`;
@@ -69,7 +67,7 @@ export const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL = Object.fre
             taxID: EXAMPLE_ORGANIZATION_TAX_ID,
         },
         hasOccupation: {
-            identifier: EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_IDENTIFIER,
+            identifier: EXAMPLE_REPRESENTATIVE_ROLE_CODE,
         },
         hasCredential: {
             material: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,

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

@@ -99,7 +99,7 @@ export declare const EXAMPLE_VERIFY_RESPONSE_ADDRESS_TYPE: "PostalAddress";
 export declare const EXAMPLE_VERIFY_RESPONSE_ADDRESS_COUNTRY: "ES";
 export declare const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_TYPE: "Occupation";
 export declare const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_NAME: "LegalRepresentative";
-export declare const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_IDENTIFIER: "urn:ilo:ilostat:isco-08:1120";
+export declare const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_IDENTIFIER: "RESPRSN";
 export declare const EXAMPLE_VERIFY_RESPONSE_PROOF_TYPE: "JsonWebSignature2020";
 export declare const EXAMPLE_VERIFY_RESPONSE_PROOF_PURPOSE: "assertionMethod";
 export declare const EXAMPLE_VERIFY_RESPONSE_PROOF_VERIFICATION_METHOD: "did:web:localhost%3A3310#verification-key-001";
@@ -197,7 +197,7 @@ export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL: Readonly<{
         hasOccupation: {
             '@type': "Occupation";
             name: "LegalRepresentative";
-            identifier: "urn:ilo:ilostat:isco-08:1120";
+            identifier: "RESPRSN";
         };
         memberOf: {
             '@type': "Organization";

package/dist/examples/ica-verify-response.js

@@ -44,7 +44,7 @@ export const EXAMPLE_VERIFY_RESPONSE_ADDRESS_TYPE = 'PostalAddress';
 export const EXAMPLE_VERIFY_RESPONSE_ADDRESS_COUNTRY = 'ES';
 export const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_TYPE = 'Occupation';
 export const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_NAME = 'LegalRepresentative';
-export const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_IDENTIFIER = 'urn:ilo:ilostat:isco-08:1120';
+export const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_IDENTIFIER = 'RESPRSN';
 export const EXAMPLE_VERIFY_RESPONSE_PROOF_TYPE = 'JsonWebSignature2020';
 export const EXAMPLE_VERIFY_RESPONSE_PROOF_PURPOSE = 'assertionMethod';
 export const EXAMPLE_VERIFY_RESPONSE_PROOF_VERIFICATION_METHOD = 'did:web:localhost%3A3310#verification-key-001';

package/dist/models/device-license.d.ts

@@ -162,8 +162,8 @@ export interface DeviceLicense {
     /** All DCR installations bound to this user/member seat. */
     deviceBindings?: DeviceBinding[];
     /**
-     * Stable private actor identifier:
-     * `urn:multibase:<hash(normalized email or phone)>:<professional|personal>`.
+     * Stable private contact identifier: `urn:multibase:<hash(normalized email or phone)>`.
+     * The canonical ISCO-08/FHIR-v3 role is stored separately in `issuedToRole`.
      * Portal DIDs, IdP subjects, wallets and DCR clients bind to this value but do not define it.
      */
     activatedBy?: string;

package/dist/models/did.d.ts

@@ -45,6 +45,8 @@ export interface DidDocument {
     '@context': string | string[];
     /** The DID URI itself. */
     id: string;
+    /** Independent DID subjects authorized to control this DID. */
+    controller?: string | string[];
     /** Public keys used for verifying digital signatures */
     verificationMethod?: VerificationMethod[];
     /**

package/dist/models/index.d.ts

@@ -51,6 +51,7 @@ export * from './resource-document';
 export * from './relationship-access';
 export * from './response';
 export * from './subject-identifier-ledger';
+export * from './subject-identity';
 export * from './subject-identity-binding';
 export * from './terminology';
 export * from './urlPath';

package/dist/models/index.js

@@ -51,6 +51,7 @@ export * from './resource-document.js';
 export * from './relationship-access.js';
 export * from './response.js';
 export * from './subject-identifier-ledger.js';
+export * from './subject-identity.js';
 export * from './subject-identity-binding.js';
 export * from './terminology.js';
 export * from './urlPath.js';

package/dist/models/subject-identifier-ledger.d.ts

@@ -6,11 +6,22 @@ export type SubjectIdentifierProviderPointer = Readonly<{
     /** Bare DNS domain: no URL scheme, path, DID or tenant identifier. */
     url: string;
 }>;
-/** Ledger payload. It deliberately contains no subject DID or raw identifier. */
+/** Public unified-card pointer resolved from an exact known identifier. */
+export type SubjectIdentifierCardPointer = Readonly<{
+    identifier: Readonly<{
+        value: string;
+    }>;
+    subjectKind: 'person' | 'animal' | 'property';
+}>;
+/** Ledger payload. It deliberately contains no raw private identifier. */
 export type SubjectIdentifierLedgerPayload = Readonly<{
+    card: SubjectIdentifierCardPointer;
     provider: SubjectIdentifierProviderPointer;
 }>;
-/** One individual/animal bundle entry expanded into one write per `sameAs` alias. */
+/**
+ * @deprecated Parse canonical Person/Animal/Place Bundle entries with
+ * `readSubjectIdentityBundleEntry` instead. Kept for 2.x compatibility only.
+ */
 export type SubjectIdentifierLedgerBundleEntry = Readonly<{
     sameAs: string | readonly string[];
 }>;

package/dist/models/subject-identity.d.ts

@@ -0,0 +1,36 @@
+import type { BundleEntry } from './bundle';
+/** Subject categories supported by the neutral identity collection. */
+export type SubjectKind = 'person' | 'animal' | 'property';
+/** Semantic resource types stored inside the neutral Subject collection. */
+export type SubjectIdentityResourceType = 'Person' | 'Animal' | 'Place';
+/** Exact private identifier input linked to one public unified card. */
+export type SubjectIdentityInput = Readonly<{
+    subjectKind: SubjectKind;
+    cardId: string;
+    /** Canonical identifier type/coding system. */
+    codingSystem: string;
+    /** ISO jurisdiction for scoped identifiers; empty for a global identifier. */
+    jurisdiction: string;
+    codeValue: string;
+    /** Additional encrypted claims; canonical identifier and sameAs keys cannot be overridden. */
+    additionalClaims?: Readonly<Record<string, unknown>>;
+}>;
+/** Normalized association recovered from one Subject collection entry. */
+export type SubjectIdentityAssociation = SubjectIdentityInput & Readonly<{
+    resourceType: SubjectIdentityResourceType;
+    assetId: string;
+}>;
+/** Bundle entry used to write one semantic identity into the Subject collection. */
+export type SubjectIdentityBundleEntry = BundleEntry & Readonly<{
+    type: 'Subject-identity-link-v1.0';
+    resource: NonNullable<BundleEntry['resource']> & Readonly<{
+        resourceType: SubjectIdentityResourceType;
+        meta: {
+            claims: Record<string, unknown>;
+        };
+    }>;
+    request: {
+        method: 'POST';
+        url: 'Subject';
+    };
+}>;

package/dist/models/subject-identity.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/activation-policy.d.ts

@@ -88,11 +88,8 @@ export declare function extractDidWebFromCredential(credential: unknown): string
  * Checks whether the representative role expresses the activation-controller
  * semantics accepted by GW.
  *
- * Compatibility rules:
- * - historical GW payloads may still use HL7/FHIR `RESPRSN`
- * - current ICA person credentials may encode the legal representative role as
- *   ISCO-08 `1120`, either tokenized (`ISCO-08|1120`) or as the canonical
- *   ILO URN (`urn:ilo:ilostat:isco-08:1120`)
+ * The controller/legal-representative authorization is the bare HL7 v3 code
+ * `RESPRSN`. ISCO occupation `1120` is not a controller authorization role.
  *
  * @param roleCode Candidate role token extracted from the credential.
  * @param requiredCode Required GW compatibility code, defaults to `RESPRSN`.

package/dist/utils/activation-policy.js

@@ -187,22 +187,14 @@ export function extractDidWebFromCredential(credential) {
  * Checks whether the representative role expresses the activation-controller
  * semantics accepted by GW.
  *
- * Compatibility rules:
- * - historical GW payloads may still use HL7/FHIR `RESPRSN`
- * - current ICA person credentials may encode the legal representative role as
- *   ISCO-08 `1120`, either tokenized (`ISCO-08|1120`) or as the canonical
- *   ILO URN (`urn:ilo:ilostat:isco-08:1120`)
+ * The controller/legal-representative authorization is the bare HL7 v3 code
+ * `RESPRSN`. ISCO occupation `1120` is not a controller authorization role.
  *
  * @param roleCode Candidate role token extracted from the credential.
  * @param requiredCode Required GW compatibility code, defaults to `RESPRSN`.
  */
 export function hasActivationRepresentativeRole(roleCode, requiredCode = 'RESPRSN') {
-    if (hasRoleCode(roleCode, requiredCode))
-        return true;
-    const normalized = String(roleCode || '').trim().toUpperCase();
-    if (!normalized)
-        return false;
-    return /(?:^|[|:])1120$/.test(normalized);
+    return hasRoleCode(roleCode, requiredCode);
 }
 /**
  * Extracts the categories authorized by an ICA-issued organization credential.
@@ -354,7 +346,7 @@ export function validateActivationRepresentativePolicy(input) {
     if (!hasActivationRepresentativeRole(roleCode, input.requiredRoleCode || 'RESPRSN')) {
         errors.push({
             code: 'MISSING_REPRESENTATIVE_ROLE_RESPRSN',
-            message: 'ICA-issued representative credential must include legal representative role semantics (RESPRSN or ISCO-08 1120) in credentialSubject.hasOccupation.',
+            message: 'ICA-issued representative credential must include controller role RESPRSN in credentialSubject.hasOccupation.',
         });
     }
     const binding = extractRepresentativeCredentialBinding(input.representativeCredential);

package/dist/utils/actor-identifier.d.ts

@@ -1,17 +1,11 @@
-/** Cross-portal actor classes. These are intentionally broader than job roles. */
-export declare const StableActorRoles: Readonly<{
-    readonly Professional: "professional";
-    readonly Personal: "personal";
-}>;
-export type StableActorRole = typeof StableActorRoles[keyof typeof StableActorRoles];
 export type StableActorContactKind = 'email' | 'phone';
 /**
  * Builds the private, stable actor identifier shared by independent portals.
  *
- * Wire format: `urn:multibase:<multibase(multihash(SHA3-256, normalized-contact))>:<role>`.
- * Examples end in `:professional` or `:personal`; the clear email/phone is
- * never embedded. A portal-specific `did:web`, IdP `sub`, wallet and DCR
- * `client_id` are bindings to this identifier, not replacements for it.
+ * Wire format: `urn:multibase:<multibase(multihash(SHA3-256, normalized-contact))>`.
+ * The clear email/phone and the actor role are never embedded. ISCO-08 or
+ * FHIR v3 roles are persisted separately in `Person.hasOccupation` and may be
+ * represented separately in an employee/member DID.
  *
  * Email is trimmed, stripped of `mailto:` and lower-cased. Phone is stripped
  * of `tel:` and formatting while preserving an E.164 leading `+`.
@@ -19,15 +13,17 @@ export type StableActorContactKind = 'email' | 'phone';
 export declare function buildStableActorIdentifier(input: {
     contactKind: StableActorContactKind;
     contact: string;
-    role: StableActorRole;
 }): string;
 /**
- * Builds a portal-specific DID binding that carries the stable actor payload.
- * The portal root can change while the final actor payload remains identical.
+ * Builds a portal-specific employee DID binding. The stable actor payload and
+ * the canonical ISCO-08/FHIR-v3 role remain distinct path components.
+ *
+ * @deprecated Use `buildProfessionalDidWeb` for organization employees.
  */
 export declare function buildPortalActorDidWeb(input: {
     portalDidWeb: string;
     actorIdentifier: string;
+    role: string;
 }): string;
 /**
  * Extracts the stable actor URN from a canonical GDC portal actor DID.

package/dist/utils/actor-identifier.js

@@ -1,26 +1,17 @@
 import { normalizePhone } from './consent.js';
-import { multibase58MultihashSha3_256 } from './same-as.js';
-/** Cross-portal actor classes. These are intentionally broader than job roles. */
-export const StableActorRoles = Object.freeze({
-    Professional: 'professional',
-    Personal: 'personal',
-});
+import { normalizeSameAsHash, normalizeTelephoneHash } from './same-as.js';
 /**
  * Builds the private, stable actor identifier shared by independent portals.
  *
- * Wire format: `urn:multibase:<multibase(multihash(SHA3-256, normalized-contact))>:<role>`.
- * Examples end in `:professional` or `:personal`; the clear email/phone is
- * never embedded. A portal-specific `did:web`, IdP `sub`, wallet and DCR
- * `client_id` are bindings to this identifier, not replacements for it.
+ * Wire format: `urn:multibase:<multibase(multihash(SHA3-256, normalized-contact))>`.
+ * The clear email/phone and the actor role are never embedded. ISCO-08 or
+ * FHIR v3 roles are persisted separately in `Person.hasOccupation` and may be
+ * represented separately in an employee/member DID.
  *
  * Email is trimmed, stripped of `mailto:` and lower-cased. Phone is stripped
  * of `tel:` and formatting while preserving an E.164 leading `+`.
  */
 export function buildStableActorIdentifier(input) {
-    const role = String(input.role || '').trim();
-    if (!Object.values(StableActorRoles).includes(role)) {
-        throw new Error('Stable actor role must be professional or personal.');
-    }
     const rawContact = String(input.contact || '').trim();
     const normalizedContact = input.contactKind === 'email'
         ? rawContact.replace(/^mailto:/i, '').replace(/\s+/g, '').toLowerCase()
@@ -28,31 +19,39 @@ export function buildStableActorIdentifier(input) {
     if (!normalizedContact) {
         throw new Error(`Stable actor ${input.contactKind} is required.`);
     }
-    return `urn:multibase:${multibase58MultihashSha3_256(normalizedContact)}:${role}`;
+    return input.contactKind === 'email'
+        ? normalizeSameAsHash(normalizedContact)
+        : normalizeTelephoneHash(normalizedContact);
 }
 /**
- * Builds a portal-specific DID binding that carries the stable actor payload.
- * The portal root can change while the final actor payload remains identical.
+ * Builds a portal-specific employee DID binding. The stable actor payload and
+ * the canonical ISCO-08/FHIR-v3 role remain distinct path components.
+ *
+ * @deprecated Use `buildProfessionalDidWeb` for organization employees.
  */
 export function buildPortalActorDidWeb(input) {
     const portalDidWeb = String(input.portalDidWeb || '').trim();
-    const match = /^urn:multibase:(z[^:]+):(professional|personal)$/.exec(String(input.actorIdentifier || '').trim());
+    const match = /^urn:multibase:(z[^:]+)$/.exec(String(input.actorIdentifier || '').trim());
+    const role = String(input.role || '').trim();
     if (!portalDidWeb.startsWith('did:web:')) {
         throw new Error('Portal actor binding requires a did:web root.');
     }
     if (!match) {
         throw new Error('Portal actor binding requires a stable actor URN.');
     }
-    return `${portalDidWeb}:actor:multibase:${match[1]}:${match[2]}`;
+    if (!role) {
+        throw new Error('Portal actor binding requires a canonical role.');
+    }
+    return `${portalDidWeb}:employee:${match[1]}:${role}`;
 }
 /**
  * Extracts the stable actor URN from a canonical GDC portal actor DID.
  * This is extraction, not reversal of the contact hash.
  */
 export function stableActorIdentifierFromDidWeb(didWeb) {
-    const match = /:actor:multibase:(z[^:]+):(professional|personal)(?::|$)/.exec(String(didWeb || '').trim());
+    const match = /:employee:(z[^:]+):[^:]+(?:[:]|$)/.exec(String(didWeb || '').trim());
     if (!match) {
         throw new Error('DID does not contain a canonical GDC actor binding.');
     }
-    return `urn:multibase:${match[1]}:${match[2]}`;
+    return `urn:multibase:${match[1]}`;
 }