gdc-common-utils-ts 2.5.1 → 2.5.3

package/README.md

@@ -450,9 +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(...)`, `getOrganizationControllerCredentialFromVpToken(...)`](src/utils/vp-token.ts)
+- [`getOrganizationCredentialFromVpToken(...)`, `getLegalRepresentativeCredentialFromVpToken(...)`, `getServiceControllerCredentialFromVpToken(...)`](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)
+- [`readServiceControllerCredentialsFromResponseBody(...)`](src/utils/legal-organization-verification-result.ts)
+- [`extractServiceControllerRoleCodes(...)`, `extractServiceControllerOccupationCodes(...)`](src/utils/activation-policy.ts) read controller authority from `owner.additionalType` and professional occupation from `owner.hasOccupation.occupationalCategory`.
   - 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.

package/dist/constants/schemaorg.d.ts

@@ -155,6 +155,8 @@ export declare enum ClaimsOrderSchemaorg {
  *   conventions and international contexts.
  */
 export declare enum ClaimsPersonSchemaorg {
+    /** Schema.org additional type; service-controller VCs use bare `RESPRSN`. */
+    additionalType = "org.schema.Person.additionalType",
     /** Second surname or mother's maiden name */
     additionalName = "org.schema.Person.additionalName",
     /** Short friendly name */
@@ -165,6 +167,8 @@ export declare enum ClaimsPersonSchemaorg {
     gender = "org.schema.Person.gender",
     givenName = "org.schema.Person.givenName",
     hasOccupation = "org.schema.Person.hasOccupation",
+    /** ISCO taxonomy token carried by `Occupation.occupationalCategory`. */
+    hasOccupationalCategory = "org.schema.Person.hasOccupation.occupationalCategory",
     /**
      * Canonical nested role value used in ICA/VC credential subjects and
      * supported by activation/normalization helpers.

package/dist/constants/schemaorg.js

@@ -163,6 +163,8 @@ export var ClaimsOrderSchemaorg;
  */
 export var ClaimsPersonSchemaorg;
 (function (ClaimsPersonSchemaorg) {
+    /** Schema.org additional type; service-controller VCs use bare `RESPRSN`. */
+    ClaimsPersonSchemaorg["additionalType"] = "org.schema.Person.additionalType";
     /** Second surname or mother's maiden name */
     ClaimsPersonSchemaorg["additionalName"] = "org.schema.Person.additionalName";
     /** Short friendly name */
@@ -173,6 +175,8 @@ export var ClaimsPersonSchemaorg;
     ClaimsPersonSchemaorg["gender"] = "org.schema.Person.gender";
     ClaimsPersonSchemaorg["givenName"] = "org.schema.Person.givenName";
     ClaimsPersonSchemaorg["hasOccupation"] = "org.schema.Person.hasOccupation";
+    /** ISCO taxonomy token carried by `Occupation.occupationalCategory`. */
+    ClaimsPersonSchemaorg["hasOccupationalCategory"] = "org.schema.Person.hasOccupation.occupationalCategory";
     /**
      * Canonical nested role value used in ICA/VC credential subjects and
      * supported by activation/normalization helpers.

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

@@ -28,6 +28,8 @@ export declare const ActivationCredentialTypes: Readonly<{
     OrganizationCredential: "OrganizationCredential";
     LegalOrganizationCredential: "LegalOrganizationCredential";
     LegalRepresentativeCredential: "LegalRepresentativeCredential";
+    ServiceControllerCredential: "ServiceControllerCredential";
+    /** @deprecated Read-only compatibility with pre-2.6 controller VCs. */
     OrganizationControllerCredential: "OrganizationControllerCredential";
     PersonCredential: "PersonCredential";
 }>;
@@ -69,4 +71,6 @@ export declare const REPRESENTATIVE_ACTIVATION_VC_TYPES: readonly ("LegalReprese
  * 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"[];
+export declare const SERVICE_CONTROLLER_ACTIVATION_VC_TYPES: readonly ("ServiceControllerCredential" | "OrganizationControllerCredential")[];
+/** @deprecated Use `SERVICE_CONTROLLER_ACTIVATION_VC_TYPES`. */
+export declare const ORGANIZATION_CONTROLLER_ACTIVATION_VC_TYPES: readonly ("ServiceControllerCredential" | "OrganizationControllerCredential")[];

package/dist/constants/verifiable-credentials.js

@@ -30,6 +30,8 @@ export const ActivationCredentialTypes = Object.freeze({
     OrganizationCredential: 'OrganizationCredential',
     LegalOrganizationCredential: 'LegalOrganizationCredential',
     LegalRepresentativeCredential: 'LegalRepresentativeCredential',
+    ServiceControllerCredential: 'ServiceControllerCredential',
+    /** @deprecated Read-only compatibility with pre-2.6 controller VCs. */
     OrganizationControllerCredential: 'OrganizationControllerCredential',
     PersonCredential: 'PersonCredential',
 });
@@ -77,6 +79,9 @@ export const REPRESENTATIVE_ACTIVATION_VC_TYPES = Object.freeze([
  * 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([
+export const SERVICE_CONTROLLER_ACTIVATION_VC_TYPES = Object.freeze([
+    ActivationCredentialTypes.ServiceControllerCredential,
     ActivationCredentialTypes.OrganizationControllerCredential,
 ]);
+/** @deprecated Use `SERVICE_CONTROLLER_ACTIVATION_VC_TYPES`. */
+export const ORGANIZATION_CONTROLLER_ACTIVATION_VC_TYPES = SERVICE_CONTROLLER_ACTIVATION_VC_TYPES;

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

@@ -5,9 +5,9 @@
  * - controller-signing/audience ids and VC subtype names must be imported from
  *   this module instead of re-hardcoded
  *   inline
- * - the representative `hasCredential.material` shape below reflects the
- *   current `activation-policy` helper contract; if ICA finalizes a different
- *   VC shape, update this module first and then the dependent helpers/tests
+ * - the representative VC carries the legal occupation, while the separate
+ *   service-controller VC carries `RESPRSN`, the technical ISCO occupation and the
+ *   controller key binding
  *
  * Modeling note:
  * - this onboarding example intentionally anchors the business subject on the
@@ -24,6 +24,8 @@ 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_LEGAL_REPRESENTATIVE_ISCO_CODE: "1120";
+export declare const EXAMPLE_TECHNICAL_CONTROLLER_ISCO_CODE: "1330";
 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";
@@ -55,15 +57,37 @@ export declare const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL: Rea
             taxID: "ESB00112233";
         };
         hasOccupation: {
-            identifier: "RESPRSN";
-        };
-        hasCredential: {
-            material: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+            '@type': string;
+            occupationalCategory: string;
         };
         identifier: "IDCES-99999999R";
         sameAs: "urn:multibase:zControllerHash";
     };
 }>;
+export declare const EXAMPLE_ORG_ACTIVATION_CONTROLLER_CREDENTIAL: Readonly<{
+    '@context': string[];
+    type: ("VerifiableCredential" | "ServiceControllerCredential")[];
+    credentialSubject: {
+        id: "ESB00112233";
+        '@type': string;
+        serviceType: string;
+        provider: {
+            taxID: "ESB00112233";
+        };
+        owner: {
+            '@type': string;
+            additionalType: "RESPRSN";
+            sameAs: "urn:multibase:zControllerHash";
+            hasOccupation: {
+                '@type': string;
+                occupationalCategory: string;
+            };
+            hasCredential: {
+                material: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+            };
+        };
+    };
+}>;
 export declare const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD: Readonly<{
     iss: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
     sub: "ESB00112233";

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

@@ -11,9 +11,9 @@ import { DataspaceSectors } from '../constants/sectors.js';
  * - controller-signing/audience ids and VC subtype names must be imported from
  *   this module instead of re-hardcoded
  *   inline
- * - the representative `hasCredential.material` shape below reflects the
- *   current `activation-policy` helper contract; if ICA finalizes a different
- *   VC shape, update this module first and then the dependent helpers/tests
+ * - the representative VC carries the legal occupation, while the separate
+ *   service-controller VC carries `RESPRSN`, the technical ISCO occupation and the
+ *   controller key binding
  *
  * Modeling note:
  * - this onboarding example intentionally anchors the business subject on the
@@ -30,6 +30,8 @@ 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_LEGAL_REPRESENTATIVE_ISCO_CODE = '1120';
+export const EXAMPLE_TECHNICAL_CONTROLLER_ISCO_CODE = '1330';
 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}`;
@@ -67,15 +69,36 @@ export const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL = Object.fre
             taxID: EXAMPLE_ORGANIZATION_TAX_ID,
         },
         hasOccupation: {
-            identifier: EXAMPLE_REPRESENTATIVE_ROLE_CODE,
-        },
-        hasCredential: {
-            material: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
+            '@type': 'Occupation',
+            occupationalCategory: `ISCO-08|${EXAMPLE_LEGAL_REPRESENTATIVE_ISCO_CODE}`,
         },
         identifier: EXAMPLE_REPRESENTATIVE_IDENTIFIER,
         sameAs: EXAMPLE_REPRESENTATIVE_SAME_AS,
     },
 });
+export const EXAMPLE_ORG_ACTIVATION_CONTROLLER_CREDENTIAL = Object.freeze({
+    '@context': [W3cCredentialContexts.V2, 'https://schema.org'],
+    type: [
+        W3cCredentialTypes.VerifiableCredential,
+        ActivationCredentialTypes.ServiceControllerCredential,
+    ],
+    credentialSubject: {
+        id: EXAMPLE_ORGANIZATION_ID,
+        '@type': 'Service',
+        serviceType: 'OrganizationControllerService',
+        provider: { taxID: EXAMPLE_ORGANIZATION_TAX_ID },
+        owner: {
+            '@type': 'Person',
+            additionalType: EXAMPLE_REPRESENTATIVE_ROLE_CODE,
+            sameAs: EXAMPLE_REPRESENTATIVE_SAME_AS,
+            hasOccupation: {
+                '@type': 'Occupation',
+                occupationalCategory: `ISCO-08|${EXAMPLE_TECHNICAL_CONTROLLER_ISCO_CODE}`,
+            },
+            hasCredential: { material: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID },
+        },
+    },
+});
 export const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD = Object.freeze({
     iss: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
     sub: EXAMPLE_ORGANIZATION_TAX_ID,
@@ -87,6 +110,7 @@ export const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD = Object.freeze({
         verifiableCredential: [
             JSON.stringify(EXAMPLE_ORG_ACTIVATION_ORGANIZATION_CREDENTIAL),
             JSON.stringify(EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL),
+            JSON.stringify(EXAMPLE_ORG_ACTIVATION_CONTROLLER_CREDENTIAL),
         ],
     },
 });

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

@@ -40,11 +40,10 @@ export interface IcaVerifyResponseExampleOutcome {
  * Contract notes:
  * - `body.data[0]` carries the organization credential plus optional generated
  *   organization signing keypair
- * - `body.data[1]` carries the legal representative credential plus the
- *   controller binding public key
- * - `credentialSubject.sameAs` expresses public identity continuity
- * - `credentialSubject.hasCredential.material` expresses controller
- *   signing/binding key continuity as an RFC 9278 JWK-thumbprint URN
+ * - `body.data[1]` carries the legal representative credential and its ISCO
+ *   occupation; legal representation alone does not grant tenant control
+ * - `body.data[2]` carries the independently issued organization-controller
+ *   credential, including `RESPRSN`, controller ISCO occupation and JWK binding
  */
 export interface IcaVerifyTermsResponseExample {
     jti: string;
@@ -74,14 +73,19 @@ export declare const EXAMPLE_VERIFY_RESPONSE_PROOF_DATE: "2026-03-12T21:12:57.53
 export declare const EXAMPLE_VERIFY_RESPONSE_VERSION_ID: "zPdfVersionHash001";
 export declare const EXAMPLE_VERIFY_RESPONSE_ORG_VC_ID: "urn:uuid:org-vc-001";
 export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_VC_ID: "urn:uuid:person-vc-001";
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_VC_ID: "urn:uuid:controller-vc-001";
 export declare const EXAMPLE_VERIFY_RESPONSE_ORG_ENTRY_TYPE: "Organization-verification-v1.0";
 export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_ENTRY_TYPE: "LegalRepresentative-verification-v1.0";
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ENTRY_TYPE: "ServiceController-verification-v1.0";
 export declare const EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT_ID: "vc-jwt-1";
 export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT_ID: "vc-jwt-2";
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ATTACHMENT_ID: "vc-jwt-3";
 export declare const EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT_FILENAME: "Organization-verification-v1.0-1.jwt";
 export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT_FILENAME: "LegalRepresentative-verification-v1.0-2.jwt";
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ATTACHMENT_FILENAME: "ServiceController-verification-v1.0-3.jwt";
 export declare const EXAMPLE_VERIFY_RESPONSE_ORG_JWT: "<vc-jwt-organization>";
 export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_JWT: "<vc-jwt-legal-representative>";
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_JWT: "<vc-jwt-organization-controller>";
 export declare const EXAMPLE_VERIFY_RESPONSE_MEDIA_TYPE: "application/vc+jwt";
 export declare const EXAMPLE_VERIFY_RESPONSE_ATTACHMENT_FORMAT: "vc+jwt";
 export declare const EXAMPLE_VERIFY_RESPONSE_STATUS_OK: "200";
@@ -98,19 +102,24 @@ export declare const EXAMPLE_VERIFY_RESPONSE_ORG_ADDITIONAL_TYPE: "sector=onehea
 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";
+/** @deprecated Display-only legacy constant; no longer emitted in signed VCs. */
 export declare const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_NAME: "LegalRepresentative";
-export declare const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_IDENTIFIER: "RESPRSN";
+export declare const EXAMPLE_VERIFY_RESPONSE_REPRESENTATIVE_ISCO: "1120";
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ISCO: "1330";
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ROLE: "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";
 export declare const EXAMPLE_VERIFY_RESPONSE_ORG_PROOF_JWS: "<detached-jws-organization-truncated>";
 export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_PROOF_JWS: "<detached-jws-person-truncated>";
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_PROOF_JWS: "<detached-jws-controller-truncated>";
 /**
  * Shared success outcome reused at bundle level and item level.
  */
 export declare const EXAMPLE_VERIFY_RESPONSE_SUCCESS_OUTCOME: IcaVerifyResponseExampleOutcome;
 export declare const EXAMPLE_VERIFY_RESPONSE_ORG_ITEM_OUTCOME: IcaVerifyResponseExampleOutcome;
 export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_ITEM_OUTCOME: IcaVerifyResponseExampleOutcome;
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ITEM_OUTCOME: IcaVerifyResponseExampleOutcome;
 export declare const EXAMPLE_VERIFY_RESPONSE_ORG_PUBLIC_KEY_JWK: Readonly<{
     kty: "EC";
     crv: "P-384";
@@ -196,8 +205,7 @@ export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL: Readonly<{
         };
         hasOccupation: {
             '@type': "Occupation";
-            name: "LegalRepresentative";
-            identifier: "RESPRSN";
+            occupationalCategory: string;
         };
         memberOf: {
             '@type': "Organization";
@@ -216,8 +224,49 @@ export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL: Readonly<{
         jws: "<detached-jws-person-truncated>";
     };
 }>;
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_CREDENTIAL: Readonly<{
+    id: "urn:uuid:controller-vc-001";
+    '@context': ("https://www.w3.org/ns/credentials/v2" | "https://schema.org")[];
+    type: string[];
+    issuer: "did:web:ica.example.org";
+    validFrom: "2026-03-12T21:12:26.646Z";
+    meta: {
+        versionId: "zPdfVersionHash001";
+    };
+    credentialSubject: {
+        id: "did:web:globaldatacare.es:onehealth:organization:taxid:VATES-B00112233";
+        '@type': string;
+        serviceType: string;
+        provider: {
+            '@type': "Organization";
+            legalName: "ACME Health Provider";
+            taxID: "VATES-B00112233";
+        };
+        owner: {
+            '@type': "Person";
+            additionalType: "RESPRSN";
+            sameAs: "urn:multibase:zControllerHash";
+            hasOccupation: {
+                '@type': "Occupation";
+                occupationalCategory: string;
+            };
+            hasCredential: {
+                material: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+            };
+        };
+    };
+    evidence: never[];
+    proof: {
+        type: "JsonWebSignature2020";
+        created: "2026-03-12T21:12:57.534Z";
+        proofPurpose: "assertionMethod";
+        verificationMethod: "did:web:localhost%3A3310#verification-key-001";
+        jws: "<detached-jws-controller-truncated>";
+    };
+}>;
 export declare const EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT: IcaVerifyResponseExampleAttachment;
 export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT: IcaVerifyResponseExampleAttachment;
+export declare const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ATTACHMENT: IcaVerifyResponseExampleAttachment;
 /**
  * Canonical `_verify-response` success example shared across ICA repos.
  */

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

@@ -19,14 +19,19 @@ export const EXAMPLE_VERIFY_RESPONSE_PROOF_DATE = '2026-03-12T21:12:57.534Z';
 export const EXAMPLE_VERIFY_RESPONSE_VERSION_ID = 'zPdfVersionHash001';
 export const EXAMPLE_VERIFY_RESPONSE_ORG_VC_ID = 'urn:uuid:org-vc-001';
 export const EXAMPLE_VERIFY_RESPONSE_PERSON_VC_ID = 'urn:uuid:person-vc-001';
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_VC_ID = 'urn:uuid:controller-vc-001';
 export const EXAMPLE_VERIFY_RESPONSE_ORG_ENTRY_TYPE = 'Organization-verification-v1.0';
 export const EXAMPLE_VERIFY_RESPONSE_PERSON_ENTRY_TYPE = 'LegalRepresentative-verification-v1.0';
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ENTRY_TYPE = 'ServiceController-verification-v1.0';
 export const EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT_ID = 'vc-jwt-1';
 export const EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT_ID = 'vc-jwt-2';
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ATTACHMENT_ID = 'vc-jwt-3';
 export const EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT_FILENAME = 'Organization-verification-v1.0-1.jwt';
 export const EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT_FILENAME = 'LegalRepresentative-verification-v1.0-2.jwt';
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ATTACHMENT_FILENAME = 'ServiceController-verification-v1.0-3.jwt';
 export const EXAMPLE_VERIFY_RESPONSE_ORG_JWT = '<vc-jwt-organization>';
 export const EXAMPLE_VERIFY_RESPONSE_PERSON_JWT = '<vc-jwt-legal-representative>';
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_JWT = '<vc-jwt-organization-controller>';
 export const EXAMPLE_VERIFY_RESPONSE_MEDIA_TYPE = 'application/vc+jwt';
 export const EXAMPLE_VERIFY_RESPONSE_ATTACHMENT_FORMAT = 'vc+jwt';
 export const EXAMPLE_VERIFY_RESPONSE_STATUS_OK = '200';
@@ -43,13 +48,17 @@ export const EXAMPLE_VERIFY_RESPONSE_ORG_ADDITIONAL_TYPE = 'sector=onehealth;sec
 export const EXAMPLE_VERIFY_RESPONSE_ADDRESS_TYPE = 'PostalAddress';
 export const EXAMPLE_VERIFY_RESPONSE_ADDRESS_COUNTRY = 'ES';
 export const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_TYPE = 'Occupation';
+/** @deprecated Display-only legacy constant; no longer emitted in signed VCs. */
 export const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_NAME = 'LegalRepresentative';
-export const EXAMPLE_VERIFY_RESPONSE_OCCUPATION_IDENTIFIER = 'RESPRSN';
+export const EXAMPLE_VERIFY_RESPONSE_REPRESENTATIVE_ISCO = '1120';
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ISCO = '1330';
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ROLE = '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';
 export const EXAMPLE_VERIFY_RESPONSE_ORG_PROOF_JWS = '<detached-jws-organization-truncated>';
 export const EXAMPLE_VERIFY_RESPONSE_PERSON_PROOF_JWS = '<detached-jws-person-truncated>';
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_PROOF_JWS = '<detached-jws-controller-truncated>';
 /**
  * Shared success outcome reused at bundle level and item level.
  */
@@ -83,6 +92,14 @@ export const EXAMPLE_VERIFY_RESPONSE_PERSON_ITEM_OUTCOME = {
         },
     ],
 };
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ITEM_OUTCOME = {
+    resourceType: EXAMPLE_VERIFY_RESPONSE_OPERATION_OUTCOME_RESOURCE_TYPE,
+    issue: [{
+            severity: IssueSeverity.Information,
+            code: IssueType.Informational,
+            diagnostics: 'Organization controller credential extracted from verified document and JWK binding.',
+        }],
+};
 export const EXAMPLE_VERIFY_RESPONSE_ORG_PUBLIC_KEY_JWK = Object.freeze({
     kty: 'EC',
     crv: 'P-384',
@@ -167,8 +184,7 @@ export const EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL = Object.freeze({
         },
         hasOccupation: {
             '@type': EXAMPLE_VERIFY_RESPONSE_OCCUPATION_TYPE,
-            name: EXAMPLE_VERIFY_RESPONSE_OCCUPATION_NAME,
-            identifier: EXAMPLE_VERIFY_RESPONSE_OCCUPATION_IDENTIFIER,
+            occupationalCategory: `ISCO-08|${EXAMPLE_VERIFY_RESPONSE_REPRESENTATIVE_ISCO}`,
         },
         memberOf: {
             '@type': EXAMPLE_VERIFY_RESPONSE_ORGANIZATION_TYPE,
@@ -187,6 +203,46 @@ export const EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL = Object.freeze({
         jws: EXAMPLE_VERIFY_RESPONSE_PERSON_PROOF_JWS,
     },
 });
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_CREDENTIAL = Object.freeze({
+    id: EXAMPLE_VERIFY_RESPONSE_CONTROLLER_VC_ID,
+    '@context': [W3cCredentialContexts.V2, EXAMPLE_VERIFY_RESPONSE_SCHEMA_ORG_CONTEXT],
+    type: [
+        W3cCredentialTypes.VerifiableCredential,
+        'ServiceCredential',
+        ActivationCredentialTypes.ServiceControllerCredential,
+    ],
+    issuer: EXAMPLE_DEFAULT_ICA_DID,
+    validFrom: EXAMPLE_VERIFY_RESPONSE_DATE,
+    meta: { versionId: EXAMPLE_VERIFY_RESPONSE_VERSION_ID },
+    credentialSubject: {
+        id: EXAMPLE_VERIFY_RESPONSE_ORG_DID,
+        '@type': 'Service',
+        serviceType: 'OrganizationControllerService',
+        provider: {
+            '@type': EXAMPLE_VERIFY_RESPONSE_ORGANIZATION_TYPE,
+            legalName: EXAMPLE_PROVIDER_LEGAL_NAME,
+            taxID: EXAMPLE_PROVIDER_TAX_ID,
+        },
+        owner: {
+            '@type': EXAMPLE_VERIFY_RESPONSE_PERSON_TYPE,
+            additionalType: EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ROLE,
+            sameAs: EXAMPLE_REPRESENTATIVE_SAME_AS,
+            hasOccupation: {
+                '@type': EXAMPLE_VERIFY_RESPONSE_OCCUPATION_TYPE,
+                occupationalCategory: `ISCO-08|${EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ISCO}`,
+            },
+            hasCredential: { material: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID },
+        },
+    },
+    evidence: [],
+    proof: {
+        type: EXAMPLE_VERIFY_RESPONSE_PROOF_TYPE,
+        created: EXAMPLE_VERIFY_RESPONSE_PROOF_DATE,
+        proofPurpose: EXAMPLE_VERIFY_RESPONSE_PROOF_PURPOSE,
+        verificationMethod: EXAMPLE_VERIFY_RESPONSE_PROOF_VERIFICATION_METHOD,
+        jws: EXAMPLE_VERIFY_RESPONSE_CONTROLLER_PROOF_JWS,
+    },
+});
 export const EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT = Object.freeze({
     id: EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT_ID,
     format: EXAMPLE_VERIFY_RESPONSE_ATTACHMENT_FORMAT,
@@ -211,6 +267,18 @@ export const EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT = Object.freeze({
         },
     },
 });
+export const EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ATTACHMENT = Object.freeze({
+    id: EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ATTACHMENT_ID,
+    format: EXAMPLE_VERIFY_RESPONSE_ATTACHMENT_FORMAT,
+    media_type: EXAMPLE_VERIFY_RESPONSE_MEDIA_TYPE,
+    filename: EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ATTACHMENT_FILENAME,
+    data: {
+        json: {
+            format: EXAMPLE_VERIFY_RESPONSE_ATTACHMENT_FORMAT,
+            jwt: EXAMPLE_VERIFY_RESPONSE_CONTROLLER_JWT,
+        },
+    },
+});
 /**
  * Canonical `_verify-response` success example shared across ICA repos.
  */
@@ -223,11 +291,12 @@ export const EXAMPLE_ICA_VERIFY_TERMS_RESPONSE_SUCCESS = {
     attachments: [
         EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT,
         EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT,
+        EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ATTACHMENT,
     ],
     body: {
         resourceType: EXAMPLE_BUNDLE_RESOURCE_TYPE,
         type: EXAMPLE_VERIFY_RESPONSE_BATCH_RESPONSE_TYPE,
-        total: 2,
+        total: 3,
         issues: EXAMPLE_VERIFY_RESPONSE_SUCCESS_OUTCOME,
         data: [
             {
@@ -250,6 +319,15 @@ export const EXAMPLE_ICA_VERIFY_TERMS_RESPONSE_SUCCESS = {
                 },
                 resource: EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL,
             },
+            {
+                type: EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ENTRY_TYPE,
+                publicKeyJwk: EXAMPLE_VERIFY_RESPONSE_PERSON_PUBLIC_KEY_JWK,
+                response: {
+                    status: EXAMPLE_VERIFY_RESPONSE_STATUS_OK,
+                    outcome: EXAMPLE_VERIFY_RESPONSE_CONTROLLER_ITEM_OUTCOME,
+                },
+                resource: EXAMPLE_VERIFY_RESPONSE_CONTROLLER_CREDENTIAL,
+            },
         ],
     },
 };

package/dist/examples/inter-tenant-access-contract.d.ts

@@ -18,6 +18,7 @@
  *   field in this first inter-tenant fixture
  */
 export declare const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_ID: "urn:uuid:inter-tenant-access-contract-001";
+export declare const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_TYPE: "https://example.org/fhir/CodeSystem/contract-type|data-sharing";
 export declare const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_VALID_FROM: "2026-06-29T00:00:00.000Z";
 export declare const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_VALID_UNTIL: "2027-06-29T00:00:00.000Z";
 export declare const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_PURPOSE: "RESEARCH";
@@ -30,6 +31,7 @@ export declare const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_SMART_SCOPE: "organiza
 export declare const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_CLAIMS: Readonly<{
     readonly "Contract.identifier": "urn:uuid:inter-tenant-access-contract-001";
     readonly "Contract.status": "executed";
+    readonly "Contract.type": "https://example.org/fhir/CodeSystem/contract-type|data-sharing";
     readonly "Contract.issued": "2026-06-29T00:00:00.000Z";
     readonly "Contract.applies-start": "2026-06-29T00:00:00.000Z";
     readonly "Contract.applies-end": "2027-06-29T00:00:00.000Z";

package/dist/examples/inter-tenant-access-contract.js

@@ -27,6 +27,7 @@ import { EXAMPLE_API_ORGANIZATION_DID, EXAMPLE_CONTROLLER_DID, EXAMPLE_HEALTHCAR
  *   field in this first inter-tenant fixture
  */
 export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_ID = 'urn:uuid:inter-tenant-access-contract-001';
+export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_TYPE = 'https://example.org/fhir/CodeSystem/contract-type|data-sharing';
 export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_VALID_FROM = '2026-06-29T00:00:00.000Z';
 export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_VALID_UNTIL = '2027-06-29T00:00:00.000Z';
 export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_PURPOSE = 'RESEARCH';
@@ -39,6 +40,7 @@ export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_SMART_SCOPE = `${EXAMPLE_INTER
 export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_CLAIMS = Object.freeze({
     [ClaimInterTenantAccessContract.identifier]: EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_ID,
     [ClaimInterTenantAccessContract.status]: 'executed',
+    [ClaimInterTenantAccessContract.type]: EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_TYPE,
     [ClaimInterTenantAccessContract.issued]: EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_VALID_FROM,
     [ClaimInterTenantAccessContract.appliesStart]: EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_VALID_FROM,
     [ClaimInterTenantAccessContract.appliesEnd]: EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_VALID_UNTIL,

package/dist/models/inter-tenant-access-contract.d.ts

@@ -16,6 +16,12 @@ export declare enum ClaimInterTenantAccessContract {
     identifier = "Contract.identifier",
     /** FHIR Contract lifecycle status, for example `executed` or `amended`. */
     status = "Contract.status",
+    /**
+     * FHIR `Contract.type` CodeableConcept encoded as `system|code` in the flat
+     * claims transport. The terminology authority is supplied by the adopting
+     * governance domain rather than hardcoded in this product-neutral package.
+     */
+    type = "Contract.type",
     /** When the agreement was formally issued. */
     issued = "Contract.issued",
     /** Agreement validity start date/time. */

package/dist/models/inter-tenant-access-contract.js

@@ -18,6 +18,12 @@ export var ClaimInterTenantAccessContract;
     ClaimInterTenantAccessContract["identifier"] = "Contract.identifier";
     /** FHIR Contract lifecycle status, for example `executed` or `amended`. */
     ClaimInterTenantAccessContract["status"] = "Contract.status";
+    /**
+     * FHIR `Contract.type` CodeableConcept encoded as `system|code` in the flat
+     * claims transport. The terminology authority is supplied by the adopting
+     * governance domain rather than hardcoded in this product-neutral package.
+     */
+    ClaimInterTenantAccessContract["type"] = "Contract.type";
     /** When the agreement was formally issued. */
     ClaimInterTenantAccessContract["issued"] = "Contract.issued";
     /** Agreement validity start date/time. */

package/dist/models/urlPath.d.ts

@@ -5,6 +5,7 @@
 export declare enum Sector {
     TEST = "test",// For mock/demo endpoints and host registry in tests
     SYSTEM = "system",// Reserved for the host's bootstrap operation (TODO: deprecate)
+    ANTIFRAUD = "antifraud",
     HEALTH_CARE = "health-care",
     HEALTH_INSURANCE = "health-insurance",
     EMERGENCY = "emergency",

package/dist/models/urlPath.js

@@ -8,6 +8,7 @@ export var Sector;
 (function (Sector) {
     Sector["TEST"] = "test";
     Sector["SYSTEM"] = "system";
+    Sector["ANTIFRAUD"] = "antifraud";
     Sector["HEALTH_CARE"] = "health-care";
     Sector["HEALTH_INSURANCE"] = "health-insurance";
     Sector["EMERGENCY"] = "emergency";

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

@@ -1,4 +1,4 @@
-export type ActivationRepresentativePolicyErrorCode = 'MISSING_REPRESENTATIVE_SUBJECT_ID' | 'MISSING_REPRESENTATIVE_ROLE_RESPRSN' | 'MISSING_REPRESENTATIVE_CREDENTIAL_BINDING' | 'REPRESENTATIVE_TAXID_MISMATCH';
+export type ActivationRepresentativePolicyErrorCode = 'MISSING_REPRESENTATIVE_SUBJECT_ID' | 'MISSING_REPRESENTATIVE_ROLE_RESPRSN' | 'MISSING_REPRESENTATIVE_CREDENTIAL_BINDING' | 'MISSING_CONTROLLER_ROLE_RESPRSN' | 'MISSING_CONTROLLER_CREDENTIAL_BINDING' | 'CONTROLLER_TAXID_MISMATCH' | 'REPRESENTATIVE_TAXID_MISMATCH';
 export type ActivationServiceAuthorizationPolicyErrorCode = 'MISSING_ORGANIZATION_SERVICE_CATEGORY' | 'MISSING_ORGANIZATION_SERVICE_TYPE' | 'UNAUTHORIZED_ORGANIZATION_SERVICE_CATEGORY' | 'UNAUTHORIZED_ORGANIZATION_SERVICE_TYPE';
 export type ActivationRepresentativePolicyError = {
     code: ActivationRepresentativePolicyErrorCode;
@@ -38,6 +38,20 @@ export declare function extractRepresentativeMemberOfTaxId(representativeCredent
  * @param representativeCredential Candidate representative credential.
  */
 export declare function extractRepresentativeRoleCode(representativeCredential: unknown): string | undefined;
+/**
+ * Reads controller-authorization codes from an ICA-issued controller VC.
+ * Professional ISCO occupations are deliberately excluded.
+ */
+export declare function extractOrganizationControllerRoleCodes(controllerCredential: unknown): string[];
+/** Canonical name for reading controller authority from a service-controller VC. */
+export declare const extractServiceControllerRoleCodes: typeof extractOrganizationControllerRoleCodes;
+/**
+ * Reads professional ISCO occupations from an ICA-issued controller VC as
+ * canonical `ISCO-08|code` tokens.
+ */
+export declare function extractOrganizationControllerOccupationCodes(controllerCredential: unknown): string[];
+/** Canonical name for reading ISCO occupations from a service-controller VC. */
+export declare const extractServiceControllerOccupationCodes: typeof extractOrganizationControllerOccupationCodes;
 /**
  * Checks whether a role code contains the required code, ignoring prefixes such as `SYSTEM|`.
  *
@@ -154,22 +168,30 @@ export declare function buildMemberDidWeb(ownerDidWeb: string, memberId: string,
  */
 export declare function isMemberDidWebUnderOwner(memberDidWeb: string, ownerDidWeb: string): boolean;
 /**
- * Validates the activation representative policy against organization and representative credentials.
+ * Validates controller authorization for organization activation.
  *
- * The representative proof model is intentionally two-dimensional:
- * - `credentialSubject.sameAs` expresses public identity continuity
- * - `credentialSubject.hasCredential.material` expresses signing-key continuity
+ * Canonical three-credential flow:
+ * - `LegalRepresentativeCredential` proves legal representation and carries
+ *   the representative's professional ISCO occupation
+ * - `ServiceControllerCredential` independently carries `RESPRSN` in
+ *   `owner.additionalType` and `owner.hasCredential.material` for the
+ *   controller actor key
  *
- * For GW activation, the key-binding dimension is the hard requirement
- * enforced here. The public-identity dimension may still be used by higher
- * layers for stronger demo/production matching and auditability.
+ * Legacy two-credential compatibility is deliberately narrow. When no
+ * no service-controller credential exists, the representative credential is
+ * accepted as the controller proof only if that old credential itself carries
+ * both `RESPRSN` and `hasCredential` binding material. A modern representative
+ * credential containing only an ISCO occupation such as `ISCO-08|1120` is not
+ * promoted to controller and fails this policy.
  *
  * @param input.organizationCredential Candidate organization credential.
- * @param input.representativeCredential Candidate representative credential.
- * @param input.requiredRoleCode Required representative role, defaults to `RESPRSN`.
+ * @param input.representativeCredential Legal-representative credential.
+ * @param input.controllerCredential Canonical controller-authority credential.
+ * @param input.requiredRoleCode Required controller role, defaults to `RESPRSN`.
  */
 export declare function validateActivationRepresentativePolicy(input: {
     organizationCredential?: unknown;
     representativeCredential?: unknown;
+    controllerCredential?: unknown;
     requiredRoleCode?: string;
 }): ActivationRepresentativePolicyError[];

package/dist/utils/activation-policy.js

@@ -88,6 +88,91 @@ export function extractRepresentativeRoleCode(representativeCredential) {
     }
     return undefined;
 }
+function readOccupationEntries(value) {
+    const values = Array.isArray(value) ? value : value ? [value] : [];
+    return values.map((entry) => {
+        if (typeof entry === 'string')
+            return { identifier: entry };
+        return asObject(entry);
+    }).filter((entry) => Boolean(entry));
+}
+function readCodedIdentifier(entry) {
+    const identifier = entry.identifier;
+    if (typeof identifier === 'string') {
+        const token = identifier.trim();
+        const separator = token.lastIndexOf('|');
+        return separator >= 0
+            ? { system: token.slice(0, separator), value: token.slice(separator + 1) }
+            : { value: token };
+    }
+    const coded = asObject(identifier) || {};
+    return {
+        system: String(coded.additionalType || coded.system || '').trim() || undefined,
+        value: String(coded.value || '').trim() || undefined,
+    };
+}
+/**
+ * Reads controller-authorization codes from an ICA-issued controller VC.
+ * Professional ISCO occupations are deliberately excluded.
+ */
+export function extractOrganizationControllerRoleCodes(controllerCredential) {
+    const subject = extractCredentialSubject(controllerCredential) || {};
+    const owner = asObject(subject.owner) || {};
+    const canonical = (Array.isArray(owner.additionalType) ? owner.additionalType : [owner.additionalType])
+        .map((value) => String(value || '').trim())
+        .filter(Boolean);
+    if (canonical.length)
+        return canonical;
+    return readOccupationEntries(owner.hasOccupation)
+        .filter((entry) => String(entry['@type'] || '').toLowerCase() === 'role'
+        || readCodedIdentifier(entry).system?.toUpperCase() !== 'ISCO-08')
+        .map((entry) => readCodedIdentifier(entry).value)
+        .filter((value) => Boolean(value));
+}
+/** Canonical name for reading controller authority from a service-controller VC. */
+export const extractServiceControllerRoleCodes = extractOrganizationControllerRoleCodes;
+/**
+ * Reads professional ISCO occupations from an ICA-issued controller VC as
+ * canonical `ISCO-08|code` tokens.
+ */
+export function extractOrganizationControllerOccupationCodes(controllerCredential) {
+    const subject = extractCredentialSubject(controllerCredential) || {};
+    const owner = asObject(subject.owner) || {};
+    const occupation = asObject(owner.hasOccupation);
+    const occupationalCategory = occupation?.occupationalCategory;
+    const canonical = (Array.isArray(occupationalCategory) ? occupationalCategory : [occupationalCategory])
+        .map((value) => {
+        if (typeof value === 'string')
+            return value.trim();
+        const category = asObject(value) || {};
+        const codeValue = String(category.codeValue || '').trim();
+        const codeSet = asObject(category.inCodeSet) || {};
+        const system = String(codeSet.name || '').trim();
+        return codeValue ? `${system || 'ISCO-08'}|${codeValue}` : '';
+    })
+        .filter(Boolean);
+    if (canonical.length)
+        return canonical;
+    return readOccupationEntries(owner.hasOccupation)
+        .map(readCodedIdentifier)
+        .filter((identifier) => identifier.system?.toUpperCase() === 'ISCO-08' && identifier.value)
+        .map((identifier) => `ISCO-08|${identifier.value}`);
+}
+/** Canonical name for reading ISCO occupations from a service-controller VC. */
+export const extractServiceControllerOccupationCodes = extractOrganizationControllerOccupationCodes;
+function extractOrganizationControllerBinding(controllerCredential) {
+    const subject = extractCredentialSubject(controllerCredential) || {};
+    const owner = asObject(subject.owner) || {};
+    return extractCredentialBindingValue(owner.hasCredential);
+}
+function extractOrganizationControllerProviderTaxId(controllerCredential) {
+    const subject = extractCredentialSubject(controllerCredential) || {};
+    const provider = asObject(subject.provider) || {};
+    const identifier = asObject(provider.identifier);
+    return normalizeTaxIdentifier(provider.taxID)
+        || normalizeTaxIdentifier(provider.taxId)
+        || normalizeTaxIdentifier(identifier?.value);
+}
 /**
  * Checks whether a role code contains the required code, ignoring prefixes such as `SYSTEM|`.
  *
@@ -307,19 +392,26 @@ export function isMemberDidWebUnderOwner(memberDidWeb, ownerDidWeb) {
     return did.startsWith(`${owner}:member:`);
 }
 /**
- * Validates the activation representative policy against organization and representative credentials.
+ * Validates controller authorization for organization activation.
  *
- * The representative proof model is intentionally two-dimensional:
- * - `credentialSubject.sameAs` expresses public identity continuity
- * - `credentialSubject.hasCredential.material` expresses signing-key continuity
+ * Canonical three-credential flow:
+ * - `LegalRepresentativeCredential` proves legal representation and carries
+ *   the representative's professional ISCO occupation
+ * - `ServiceControllerCredential` independently carries `RESPRSN` in
+ *   `owner.additionalType` and `owner.hasCredential.material` for the
+ *   controller actor key
  *
- * For GW activation, the key-binding dimension is the hard requirement
- * enforced here. The public-identity dimension may still be used by higher
- * layers for stronger demo/production matching and auditability.
+ * Legacy two-credential compatibility is deliberately narrow. When no
+ * no service-controller credential exists, the representative credential is
+ * accepted as the controller proof only if that old credential itself carries
+ * both `RESPRSN` and `hasCredential` binding material. A modern representative
+ * credential containing only an ISCO occupation such as `ISCO-08|1120` is not
+ * promoted to controller and fails this policy.
  *
  * @param input.organizationCredential Candidate organization credential.
- * @param input.representativeCredential Candidate representative credential.
- * @param input.requiredRoleCode Required representative role, defaults to `RESPRSN`.
+ * @param input.representativeCredential Legal-representative credential.
+ * @param input.controllerCredential Canonical controller-authority credential.
+ * @param input.requiredRoleCode Required controller role, defaults to `RESPRSN`.
  */
 export function validateActivationRepresentativePolicy(input) {
     const errors = [];
@@ -332,16 +424,41 @@ export function validateActivationRepresentativePolicy(input) {
             message: 'ICA-issued representative credential is missing credentialSubject.id.',
         });
     }
-    if (!input.representativeCredential)
-        return errors;
     const orgTax = extractOrganizationTaxId(input.organizationCredential);
-    const repTax = extractRepresentativeMemberOfTaxId(input.representativeCredential);
-    if (orgTax && repTax && orgTax !== repTax) {
-        errors.push({
-            code: 'REPRESENTATIVE_TAXID_MISMATCH',
-            message: 'ICA-issued representative credential memberOf.taxID must match organization credential taxID.',
-        });
+    if (input.representativeCredential) {
+        const repTax = extractRepresentativeMemberOfTaxId(input.representativeCredential);
+        if (orgTax && repTax && orgTax !== repTax) {
+            errors.push({
+                code: 'REPRESENTATIVE_TAXID_MISMATCH',
+                message: 'ICA-issued representative credential memberOf.taxID must match organization credential taxID.',
+            });
+        }
+    }
+    if (input.controllerCredential) {
+        const controllerTax = extractOrganizationControllerProviderTaxId(input.controllerCredential);
+        if (orgTax && controllerTax && orgTax !== controllerTax) {
+            errors.push({
+                code: 'CONTROLLER_TAXID_MISMATCH',
+                message: 'ICA-issued controller credential provider.taxID must match organization credential taxID.',
+            });
+        }
+        const controllerRoles = extractOrganizationControllerRoleCodes(input.controllerCredential);
+        if (!controllerRoles.some((role) => hasActivationRepresentativeRole(role, input.requiredRoleCode || 'RESPRSN'))) {
+            errors.push({
+                code: 'MISSING_CONTROLLER_ROLE_RESPRSN',
+                message: 'ICA-issued service controller credential must include RESPRSN in credentialSubject.owner.additionalType.',
+            });
+        }
+        if (!extractOrganizationControllerBinding(input.controllerCredential)) {
+            errors.push({
+                code: 'MISSING_CONTROLLER_CREDENTIAL_BINDING',
+                message: 'ICA-issued service controller credential is missing credentialSubject.owner.hasCredential binding data.',
+            });
+        }
+        return errors;
     }
+    if (!input.representativeCredential)
+        return errors;
     const roleCode = extractRepresentativeRoleCode(input.representativeCredential);
     if (!hasActivationRepresentativeRole(roleCode, input.requiredRoleCode || 'RESPRSN')) {
         errors.push({

package/dist/utils/inter-tenant-access-contract.js

@@ -15,6 +15,20 @@ function splitCsv(value) {
         .map((item) => item.trim())
         .filter(Boolean)));
 }
+function buildContractTypeCodeableConcept(value) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        return undefined;
+    const separator = normalized.indexOf('|');
+    if (separator < 1 || separator === normalized.length - 1) {
+        return { text: normalized };
+    }
+    const system = normalized.slice(0, separator).trim();
+    const code = normalized.slice(separator + 1).trim();
+    if (!system || !code)
+        return { text: normalized };
+    return { coding: [{ system, code }] };
+}
 function readClaimWithAliases(claims, canonicalKey, aliases = []) {
     const direct = String(claims[canonicalKey] || '').trim();
     if (direct)
@@ -124,6 +138,7 @@ function normalizeNow(input) {
 export function buildInterTenantAccessContractResource(claims) {
     const identifier = readClaimWithAliases(claims, ClaimInterTenantAccessContract.identifier) || '';
     const status = readClaimWithAliases(claims, ClaimInterTenantAccessContract.status) || 'executed';
+    const type = buildContractTypeCodeableConcept(readClaimWithAliases(claims, ClaimInterTenantAccessContract.type));
     const issued = readClaimWithAliases(claims, ClaimInterTenantAccessContract.issued) || '';
     const appliesStart = readClaimWithAliases(claims, ClaimInterTenantAccessContract.appliesStart, ['Contract.applies.start']) || '';
     const appliesEnd = readClaimWithAliases(claims, ClaimInterTenantAccessContract.appliesEnd, ['Contract.applies.end']) || '';
@@ -139,6 +154,7 @@ export function buildInterTenantAccessContractResource(claims) {
         id: identifier || undefined,
         identifier: identifier ? [{ value: identifier }] : undefined,
         status,
+        type,
         issued: issued || undefined,
         instantiatesUri: instantiatesUri || undefined,
         applies: {

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

@@ -64,19 +64,27 @@ export declare function readLegalRepresentativeBindingFromResponseBody(responseB
  * and legal-representative credential pair.
  */
 export declare function readOrganizationControllerCredentialsFromResponseBody(responseBody: unknown): LegalOrganizationVerificationCredential[];
+/** Canonical name for reading ICA-issued service-controller credentials. */
+export declare const readServiceControllerCredentialsFromResponseBody: typeof readOrganizationControllerCredentialsFromResponseBody;
 /**
  * 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;
+/** Canonical name for selecting one ICA-issued service-controller credential. */
+export declare const readServiceControllerCredentialFromResponseBody: typeof readOrganizationControllerCredentialFromResponseBody;
 /**
  * Reads `credentialSubject.owner.sameAs` from the first
  * organization-controller service credential when present.
  */
 export declare function readOrganizationControllerSameAsFromResponseBody(responseBody: unknown): string | undefined;
+/** Canonical name for reading a service controller's stable actor identifier. */
+export declare const readServiceControllerSameAsFromResponseBody: typeof readOrganizationControllerSameAsFromResponseBody;
 /**
  * Reads `credentialSubject.owner.hasCredential.material` from the first
  * organization-controller service credential when present.
  */
 export declare function readOrganizationControllerBindingFromResponseBody(responseBody: unknown): string | undefined;
+/** Canonical name for reading a service controller's actor-key binding. */
+export declare const readServiceControllerBindingFromResponseBody: typeof readOrganizationControllerBindingFromResponseBody;

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

@@ -152,10 +152,13 @@ export function readLegalRepresentativeBindingFromResponseBody(responseBody) {
  */
 export function readOrganizationControllerCredentialsFromResponseBody(responseBody) {
     return getLegalOrganizationVerificationEntriesFromResponseBody(responseBody)
-        .filter((entry) => hasCredentialType(entry, 'OrganizationControllerCredential'))
+        .filter((entry) => hasCredentialType(entry, 'ServiceControllerCredential')
+        || hasCredentialType(entry, 'OrganizationControllerCredential'))
         .map((entry) => asObject(asObject(entry)?.resource) || asObject(entry))
         .filter((entry) => Boolean(entry));
 }
+/** Canonical name for reading ICA-issued service-controller credentials. */
+export const readServiceControllerCredentialsFromResponseBody = readOrganizationControllerCredentialsFromResponseBody;
 /**
  * Returns one organization-controller service credential in an ICA or
  * projected GW verification response. Pass a stable actor `sameAs` to select
@@ -168,6 +171,8 @@ export function readOrganizationControllerCredentialFromResponseBody(responseBod
         ? credentials.find((credential) => extractOrganizationControllerSameAs(credential) === expectedSameAs)
         : credentials[0];
 }
+/** Canonical name for selecting one ICA-issued service-controller credential. */
+export const readServiceControllerCredentialFromResponseBody = readOrganizationControllerCredentialFromResponseBody;
 /**
  * Reads `credentialSubject.owner.sameAs` from the first
  * organization-controller service credential when present.
@@ -175,6 +180,8 @@ export function readOrganizationControllerCredentialFromResponseBody(responseBod
 export function readOrganizationControllerSameAsFromResponseBody(responseBody) {
     return extractOrganizationControllerSameAs(readOrganizationControllerCredentialFromResponseBody(responseBody));
 }
+/** Canonical name for reading a service controller's stable actor identifier. */
+export const readServiceControllerSameAsFromResponseBody = readOrganizationControllerSameAsFromResponseBody;
 /**
  * Reads `credentialSubject.owner.hasCredential.material` from the first
  * organization-controller service credential when present.
@@ -182,3 +189,5 @@ export function readOrganizationControllerSameAsFromResponseBody(responseBody) {
 export function readOrganizationControllerBindingFromResponseBody(responseBody) {
     return extractOrganizationControllerBinding(readOrganizationControllerCredentialFromResponseBody(responseBody));
 }
+/** Canonical name for reading a service controller's actor-key binding. */
+export const readServiceControllerBindingFromResponseBody = readOrganizationControllerBindingFromResponseBody;

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

@@ -84,11 +84,16 @@ export type LegalOrganizationVerificationTransactionInput = Readonly<{
 }>;
 export type LegalOrganizationVerificationTransactionEntry = Readonly<{
     type?: string;
+    /** @deprecated Read-only compatibility with payloads emitted before 2.5.x. */
     meta?: {
         claims?: ClaimsRecord;
         [key: string]: unknown;
     };
     resource?: {
+        meta?: {
+            claims?: ClaimsRecord;
+            [key: string]: unknown;
+        };
         controller?: LegalOrganizationVerificationTransactionController;
         organization?: LegalOrganizationVerificationTransactionOrganization;
         /** @deprecated Legacy demo/OTP compatibility input. */
@@ -106,7 +111,7 @@ export type LegalOrganizationVerificationTransactionEntry = Readonly<{
  * verification transactions.
  *
  * Contract notes:
- * - business claims remain in `meta.claims`
+ * - business claims live in `resource.meta.claims`
  * - controller binding material remains in `resource.controller.*`
  * - organization signing material remains in `resource.organization.*`
  * - PDF evidence or URL attachments stay at the DIDComm-message level

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

@@ -31,7 +31,7 @@ function asRecord(value) {
  * verification transactions.
  *
  * Contract notes:
- * - business claims remain in `meta.claims`
+ * - business claims live in `resource.meta.claims`
  * - controller binding material remains in `resource.controller.*`
  * - organization signing material remains in `resource.organization.*`
  * - PDF evidence or URL attachments stay at the DIDComm-message level
@@ -49,10 +49,10 @@ export function buildLegalOrganizationVerificationTransactionBundle(input) {
         total: 1,
         data: [{
                 type: LegalOrganizationVerificationTransactionEntryTypes.Request,
-                meta: {
-                    claims: input.claims,
-                },
                 resource: {
+                    meta: {
+                        claims: input.claims,
+                    },
                     controller: input.controller,
                     ...(input.organization ? { organization: input.organization } : {}),
                     ...(input.legalRepresentativePayload

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

@@ -10,8 +10,9 @@ export declare const PostalActivationLicenseStatuses: Readonly<{
 export type PostalActivationLicenseStatus = typeof PostalActivationLicenseStatuses[keyof typeof PostalActivationLicenseStatuses];
 /**
  * Public binding recorded for the activation licence. The activation code is
- * deliberately absent: storage implementations retain only its protected
- * value/index and never place the secret inside a VC.
+ * 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;
@@ -20,6 +21,11 @@ export type PostalActivationLicenseBinding = Readonly<{
     controllerEmail: string;
     controllerKeyMaterial: string;
     postalAddressHash: string;
+    protectedCode: Readonly<{
+        algorithm: 'scrypt-v1';
+        salt: string;
+        digest: string;
+    }>;
     hostDid: string;
     network: 'test-network' | 'network';
     status: PostalActivationLicenseStatus;

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

@@ -58,6 +58,11 @@ export function buildOrganizationRegistrationAuthorizationCredential(input) {
                 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'),

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

@@ -103,12 +103,14 @@ export declare function getOrganizationCredentialFromVpToken(vpToken: string): V
  */
 export declare function getLegalRepresentativeCredentialFromVpToken(vpToken: string): VpCredential | undefined;
 /**
- * Extracts the organization-controller service credential from a VP token
+ * Extracts the service-controller 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;
+/** Canonical name for `getOrganizationControllerCredentialFromVpToken`. */
+export declare const getServiceControllerCredentialFromVpToken: typeof getOrganizationControllerCredentialFromVpToken;
 /**
  * Appends an organization activation credential after validating its VC type.
  *
@@ -129,6 +131,8 @@ export declare function addLegalRepresentativeCredential(vpPayload: VpTokenPaylo
  * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
  */
 export declare function addOrganizationControllerCredential(vpPayload: VpTokenPayload, vc: VpCredentialInput): VpTokenPayload;
+/** Canonical name for `addOrganizationControllerCredential`. */
+export declare const addServiceControllerCredential: typeof addOrganizationControllerCredential;
 export declare function prepareForSignature(header: VpTokenHeader, payload: VpTokenPayload): {
     encodedHeader: string;
     encodedPayload: string;

package/dist/utils/vp-token.js

@@ -190,7 +190,7 @@ export function getLegalRepresentativeCredentialFromVpToken(vpToken) {
     return getVpCredentialByAnyType(vpToken, [...REPRESENTATIVE_ACTIVATION_VC_TYPES]);
 }
 /**
- * Extracts the organization-controller service credential from a VP token
+ * Extracts the service-controller credential from a VP token
  * when present. It never substitutes a legal-representative credential.
  *
  * @param vpToken Compact VP token or raw JSON string.
@@ -198,6 +198,8 @@ export function getLegalRepresentativeCredentialFromVpToken(vpToken) {
 export function getOrganizationControllerCredentialFromVpToken(vpToken) {
     return getVpCredentialByAnyType(vpToken, [...ORGANIZATION_CONTROLLER_ACTIVATION_VC_TYPES]);
 }
+/** Canonical name for `getOrganizationControllerCredentialFromVpToken`. */
+export const getServiceControllerCredentialFromVpToken = getOrganizationControllerCredentialFromVpToken;
 function vcHasAnyType(vcPayload, acceptedTypes) {
     if (!vcPayload)
         return false;
@@ -238,8 +240,10 @@ export function addLegalRepresentativeCredential(vpPayload, vc) {
  * 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');
+    return addTypedVC(vpPayload, vc, [...ORGANIZATION_CONTROLLER_ACTIVATION_VC_TYPES], 'ServiceController');
 }
+/** Canonical name for `addOrganizationControllerCredential`. */
+export const addServiceControllerCredential = addOrganizationControllerCredential;
 export function prepareForSignature(header, payload) {
     return prepareJwtForSignature(header, payload);
 }

package/package.json

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