gdc-common-utils-ts 2.5.0 → 2.5.2

package/README.md

@@ -450,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/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/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]}`;
 }

package/dist/utils/index.d.ts

@@ -83,6 +83,7 @@ export * from './jwt-signer';
 export * from './jwk-thumbprint';
 export * from './legal-organization-onboarding';
 export * from './legal-organization-verification-transaction';
+export * from './organization-registration-authorization';
 export * from './local-terminology-provider';
 export * from './license';
 export * from './license-commercial-search';

package/dist/utils/index.js

@@ -83,6 +83,7 @@ export * from './jwt-signer.js';
 export * from './jwk-thumbprint.js';
 export * from './legal-organization-onboarding.js';
 export * from './legal-organization-verification-transaction.js';
+export * from './organization-registration-authorization.js';
 export * from './local-terminology-provider.js';
 export * from './license.js';
 export * from './license-commercial-search.js';

package/dist/utils/jwk-thumbprint.d.ts

@@ -38,3 +38,11 @@ export declare function computeRfc7638JwkThumbprint(jwk: ThumbprintableJwk): str
  * `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
  */
 export declare function toJwkThumbprintSha256Urn(jwk: ThumbprintableJwk): string;
+/**
+ * Returns a public JWK whose `kid` is derived exclusively from its public key
+ * material. Caller-provided aliases are deliberately replaced so DID methods,
+ * credentials and confidential-storage indexes share one RFC 9278 identifier.
+ */
+export declare function withJwkThumbprintSha256Kid<T extends ThumbprintableJwk>(jwk: T): T & {
+    kid: string;
+};

package/dist/utils/jwk-thumbprint.js

@@ -55,3 +55,14 @@ export function computeRfc7638JwkThumbprint(jwk) {
 export function toJwkThumbprintSha256Urn(jwk) {
     return `${UrnPrefixes.JwkThumbprintSha256KeyId}${computeRfc7638JwkThumbprint(jwk)}`;
 }
+/**
+ * Returns a public JWK whose `kid` is derived exclusively from its public key
+ * material. Caller-provided aliases are deliberately replaced so DID methods,
+ * credentials and confidential-storage indexes share one RFC 9278 identifier.
+ */
+export function withJwkThumbprintSha256Kid(jwk) {
+    return {
+        ...jwk,
+        kid: toJwkThumbprintSha256Urn(jwk),
+    };
+}

package/dist/utils/legal-organization-onboarding-editor.d.ts

@@ -106,6 +106,7 @@ export interface LegalOrganizationOnboardingFacade {
     buildVerificationTransactionInput(fields: LegalOrganizationFormTemplateFields, input: Readonly<{
         controller: LegalOrganizationVerificationTransactionController;
         organization?: LegalOrganizationVerificationTransactionOrganization;
+        /** @deprecated Legacy demo/OTP compatibility input. */
         legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
         verification?: LegalOrganizationVerificationRouting;
         attachments?: unknown[];
@@ -146,6 +147,7 @@ export interface LegalOrganizationOnboardingEditor {
     buildVerificationTransactionInput(input: Readonly<{
         controller: LegalOrganizationVerificationTransactionController;
         organization?: LegalOrganizationVerificationTransactionOrganization;
+        /** @deprecated Legacy demo/OTP compatibility input. */
         legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
         verification?: LegalOrganizationVerificationRouting;
         attachments?: unknown[];

package/dist/utils/legal-organization-onboarding-editor.js

@@ -304,9 +304,7 @@ export function createLegalOrganizationOnboardingFacade() {
                         ...(controllerEmail ? { email: controllerEmail } : {}),
                         ...(representativeSameAs ? { sameAs: representativeSameAs } : {}),
                     }
-                    : controllerEmail
-                        ? { email: controllerEmail }
-                        : undefined,
+                    : undefined,
                 verification: {
                     resourceType: normalizeOptionalText(input.verificationResourceType) || 'contract',
                 },

package/dist/utils/legal-organization-verification-result.d.ts

@@ -4,6 +4,27 @@ export type LegalOrganizationVerificationCredentialPair = Readonly<{
     organizationCredential: LegalOrganizationVerificationCredential;
     legalRepresentativeCredential: LegalOrganizationVerificationCredential;
 }>;
+/**
+ * Extracts the controller actor stored at
+ * `credentialSubject.owner` in an organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export declare function extractOrganizationControllerOwner(credential: unknown): Record<string, unknown> | undefined;
+/**
+ * Extracts the stable public actor identifier from an
+ * organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export declare function extractOrganizationControllerSameAs(credential: unknown): string | undefined;
+/**
+ * Extracts the RFC 9278 JWK-thumbprint binding from an
+ * organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export declare function extractOrganizationControllerBinding(credential: unknown): string | undefined;
 /**
  * Returns the ICA verification entries currently projected by GW host
  * legal-organization `_transaction`.
@@ -35,3 +56,27 @@ export declare function readLegalRepresentativeSameAsFromResponseBody(responseBo
  * legal-representative credential when present.
  */
 export declare function readLegalRepresentativeBindingFromResponseBody(responseBody: unknown): string | undefined;
+/**
+ * Returns all independently issued organization-controller service
+ * credentials in an ICA or projected GW verification response.
+ *
+ * The result is empty when the response contains only the legacy organization
+ * and legal-representative credential pair.
+ */
+export declare function readOrganizationControllerCredentialsFromResponseBody(responseBody: unknown): LegalOrganizationVerificationCredential[];
+/**
+ * Returns one organization-controller service credential in an ICA or
+ * projected GW verification response. Pass a stable actor `sameAs` to select
+ * one controller independently; otherwise the first controller is returned.
+ */
+export declare function readOrganizationControllerCredentialFromResponseBody(responseBody: unknown, controllerSameAs?: string): LegalOrganizationVerificationCredential | undefined;
+/**
+ * Reads `credentialSubject.owner.sameAs` from the first
+ * organization-controller service credential when present.
+ */
+export declare function readOrganizationControllerSameAsFromResponseBody(responseBody: unknown): string | undefined;
+/**
+ * Reads `credentialSubject.owner.hasCredential.material` from the first
+ * organization-controller service credential when present.
+ */
+export declare function readOrganizationControllerBindingFromResponseBody(responseBody: unknown): string | undefined;

package/dist/utils/legal-organization-verification-result.js

@@ -23,6 +23,45 @@ function findCredentialResource(entries, expectedTypeFragment, fallbackIndex) {
     }
     return resource;
 }
+function hasCredentialType(value, expectedType) {
+    const candidate = asObject(value);
+    const resource = asObject(candidate?.resource);
+    const typeValues = [candidate?.type, resource?.type];
+    return typeValues.some((typeValue) => {
+        const tokens = Array.isArray(typeValue)
+            ? typeValue.map((token) => String(token || ''))
+            : [String(typeValue || '')];
+        return tokens.some((token) => token.includes(expectedType));
+    });
+}
+/**
+ * Extracts the controller actor stored at
+ * `credentialSubject.owner` in an organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export function extractOrganizationControllerOwner(credential) {
+    return asObject(extractCredentialSubject(credential)?.owner);
+}
+/**
+ * Extracts the stable public actor identifier from an
+ * organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export function extractOrganizationControllerSameAs(credential) {
+    return String(extractOrganizationControllerOwner(credential)?.sameAs || '').trim() || undefined;
+}
+/**
+ * Extracts the RFC 9278 JWK-thumbprint binding from an
+ * organization-controller service VC.
+ *
+ * @param credential Candidate organization-controller credential.
+ */
+export function extractOrganizationControllerBinding(credential) {
+    const owner = extractOrganizationControllerOwner(credential);
+    return owner ? extractRepresentativeCredentialBinding({ credentialSubject: owner }) : undefined;
+}
 /**
  * Returns the ICA verification entries currently projected by GW host
  * legal-organization `_transaction`.
@@ -104,3 +143,42 @@ export function readLegalRepresentativeBindingFromResponseBody(responseBody) {
     const pair = readLegalOrganizationVerificationCredentialPairFromResponseBody(responseBody);
     return extractRepresentativeCredentialBinding(pair.legalRepresentativeCredential);
 }
+/**
+ * Returns all independently issued organization-controller service
+ * credentials in an ICA or projected GW verification response.
+ *
+ * The result is empty when the response contains only the legacy organization
+ * and legal-representative credential pair.
+ */
+export function readOrganizationControllerCredentialsFromResponseBody(responseBody) {
+    return getLegalOrganizationVerificationEntriesFromResponseBody(responseBody)
+        .filter((entry) => hasCredentialType(entry, 'OrganizationControllerCredential'))
+        .map((entry) => asObject(asObject(entry)?.resource) || asObject(entry))
+        .filter((entry) => Boolean(entry));
+}
+/**
+ * Returns one organization-controller service credential in an ICA or
+ * projected GW verification response. Pass a stable actor `sameAs` to select
+ * one controller independently; otherwise the first controller is returned.
+ */
+export function readOrganizationControllerCredentialFromResponseBody(responseBody, controllerSameAs) {
+    const credentials = readOrganizationControllerCredentialsFromResponseBody(responseBody);
+    const expectedSameAs = String(controllerSameAs || '').trim();
+    return expectedSameAs
+        ? credentials.find((credential) => extractOrganizationControllerSameAs(credential) === expectedSameAs)
+        : credentials[0];
+}
+/**
+ * Reads `credentialSubject.owner.sameAs` from the first
+ * organization-controller service credential when present.
+ */
+export function readOrganizationControllerSameAsFromResponseBody(responseBody) {
+    return extractOrganizationControllerSameAs(readOrganizationControllerCredentialFromResponseBody(responseBody));
+}
+/**
+ * Reads `credentialSubject.owner.hasCredential.material` from the first
+ * organization-controller service credential when present.
+ */
+export function readOrganizationControllerBindingFromResponseBody(responseBody) {
+    return extractOrganizationControllerBinding(readOrganizationControllerCredentialFromResponseBody(responseBody));
+}

package/dist/utils/legal-organization-verification-transaction.d.ts

@@ -1,5 +1,6 @@
 import type { BundleJsonApi } from '../models/bundle';
 import type { ClaimsRecord } from '../models/resource-document';
+import type { VerifiableCredentialV2 } from '../models/verifiable-credential';
 /**
  * Canonical business entry type for the first host-side onboarding step that
  * asks GW CORE to forward a legal-organization verification request to ICA.
@@ -71,8 +72,14 @@ export type LegalOrganizationVerificationTransactionInput = Readonly<{
     claims: ClaimsRecord;
     controller: LegalOrganizationVerificationTransactionController;
     organization?: LegalOrganizationVerificationTransactionOrganization;
+    /**
+     * @deprecated Legacy demo/OTP compatibility only. Canonical signed-PDF and
+     * strict flows derive the representative from verified evidence.
+     */
     legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
     verification?: LegalOrganizationVerificationRouting;
+    /** Out-of-band host authorization used only by the Test Network path. */
+    authorizationCredential?: VerifiableCredentialV2;
     attachments?: unknown[];
 }>;
 export type LegalOrganizationVerificationTransactionEntry = Readonly<{
@@ -84,9 +91,12 @@ export type LegalOrganizationVerificationTransactionEntry = Readonly<{
     resource?: {
         controller?: LegalOrganizationVerificationTransactionController;
         organization?: LegalOrganizationVerificationTransactionOrganization;
+        /** @deprecated Legacy demo/OTP compatibility input. */
         legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
+        /** @deprecated Legacy ICA wire alias accepted only while migrating old callers. */
         legalRepresentative?: LegalOrganizationVerificationRepresentativePayload;
         verification?: LegalOrganizationVerificationRouting;
+        authorizationCredential?: VerifiableCredentialV2;
         [key: string]: unknown;
     };
     [key: string]: unknown;
@@ -122,6 +132,9 @@ export declare function getLegalOrganizationVerificationController(value: unknow
  * Returns the normalized legal representative contact payload from the first
  * legal-organization verification transaction entry when present.
  *
+ * @deprecated Read-only support for legacy demo/OTP payloads. Canonical
+ * signed-PDF and strict flows derive the representative from verified evidence.
+ *
  * Compatibility note:
  * - GW/SDK request builders use `resource.legalRepresentativePayload`
  * - the ICA forwarding payload currently uses `resource.legalRepresentative`

package/dist/utils/legal-organization-verification-transaction.js

@@ -61,6 +61,9 @@ export function buildLegalOrganizationVerificationTransactionBundle(input) {
                     verification: {
                         resourceType: normalizeText(input.verification?.resourceType) || 'contract',
                     },
+                    ...(input.authorizationCredential
+                        ? { authorizationCredential: input.authorizationCredential }
+                        : {}),
                 },
             }],
         ...(Array.isArray(input.attachments) && input.attachments.length > 0
@@ -98,6 +101,9 @@ export function getLegalOrganizationVerificationController(value) {
  * Returns the normalized legal representative contact payload from the first
  * legal-organization verification transaction entry when present.
  *
+ * @deprecated Read-only support for legacy demo/OTP payloads. Canonical
+ * signed-PDF and strict flows derive the representative from verified evidence.
+ *
  * Compatibility note:
  * - GW/SDK request builders use `resource.legalRepresentativePayload`
  * - the ICA forwarding payload currently uses `resource.legalRepresentative`

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

@@ -0,0 +1,71 @@
+import type { VerifiableCredentialV2 } from '../models/verifiable-credential';
+/** Lifecycle of the one GW activation licence delivered to the legal postal address. */
+export declare const PostalActivationLicenseStatuses: Readonly<{
+    readonly Issued: "issued";
+    readonly Delivered: "delivered";
+    readonly Redeemed: "redeemed";
+    readonly Revoked: "revoked";
+    readonly Expired: "expired";
+}>;
+export type PostalActivationLicenseStatus = typeof PostalActivationLicenseStatuses[keyof typeof PostalActivationLicenseStatuses];
+/**
+ * Public binding recorded for the activation licence. The activation code is
+ * deliberately absent. The VC carries only a salted, pepper-dependent scrypt
+ * binding so the host can verify the same code later without disclosing it or
+ * enabling offline guessing from the credential alone.
+ */
+export type PostalActivationLicenseBinding = Readonly<{
+    licenseId: string;
+    applicationId: string;
+    organizationIdentifier: string;
+    controllerEmail: string;
+    controllerKeyMaterial: string;
+    postalAddressHash: string;
+    protectedCode: Readonly<{
+        algorithm: 'scrypt-v1';
+        salt: string;
+        digest: string;
+    }>;
+    hostDid: string;
+    network: 'test-network' | 'network';
+    status: PostalActivationLicenseStatus;
+    issuedAt: string;
+    expiresAt: string;
+    deliveredAt?: string;
+    redeemedAt?: string;
+}>;
+/** Input for the credential returned out-of-band to the applicant controller. */
+export type OrganizationRegistrationAuthorizationCredentialInput = Readonly<{
+    issuerDid: string;
+    subjectDid: string;
+    credentialId: string;
+    validFrom: string;
+    validUntil: string;
+    legalName: string;
+    organizationIdentifier: string;
+    controllerEmail: string;
+    controllerKeyMaterial: string;
+    applicationId: string;
+    accessPath: 'partner' | 'test-network';
+    targetNetwork: 'test-network' | 'network';
+    postalLicense: PostalActivationLicenseBinding;
+    proof?: VerifiableCredentialV2['proof'];
+}>;
+/**
+ * Builds the immutable VC that a controller receives out-of-band and attaches
+ * to `Organization/_transaction`. The postal code itself never appears in the
+ * credential; its confirmed, purpose-bound licence record is referenced.
+ */
+export declare function buildOrganizationRegistrationAuthorizationCredential(input: OrganizationRegistrationAuthorizationCredentialInput): VerifiableCredentialV2;
+/**
+ * Applies the only legal state transitions for the purpose-bound postal code.
+ * Confirmation proves delivery but deliberately does not consume the code;
+ * redemption occurs later during `_exchange`.
+ */
+export declare function transitionPostalActivationLicense(current: PostalActivationLicenseStatus, action: 'mark_delivered' | 'redeem' | 'revoke' | 'expire'): PostalActivationLicenseStatus;
+/**
+ * Produces deterministic UTF-8 JSON for detached proofs. Every proof signs the
+ * same credential payload with the complete `proof` property removed, so a
+ * later counter-proof cannot invalidate an earlier one.
+ */
+export declare function canonicalizeOrganizationRegistrationAuthorizationCredential(credential: VerifiableCredentialV2): string;

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

@@ -0,0 +1,117 @@
+import { ContractCredentialTypes, W3cCredentialContexts, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
+/** Lifecycle of the one GW activation licence delivered to the legal postal address. */
+export const PostalActivationLicenseStatuses = Object.freeze({
+    Issued: 'issued',
+    Delivered: 'delivered',
+    Redeemed: 'redeemed',
+    Revoked: 'revoked',
+    Expired: 'expired',
+});
+function required(value, name) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new Error(`Organization registration authorization requires ${name}.`);
+    return normalized;
+}
+/**
+ * Builds the immutable VC that a controller receives out-of-band and attaches
+ * to `Organization/_transaction`. The postal code itself never appears in the
+ * credential; its confirmed, purpose-bound licence record is referenced.
+ */
+export function buildOrganizationRegistrationAuthorizationCredential(input) {
+    const applicationId = required(input.applicationId, 'applicationId');
+    const organizationIdentifier = required(input.organizationIdentifier, 'organizationIdentifier');
+    const controllerEmail = required(input.controllerEmail, 'controllerEmail').toLowerCase();
+    if (input.postalLicense.status !== PostalActivationLicenseStatuses.Delivered) {
+        throw new Error('Organization registration authorization requires a delivered postal activation licence.');
+    }
+    if (input.postalLicense.applicationId !== applicationId
+        || input.postalLicense.organizationIdentifier !== organizationIdentifier
+        || input.postalLicense.controllerEmail.trim().toLowerCase() !== controllerEmail
+        || input.postalLicense.controllerKeyMaterial !== input.controllerKeyMaterial
+        || input.postalLicense.network !== input.targetNetwork) {
+        throw new Error('Postal activation licence does not match the organization registration application.');
+    }
+    return {
+        '@context': [W3cCredentialContexts.V2, 'https://schema.org'],
+        id: required(input.credentialId, 'credentialId'),
+        type: [
+            W3cCredentialTypes.VerifiableCredential,
+            ContractCredentialTypes.OrganizationRegistrationAuthorizationCredential,
+        ],
+        issuer: required(input.issuerDid, 'issuerDid'),
+        credentialSubject: {
+            id: required(input.subjectDid, 'subjectDid'),
+            applicationId,
+            accessPath: input.accessPath,
+            targetNetwork: input.targetNetwork,
+            organization: {
+                legalName: required(input.legalName, 'legalName'),
+                identifier: organizationIdentifier,
+            },
+            controller: {
+                email: controllerEmail,
+                hasCredential: { material: required(input.controllerKeyMaterial, 'controllerKeyMaterial') },
+            },
+            postalActivationLicense: {
+                id: required(input.postalLicense.licenseId, 'postalLicense.licenseId'),
+                status: input.postalLicense.status,
+                postalAddressHash: required(input.postalLicense.postalAddressHash, 'postalLicense.postalAddressHash'),
+                deliveredAt: required(input.postalLicense.deliveredAt, 'postalLicense.deliveredAt'),
+                protectedCode: {
+                    algorithm: input.postalLicense.protectedCode.algorithm,
+                    salt: required(input.postalLicense.protectedCode.salt, 'postalLicense.protectedCode.salt'),
+                    digest: required(input.postalLicense.protectedCode.digest, 'postalLicense.protectedCode.digest'),
+                },
+            },
+        },
+        validFrom: required(input.validFrom, 'validFrom'),
+        validUntil: required(input.validUntil, 'validUntil'),
+        ...(input.proof ? { proof: input.proof } : {}),
+    };
+}
+/**
+ * Applies the only legal state transitions for the purpose-bound postal code.
+ * Confirmation proves delivery but deliberately does not consume the code;
+ * redemption occurs later during `_exchange`.
+ */
+export function transitionPostalActivationLicense(current, action) {
+    if (action === 'mark_delivered' && current === PostalActivationLicenseStatuses.Issued) {
+        return PostalActivationLicenseStatuses.Delivered;
+    }
+    if (action === 'redeem' && current === PostalActivationLicenseStatuses.Delivered) {
+        return PostalActivationLicenseStatuses.Redeemed;
+    }
+    if (action === 'revoke'
+        && (current === PostalActivationLicenseStatuses.Issued
+            || current === PostalActivationLicenseStatuses.Delivered)) {
+        return PostalActivationLicenseStatuses.Revoked;
+    }
+    if (action === 'expire'
+        && (current === PostalActivationLicenseStatuses.Issued
+            || current === PostalActivationLicenseStatuses.Delivered)) {
+        return PostalActivationLicenseStatuses.Expired;
+    }
+    throw new Error(`Invalid postal activation licence transition: ${current} -> ${action}.`);
+}
+function canonicalizeValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeValue);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => key !== 'proof')
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => [key, canonicalizeValue(nested)]));
+}
+/**
+ * Produces deterministic UTF-8 JSON for detached proofs. Every proof signs the
+ * same credential payload with the complete `proof` property removed, so a
+ * later counter-proof cannot invalidate an earlier one.
+ */
+export function canonicalizeOrganizationRegistrationAuthorizationCredential(credential) {
+    if (!credential.type.includes(ContractCredentialTypes.OrganizationRegistrationAuthorizationCredential)) {
+        throw new Error('Credential is not an organization registration authorization.');
+    }
+    return JSON.stringify(canonicalizeValue(credential));
+}

package/dist/utils/vp-token.d.ts

@@ -102,6 +102,13 @@ export declare function getOrganizationCredentialFromVpToken(vpToken: string): V
  * @param vpToken Compact VP token or raw JSON string.
  */
 export declare function getLegalRepresentativeCredentialFromVpToken(vpToken: string): VpCredential | undefined;
+/**
+ * Extracts the organization-controller service credential from a VP token
+ * when present. It never substitutes a legal-representative credential.
+ *
+ * @param vpToken Compact VP token or raw JSON string.
+ */
+export declare function getOrganizationControllerCredentialFromVpToken(vpToken: string): VpCredential | undefined;
 /**
  * Appends an organization activation credential after validating its VC type.
  *
@@ -115,6 +122,13 @@ export declare function addOrganizationCredential(vpPayload: VpTokenPayload, vc:
  * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
  */
 export declare function addLegalRepresentativeCredential(vpPayload: VpTokenPayload, vc: VpCredentialInput): VpTokenPayload;
+/**
+ * Appends an organization-controller service credential after validating its
+ * VC type independently from the legal-representative credential type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
+export declare function addOrganizationControllerCredential(vpPayload: VpTokenPayload, vc: VpCredentialInput): VpTokenPayload;
 export declare function prepareForSignature(header: VpTokenHeader, payload: VpTokenPayload): {
     encodedHeader: string;
     encodedPayload: string;

package/dist/utils/vp-token.js

@@ -1,5 +1,5 @@
 import { buildJwtCompact, prepareJwtBytesForSignature, prepareJwtForSignature } from './jwt.js';
-import { ORGANIZATION_ACTIVATION_VC_TYPES, REPRESENTATIVE_ACTIVATION_VC_TYPES, W3cCredentialContexts, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
+import { ORGANIZATION_ACTIVATION_VC_TYPES, ORGANIZATION_CONTROLLER_ACTIVATION_VC_TYPES, REPRESENTATIVE_ACTIVATION_VC_TYPES, W3cCredentialContexts, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
 function fallbackId() {
     const rand = Math.random().toString(36).slice(2, 10);
     return `id-${Date.now()}-${rand}`;
@@ -189,6 +189,15 @@ export function getOrganizationCredentialFromVpToken(vpToken) {
 export function getLegalRepresentativeCredentialFromVpToken(vpToken) {
     return getVpCredentialByAnyType(vpToken, [...REPRESENTATIVE_ACTIVATION_VC_TYPES]);
 }
+/**
+ * Extracts the organization-controller service credential from a VP token
+ * when present. It never substitutes a legal-representative credential.
+ *
+ * @param vpToken Compact VP token or raw JSON string.
+ */
+export function getOrganizationControllerCredentialFromVpToken(vpToken) {
+    return getVpCredentialByAnyType(vpToken, [...ORGANIZATION_CONTROLLER_ACTIVATION_VC_TYPES]);
+}
 function vcHasAnyType(vcPayload, acceptedTypes) {
     if (!vcPayload)
         return false;
@@ -222,6 +231,15 @@ export function addOrganizationCredential(vpPayload, vc) {
 export function addLegalRepresentativeCredential(vpPayload, vc) {
     return addTypedVC(vpPayload, vc, [...REPRESENTATIVE_ACTIVATION_VC_TYPES], 'LegalRepresentative');
 }
+/**
+ * Appends an organization-controller service credential after validating its
+ * VC type independently from the legal-representative credential type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
+export function addOrganizationControllerCredential(vpPayload, vc) {
+    return addTypedVC(vpPayload, vc, [...ORGANIZATION_CONTROLLER_ACTIVATION_VC_TYPES], 'OrganizationController');
+}
 export function prepareForSignature(header, payload) {
     return prepareJwtForSignature(header, payload);
 }

package/package.json

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