gdc-common-utils-ts 2.0.1 → 2.0.4

package/README.md

@@ -10,6 +10,26 @@ Short rule:
 - do not add ad hoc literals in `101` tests when `gdc-common-utils-ts` can own
   the reusable value instead
 
+## Shared Workspace
+
+Recommended local layout for the shared ICA/GDC repos and fixture PDFs:
+
+```text
+~/GITS/gdc-workspace/
+  dataspace-ica-ts/
+  ica-client-sdk-ts/
+  gdc-common-utils-ts/
+  examples/
+    <example-pdf-1>.pdf
+    <example-pdf-2>.pdf
+```
+
+This is recommended because:
+
+- cross-repo docs and fixture-based tests often refer to sibling repos
+- real PDF examples are expected under `~/GITS/gdc-workspace/examples/`
+- keeping a single shared workspace reduces path drift between repos
+
 Employee shared examples live in `src/examples/employee.ts`.
 Employee pure helper functions live in `src/utils/employee.ts`.
 
@@ -61,6 +81,31 @@ They are not interchangeable:
 Production-grade flows should prefer ICA-issued representative VCs that carry
 both dimensions.
 
+## Legal Organization Verification Transaction
+
+The first host-side legal-organization onboarding step now has one canonical
+shared payload builder in this package:
+
+- `buildLegalOrganizationVerificationTransactionBundle(...)`
+- `EXAMPLE_LEGAL_ORGANIZATION_VERIFICATION_TRANSACTION_BUNDLE`
+
+This builder owns the business payload only:
+
+- signed PDF evidence attachment references
+- `controller.publicKeyJwk` as the controller business binding key
+- optional `organization.publicKeyJwk`
+- legal representative payload
+- `meta.claims` business claims
+
+It intentionally does not own:
+
+- `fetch`
+- polling
+- JOSE transport execution
+- BFF/frontend runtime crypto
+
+Those runtime concerns belong in `gdc-sdk-node-ts`, `gdc-sdk-front-ts`, or GW.
+
 Step by step:
 
 1. ICA verifies the signed PDF and emits the representative VC.

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

@@ -0,0 +1,230 @@
+import { EXAMPLE_BUNDLE_RESOURCE_TYPE } from './shared';
+/**
+ * Minimal DIDComm bundle attachment example shape reused by ICA response fixtures.
+ */
+export interface IcaVerifyResponseExampleAttachment {
+    id: string;
+    format: string;
+    media_type: string;
+    filename: string;
+    data: {
+        json: {
+            format: string;
+            jwt: string;
+        };
+    };
+}
+/**
+ * Minimal OperationOutcome issue example shape reused by ICA response fixtures.
+ */
+export interface IcaVerifyResponseExampleIssue {
+    severity: 'information' | 'warning' | 'error' | 'fatal';
+    code: string;
+    diagnostics: string;
+}
+/**
+ * Minimal OperationOutcome example shape reused by ICA response fixtures.
+ */
+export interface IcaVerifyResponseExampleOutcome {
+    resourceType: typeof EXAMPLE_VERIFY_RESPONSE_OPERATION_OUTCOME_RESOURCE_TYPE;
+    issue: IcaVerifyResponseExampleIssue[];
+}
+/**
+ * Canonical example of the `_verify-response` DIDComm payload emitted by ICA.
+ *
+ * This example is intentionally transport-neutral and reusable by:
+ * - Swagger/OpenAPI examples
+ * - SDK unit tests
+ * - portal/BFF documentation
+ *
+ * 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
+ */
+export interface IcaVerifyTermsResponseExample {
+    jti: string;
+    iss: string;
+    aud: string;
+    thid: string;
+    type: string;
+    attachments: IcaVerifyResponseExampleAttachment[];
+    body: {
+        resourceType: typeof EXAMPLE_BUNDLE_RESOURCE_TYPE;
+        type: typeof EXAMPLE_VERIFY_RESPONSE_BATCH_RESPONSE_TYPE;
+        total: number;
+        issues: IcaVerifyResponseExampleOutcome;
+        data: Array<Record<string, unknown>>;
+    };
+}
+export declare const EXAMPLE_VERIFY_RESPONSE_OPERATION_OUTCOME_RESOURCE_TYPE: "OperationOutcome";
+export declare const EXAMPLE_VERIFY_RESPONSE_BATCH_RESPONSE_TYPE: "batch-response";
+export declare const EXAMPLE_VERIFY_RESPONSE_SCHEMA_ORG_CONTEXT: "https://schema.org";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_TYPE: "Person";
+export declare const EXAMPLE_VERIFY_RESPONSE_ORGANIZATION_TYPE: "Organization";
+export declare const EXAMPLE_VERIFY_RESPONSE_JTI: "urn:uuid:verify-resp-001";
+export declare const EXAMPLE_VERIFY_RESPONSE_THID: "verify-terms-001";
+export declare const EXAMPLE_VERIFY_RESPONSE_BUNDLE_TYPE: "application/bundle-api+json";
+export declare const EXAMPLE_VERIFY_RESPONSE_DATE: "2026-03-12T21:12:26.646Z";
+export declare const EXAMPLE_VERIFY_RESPONSE_PROOF_DATE: "2026-03-12T21:12:57.534Z";
+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_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_ORG_ATTACHMENT_ID: "vc-jwt-1";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT_ID: "vc-jwt-2";
+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_ORG_JWT: "<vc-jwt-organization>";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_JWT: "<vc-jwt-legal-representative>";
+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";
+export declare const EXAMPLE_VERIFY_RESPONSE_ORG_KID: "org-es384-001";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_KID: "controller-es384-001";
+export declare const EXAMPLE_VERIFY_RESPONSE_ORG_DID: "did:web:globaldatacare.es:onehealth:organization:taxid:VATES-B00112233";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_NAME: "Alex Example";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_GIVEN_NAME: "Alex";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_FAMILY_NAME: "Example";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_NATIONALITY: "ES";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_ADDITIONAL_TYPE: "ES384";
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_ALTERNATE_NAME: "controller-es384-001";
+export declare const EXAMPLE_VERIFY_RESPONSE_ORG_ADDITIONAL_TYPE: "sector=onehealth;section=dataprovider;kind=clinic;action=_index-provider,_research-provider";
+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_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>";
+/**
+ * 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_ORG_PUBLIC_KEY_JWK: Readonly<{
+    kty: "EC";
+    crv: "P-384";
+    x: "org-pub-x";
+    y: "org-pub-y";
+    alg: "ES384";
+    kid: "org-es384-001";
+}>;
+export declare const EXAMPLE_VERIFY_RESPONSE_ORG_PRIVATE_KEY_JWK: Readonly<{
+    d: "org-priv-d";
+    kty: "EC";
+    crv: "P-384";
+    x: "org-pub-x";
+    y: "org-pub-y";
+    alg: "ES384";
+    kid: "org-es384-001";
+}>;
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_PUBLIC_KEY_JWK: Readonly<{
+    kty: "EC";
+    crv: "P-384";
+    x: "controller-x";
+    y: "controller-y";
+    alg: "ES384";
+    kid: "controller-es384-001";
+}>;
+export declare const EXAMPLE_VERIFY_RESPONSE_ORG_AUTHORIZED_CATEGORY: "health-care";
+export declare const EXAMPLE_VERIFY_RESPONSE_ORG_CREDENTIAL: Readonly<{
+    id: "urn:uuid:org-vc-001";
+    '@context': ("https://www.w3.org/ns/credentials/v2" | "https://schema.org")[];
+    type: ("VerifiableCredential" | "OrganizationCredential")[];
+    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': "Organization";
+        legalName: "ACME Health Provider";
+        taxID: "VATES-B00112233";
+        sameAs: "did:web:provider.example.org";
+        url: "health-care.provider.example.org";
+        alternateName: string;
+        additionalType: "sector=onehealth;section=dataprovider;kind=clinic;action=_index-provider,_research-provider";
+        makesOffer: {
+            '@type': string;
+            category: "health-care";
+        };
+        address: {
+            '@type': "PostalAddress";
+            addressCountry: "ES";
+        };
+    };
+    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-organization-truncated>";
+    };
+}>;
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL: Readonly<{
+    id: "urn:uuid:person-vc-001";
+    '@context': ("https://www.w3.org/ns/credentials/v2" | "https://schema.org")[];
+    type: ("VerifiableCredential" | "LegalRepresentativeCredential" | "PersonCredential")[];
+    issuer: "did:web:ica.example.org";
+    validFrom: "2026-03-12T21:12:26.646Z";
+    meta: {
+        versionId: "zPdfVersionHash001";
+    };
+    credentialSubject: {
+        id: "urn:person:identifier:IDCES-99999999R";
+        '@type': "Person";
+        name: "Alex Example";
+        givenName: "Alex";
+        familyName: "Example";
+        identifier: "IDCES-99999999R";
+        nationality: "ES";
+        sameAs: "urn:multibase:zControllerHash";
+        hasCredential: {
+            material: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+        };
+        hasOccupation: {
+            '@type': "Occupation";
+            name: "LegalRepresentative";
+            identifier: "urn:ilo:ilostat:isco-08:1120";
+        };
+        memberOf: {
+            '@type': "Organization";
+            legalName: "ACME Health Provider";
+            taxID: "VATES-B00112233";
+        };
+        alternateName: "controller-es384-001";
+        additionalType: "ES384";
+    };
+    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-person-truncated>";
+    };
+}>;
+export declare const EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT: IcaVerifyResponseExampleAttachment;
+export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT: IcaVerifyResponseExampleAttachment;
+/**
+ * Canonical `_verify-response` success example shared across ICA repos.
+ */
+export declare const EXAMPLE_ICA_VERIFY_TERMS_RESPONSE_SUCCESS: IcaVerifyTermsResponseExample;
+/**
+ * Returns a detached deep clone of the canonical ICA `_verify-response`
+ * success example so tests/docs can tweak fields without mutating the shared
+ * frozen baseline.
+ */
+export declare function cloneIcaVerifyTermsResponseSuccessExample(): IcaVerifyTermsResponseExample;

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

@@ -0,0 +1,263 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+import { ActivationCredentialTypes, W3cCredentialContexts, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { DataspaceSectors } from '../constants/sectors.js';
+import { IssueSeverity, IssueType } from '../models/issue.js';
+import { EXAMPLE_DEFAULT_ICA_DID, EXAMPLE_BUNDLE_RESOURCE_TYPE, EXAMPLE_PROVIDER_DOMAIN, EXAMPLE_PROVIDER_LEGAL_NAME, EXAMPLE_PROVIDER_TAX_ID, EXAMPLE_TENANT_SERVICE_DID, } from './shared.js';
+import { EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID, EXAMPLE_REPRESENTATIVE_IDENTIFIER, EXAMPLE_REPRESENTATIVE_SAME_AS, EXAMPLE_REPRESENTATIVE_SUBJECT_URN, } from './ica-activation-proof.js';
+export const EXAMPLE_VERIFY_RESPONSE_OPERATION_OUTCOME_RESOURCE_TYPE = 'OperationOutcome';
+export const EXAMPLE_VERIFY_RESPONSE_BATCH_RESPONSE_TYPE = 'batch-response';
+export const EXAMPLE_VERIFY_RESPONSE_SCHEMA_ORG_CONTEXT = 'https://schema.org';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_TYPE = 'Person';
+export const EXAMPLE_VERIFY_RESPONSE_ORGANIZATION_TYPE = ResourceTypesFhirR4.Organization;
+export const EXAMPLE_VERIFY_RESPONSE_JTI = 'urn:uuid:verify-resp-001';
+export const EXAMPLE_VERIFY_RESPONSE_THID = 'verify-terms-001';
+export const EXAMPLE_VERIFY_RESPONSE_BUNDLE_TYPE = 'application/bundle-api+json';
+export const EXAMPLE_VERIFY_RESPONSE_DATE = '2026-03-12T21:12:26.646Z';
+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_ORG_ENTRY_TYPE = 'Organization-verification-v1.0';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_ENTRY_TYPE = 'LegalRepresentative-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_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_ORG_JWT = '<vc-jwt-organization>';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_JWT = '<vc-jwt-legal-representative>';
+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';
+export const EXAMPLE_VERIFY_RESPONSE_ORG_KID = 'org-es384-001';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_KID = 'controller-es384-001';
+export const EXAMPLE_VERIFY_RESPONSE_ORG_DID = 'did:web:globaldatacare.es:onehealth:organization:taxid:VATES-B00112233';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_NAME = 'Alex Example';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_GIVEN_NAME = 'Alex';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_FAMILY_NAME = 'Example';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_NATIONALITY = 'ES';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_ADDITIONAL_TYPE = 'ES384';
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_ALTERNATE_NAME = EXAMPLE_VERIFY_RESPONSE_PERSON_KID;
+export const EXAMPLE_VERIFY_RESPONSE_ORG_ADDITIONAL_TYPE = 'sector=onehealth;section=dataprovider;kind=clinic;action=_index-provider,_research-provider';
+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_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>';
+/**
+ * Shared success outcome reused at bundle level and item level.
+ */
+export const EXAMPLE_VERIFY_RESPONSE_SUCCESS_OUTCOME = {
+    resourceType: EXAMPLE_VERIFY_RESPONSE_OPERATION_OUTCOME_RESOURCE_TYPE,
+    issue: [
+        {
+            severity: IssueSeverity.Information,
+            code: IssueType.Informational,
+            diagnostics: 'Verification completed.',
+        },
+    ],
+};
+export const EXAMPLE_VERIFY_RESPONSE_ORG_ITEM_OUTCOME = {
+    resourceType: EXAMPLE_VERIFY_RESPONSE_OPERATION_OUTCOME_RESOURCE_TYPE,
+    issue: [
+        {
+            severity: IssueSeverity.Information,
+            code: IssueType.Informational,
+            diagnostics: 'Organization credential extracted from verified document.',
+        },
+    ],
+};
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_ITEM_OUTCOME = {
+    resourceType: EXAMPLE_VERIFY_RESPONSE_OPERATION_OUTCOME_RESOURCE_TYPE,
+    issue: [
+        {
+            severity: IssueSeverity.Information,
+            code: IssueType.Informational,
+            diagnostics: 'Legal representative credential extracted from verified document.',
+        },
+    ],
+};
+export const EXAMPLE_VERIFY_RESPONSE_ORG_PUBLIC_KEY_JWK = Object.freeze({
+    kty: 'EC',
+    crv: 'P-384',
+    x: 'org-pub-x',
+    y: 'org-pub-y',
+    alg: 'ES384',
+    kid: EXAMPLE_VERIFY_RESPONSE_ORG_KID,
+});
+export const EXAMPLE_VERIFY_RESPONSE_ORG_PRIVATE_KEY_JWK = Object.freeze({
+    ...EXAMPLE_VERIFY_RESPONSE_ORG_PUBLIC_KEY_JWK,
+    d: 'org-priv-d',
+});
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_PUBLIC_KEY_JWK = Object.freeze({
+    kty: 'EC',
+    crv: 'P-384',
+    x: 'controller-x',
+    y: 'controller-y',
+    alg: 'ES384',
+    kid: EXAMPLE_VERIFY_RESPONSE_PERSON_KID,
+});
+export const EXAMPLE_VERIFY_RESPONSE_ORG_AUTHORIZED_CATEGORY = DataspaceSectors.HealthCare;
+export const EXAMPLE_VERIFY_RESPONSE_ORG_CREDENTIAL = Object.freeze({
+    id: EXAMPLE_VERIFY_RESPONSE_ORG_VC_ID,
+    '@context': [W3cCredentialContexts.V2, EXAMPLE_VERIFY_RESPONSE_SCHEMA_ORG_CONTEXT],
+    type: [W3cCredentialTypes.VerifiableCredential, ActivationCredentialTypes.OrganizationCredential],
+    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': EXAMPLE_VERIFY_RESPONSE_ORGANIZATION_TYPE,
+        legalName: EXAMPLE_PROVIDER_LEGAL_NAME,
+        taxID: EXAMPLE_PROVIDER_TAX_ID,
+        sameAs: EXAMPLE_TENANT_SERVICE_DID,
+        url: EXAMPLE_PROVIDER_DOMAIN,
+        alternateName: 'example-provider',
+        additionalType: EXAMPLE_VERIFY_RESPONSE_ORG_ADDITIONAL_TYPE,
+        makesOffer: {
+            '@type': 'Offer',
+            category: EXAMPLE_VERIFY_RESPONSE_ORG_AUTHORIZED_CATEGORY,
+        },
+        address: {
+            '@type': EXAMPLE_VERIFY_RESPONSE_ADDRESS_TYPE,
+            addressCountry: EXAMPLE_VERIFY_RESPONSE_ADDRESS_COUNTRY,
+        },
+    },
+    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_ORG_PROOF_JWS,
+    },
+});
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL = Object.freeze({
+    id: EXAMPLE_VERIFY_RESPONSE_PERSON_VC_ID,
+    '@context': [W3cCredentialContexts.V2, EXAMPLE_VERIFY_RESPONSE_SCHEMA_ORG_CONTEXT],
+    type: [
+        W3cCredentialTypes.VerifiableCredential,
+        ActivationCredentialTypes.PersonCredential,
+        ActivationCredentialTypes.LegalRepresentativeCredential,
+    ],
+    issuer: EXAMPLE_DEFAULT_ICA_DID,
+    validFrom: EXAMPLE_VERIFY_RESPONSE_DATE,
+    meta: {
+        versionId: EXAMPLE_VERIFY_RESPONSE_VERSION_ID,
+    },
+    credentialSubject: {
+        id: EXAMPLE_REPRESENTATIVE_SUBJECT_URN,
+        '@type': EXAMPLE_VERIFY_RESPONSE_PERSON_TYPE,
+        name: EXAMPLE_VERIFY_RESPONSE_PERSON_NAME,
+        givenName: EXAMPLE_VERIFY_RESPONSE_PERSON_GIVEN_NAME,
+        familyName: EXAMPLE_VERIFY_RESPONSE_PERSON_FAMILY_NAME,
+        identifier: EXAMPLE_REPRESENTATIVE_IDENTIFIER,
+        nationality: EXAMPLE_VERIFY_RESPONSE_PERSON_NATIONALITY,
+        sameAs: EXAMPLE_REPRESENTATIVE_SAME_AS,
+        hasCredential: {
+            material: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
+        },
+        hasOccupation: {
+            '@type': EXAMPLE_VERIFY_RESPONSE_OCCUPATION_TYPE,
+            name: EXAMPLE_VERIFY_RESPONSE_OCCUPATION_NAME,
+            identifier: EXAMPLE_VERIFY_RESPONSE_OCCUPATION_IDENTIFIER,
+        },
+        memberOf: {
+            '@type': EXAMPLE_VERIFY_RESPONSE_ORGANIZATION_TYPE,
+            legalName: EXAMPLE_PROVIDER_LEGAL_NAME,
+            taxID: EXAMPLE_PROVIDER_TAX_ID,
+        },
+        alternateName: EXAMPLE_VERIFY_RESPONSE_PERSON_ALTERNATE_NAME,
+        additionalType: EXAMPLE_VERIFY_RESPONSE_PERSON_ADDITIONAL_TYPE,
+    },
+    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_PERSON_PROOF_JWS,
+    },
+});
+export const EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT = Object.freeze({
+    id: EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT_ID,
+    format: EXAMPLE_VERIFY_RESPONSE_ATTACHMENT_FORMAT,
+    media_type: EXAMPLE_VERIFY_RESPONSE_MEDIA_TYPE,
+    filename: EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT_FILENAME,
+    data: {
+        json: {
+            format: EXAMPLE_VERIFY_RESPONSE_ATTACHMENT_FORMAT,
+            jwt: EXAMPLE_VERIFY_RESPONSE_ORG_JWT,
+        },
+    },
+});
+export const EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT = Object.freeze({
+    id: EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT_ID,
+    format: EXAMPLE_VERIFY_RESPONSE_ATTACHMENT_FORMAT,
+    media_type: EXAMPLE_VERIFY_RESPONSE_MEDIA_TYPE,
+    filename: EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT_FILENAME,
+    data: {
+        json: {
+            format: EXAMPLE_VERIFY_RESPONSE_ATTACHMENT_FORMAT,
+            jwt: EXAMPLE_VERIFY_RESPONSE_PERSON_JWT,
+        },
+    },
+});
+/**
+ * Canonical `_verify-response` success example shared across ICA repos.
+ */
+export const EXAMPLE_ICA_VERIFY_TERMS_RESPONSE_SUCCESS = {
+    jti: EXAMPLE_VERIFY_RESPONSE_JTI,
+    iss: EXAMPLE_DEFAULT_ICA_DID,
+    aud: EXAMPLE_DEFAULT_ICA_DID,
+    thid: EXAMPLE_VERIFY_RESPONSE_THID,
+    type: EXAMPLE_VERIFY_RESPONSE_BUNDLE_TYPE,
+    attachments: [
+        EXAMPLE_VERIFY_RESPONSE_ORG_ATTACHMENT,
+        EXAMPLE_VERIFY_RESPONSE_PERSON_ATTACHMENT,
+    ],
+    body: {
+        resourceType: EXAMPLE_BUNDLE_RESOURCE_TYPE,
+        type: EXAMPLE_VERIFY_RESPONSE_BATCH_RESPONSE_TYPE,
+        total: 2,
+        issues: EXAMPLE_VERIFY_RESPONSE_SUCCESS_OUTCOME,
+        data: [
+            {
+                type: EXAMPLE_VERIFY_RESPONSE_ORG_ENTRY_TYPE,
+                publicKeyJwk: EXAMPLE_VERIFY_RESPONSE_ORG_PUBLIC_KEY_JWK,
+                privateKeyJwk: EXAMPLE_VERIFY_RESPONSE_ORG_PRIVATE_KEY_JWK,
+                keySource: 'generated',
+                response: {
+                    status: EXAMPLE_VERIFY_RESPONSE_STATUS_OK,
+                    outcome: EXAMPLE_VERIFY_RESPONSE_ORG_ITEM_OUTCOME,
+                },
+                resource: EXAMPLE_VERIFY_RESPONSE_ORG_CREDENTIAL,
+            },
+            {
+                type: EXAMPLE_VERIFY_RESPONSE_PERSON_ENTRY_TYPE,
+                publicKeyJwk: EXAMPLE_VERIFY_RESPONSE_PERSON_PUBLIC_KEY_JWK,
+                response: {
+                    status: EXAMPLE_VERIFY_RESPONSE_STATUS_OK,
+                    outcome: EXAMPLE_VERIFY_RESPONSE_PERSON_ITEM_OUTCOME,
+                },
+                resource: EXAMPLE_VERIFY_RESPONSE_PERSON_CREDENTIAL,
+            },
+        ],
+    },
+};
+/**
+ * Returns a detached deep clone of the canonical ICA `_verify-response`
+ * success example so tests/docs can tweak fields without mutating the shared
+ * frozen baseline.
+ */
+export function cloneIcaVerifyTermsResponseSuccessExample() {
+    return JSON.parse(JSON.stringify(EXAMPLE_ICA_VERIFY_TERMS_RESPONSE_SUCCESS));
+}

package/dist/examples/index.d.ts

@@ -1,7 +1,10 @@
 export * from './shared';
 export * from './ica-activation-proof';
+export * from './ica-verify-response';
 export * from './dataspace-discovery';
 export * from './organization-controller';
+export * from './organization-did-binding';
+export * from './legal-organization-verification-transaction';
 export * from './individual-controller';
 export * from './professional';
 export * from './employee';

package/dist/examples/index.js

@@ -1,7 +1,10 @@
 export * from './shared.js';
 export * from './ica-activation-proof.js';
+export * from './ica-verify-response.js';
 export * from './dataspace-discovery.js';
 export * from './organization-controller.js';
+export * from './organization-did-binding.js';
+export * from './legal-organization-verification-transaction.js';
 export * from './individual-controller.js';
 export * from './professional.js';
 export * from './employee.js';

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

@@ -0,0 +1 @@
+export declare const EXAMPLE_LEGAL_ORGANIZATION_VERIFICATION_TRANSACTION_BUNDLE: import("..").BundleJsonApi<import("..").ErrorEntry | import("..").BundleEntry>;

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

@@ -0,0 +1,66 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { ClaimsOrganizationSchemaorg, ClaimsPersonSchemaorg, ClaimsServiceSchemaorg, } from '../constants/schemaorg.js';
+import { buildLegalOrganizationVerificationTransactionBundle, } from '../utils/legal-organization-verification-transaction.js';
+import { EXAMPLE_CONTROLLER_BINDING, EXAMPLE_EMAIL_CONTROLLER_ORG, EXAMPLE_JURISDICTION, EXAMPLE_ORGANIZATION_LEGAL_NAME, EXAMPLE_LEGAL_ORGANIZATION_TAX_ID, EXAMPLE_SECTOR, EXAMPLE_SIGNED_TERMS_PDF_URL, EXAMPLE_TENANT_SERVICE_DID, } from './shared.js';
+/**
+ * Canonical host-onboarding transaction example for the new ICA verification
+ * first step.
+ *
+ * Why this exists:
+ * - BFF/portal integrations need one stable example of the GW CORE request
+ *   that wraps an ICA `_verify`
+ * - the example keeps the controller business binding separate from any
+ *   technical DIDComm communication key
+ */
+const exampleControllerBinding = {
+    did: EXAMPLE_CONTROLLER_BINDING.did,
+    sameAs: EXAMPLE_CONTROLLER_BINDING.sameAs,
+    publicKeyJwk: { ...EXAMPLE_CONTROLLER_BINDING.publicKeyJwk },
+    ...(EXAMPLE_CONTROLLER_BINDING.jwks
+        ? {
+            jwks: {
+                keys: EXAMPLE_CONTROLLER_BINDING.jwks.keys.map((item) => ({ ...item })),
+            },
+        }
+        : {}),
+};
+export const EXAMPLE_LEGAL_ORGANIZATION_VERIFICATION_TRANSACTION_BUNDLE = buildLegalOrganizationVerificationTransactionBundle({
+    claims: {
+        '@context': 'org.schema',
+        [ClaimsOrganizationSchemaorg.legalName]: EXAMPLE_ORGANIZATION_LEGAL_NAME,
+        [ClaimsOrganizationSchemaorg.identifierType]: 'taxID',
+        [ClaimsOrganizationSchemaorg.identifierValue]: EXAMPLE_LEGAL_ORGANIZATION_TAX_ID,
+        [ClaimsOrganizationSchemaorg.taxId]: EXAMPLE_LEGAL_ORGANIZATION_TAX_ID,
+        [ClaimsOrganizationSchemaorg.addressCountry]: EXAMPLE_JURISDICTION,
+        [ClaimsPersonSchemaorg.email]: EXAMPLE_EMAIL_CONTROLLER_ORG,
+        [ClaimsServiceSchemaorg.category]: EXAMPLE_SECTOR,
+        [ClaimsServiceSchemaorg.identifier]: EXAMPLE_TENANT_SERVICE_DID,
+        [ClaimsServiceSchemaorg.url]: `https://operator.example.net/acme/cds-${String(EXAMPLE_JURISDICTION).toLowerCase()}/v1/${EXAMPLE_SECTOR}`,
+    },
+    controller: exampleControllerBinding,
+    organization: {
+        did: EXAMPLE_TENANT_SERVICE_DID,
+        publicKeyJwk: {
+            kid: 'organization-signing-es384-001',
+            kty: 'EC',
+            crv: 'P-384',
+            x: '<organization-sign-x>',
+            y: '<organization-sign-y>',
+            alg: 'ES384',
+            use: 'sig',
+        },
+    },
+    legalRepresentativePayload: {
+        email: EXAMPLE_EMAIL_CONTROLLER_ORG,
+    },
+    verification: {
+        resourceType: 'contract',
+    },
+    attachments: [{
+            id: 'signed-terms-pdf-001',
+            media_type: 'application/pdf',
+            data: {
+                links: [EXAMPLE_SIGNED_TERMS_PDF_URL],
+            },
+        }],
+});

package/dist/examples/organization-did-binding.d.ts

@@ -0,0 +1 @@
+export declare const EXAMPLE_ORGANIZATION_DID_BINDING_BUNDLE: import("..").BundleJsonApi<import("..").ErrorEntry | import("..").BundleEntry>;

package/dist/examples/organization-did-binding.js

@@ -0,0 +1,14 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { buildOrganizationDidBindingBundle } from '../utils/organization-did-binding.js';
+import { EXAMPLE_CONTROLLER_BINDING, EXAMPLE_TENANT_SERVICE_DID, } from './shared.js';
+export const EXAMPLE_ORGANIZATION_DID_BINDING_BUNDLE = buildOrganizationDidBindingBundle({
+    organization: {
+        url: [
+            'https://provider.example.org',
+            EXAMPLE_TENANT_SERVICE_DID,
+        ],
+    },
+    controller: {
+        sameAs: EXAMPLE_CONTROLLER_BINDING.sameAs,
+    },
+});

package/dist/examples/shared.d.ts

@@ -17,6 +17,8 @@ export declare const EXAMPLE_NETWORK_TYPE: "test";
 export declare const EXAMPLE_ROUTE_VERSION: "v1";
 export declare const EXAMPLE_SECTOR: "health-care";
 export declare const EXAMPLE_EMAIL_CONTROLLER_ORG: "controller@acme.org";
+export declare const EXAMPLE_ORGANIZATION_LEGAL_NAME: "ACME HEALTH SL";
+export declare const EXAMPLE_LEGAL_ORGANIZATION_TAX_ID: "VATES-B00112233";
 export declare const EXAMPLE_EMAIL_CONTROLLER_INDIVIDUAL: "ana.parent@example.org";
 export declare const EXAMPLE_INTEROPERABLE_CONTEXT_FHIR_API: "org.hl7.fhir.api";
 export declare const EXAMPLE_SELF_REGISTERED_INDIVIDUAL_ALTERNATE_NAME: "Jane";
@@ -27,6 +29,7 @@ export declare const EXAMPLE_SELF_REGISTERED_INDIVIDUAL_BIRTH_YEAR: "1980";
 export declare const EXAMPLE_REGISTERED_SUBJECT_ALTERNATE_NAME: "Doraemon";
 export declare const EXAMPLE_REGISTERED_SUBJECT_BIRTH_YEAR: "2020";
 export declare const EXAMPLE_PDF_CONSENT_DATE: "2026-06-08";
+export declare const EXAMPLE_SIGNED_TERMS_PDF_URL: "https://portal.example.org/files/legal-organization-signed-terms.pdf";
 /**
  * Public provider domain selected during autodiscovery.
  *

package/dist/examples/shared.js

@@ -32,6 +32,8 @@ export const EXAMPLE_NETWORK_TYPE = HostNetworkTypes.Test;
 export const EXAMPLE_ROUTE_VERSION = 'v1';
 export const EXAMPLE_SECTOR = DataspaceSectors.HealthCare;
 export const EXAMPLE_EMAIL_CONTROLLER_ORG = 'controller@acme.org';
+export const EXAMPLE_ORGANIZATION_LEGAL_NAME = 'ACME HEALTH SL';
+export const EXAMPLE_LEGAL_ORGANIZATION_TAX_ID = 'VATES-B00112233';
 export const EXAMPLE_EMAIL_CONTROLLER_INDIVIDUAL = 'ana.parent@example.org';
 export const EXAMPLE_INTEROPERABLE_CONTEXT_FHIR_API = Format.FHIR_API;
 export const EXAMPLE_SELF_REGISTERED_INDIVIDUAL_ALTERNATE_NAME = 'Jane';
@@ -42,6 +44,7 @@ export const EXAMPLE_SELF_REGISTERED_INDIVIDUAL_BIRTH_YEAR = '1980';
 export const EXAMPLE_REGISTERED_SUBJECT_ALTERNATE_NAME = 'Doraemon';
 export const EXAMPLE_REGISTERED_SUBJECT_BIRTH_YEAR = '2020';
 export const EXAMPLE_PDF_CONSENT_DATE = '2026-06-08';
+export const EXAMPLE_SIGNED_TERMS_PDF_URL = 'https://portal.example.org/files/legal-organization-signed-terms.pdf';
 /**
  * Public provider domain selected during autodiscovery.
  *

package/dist/utils/index.d.ts

@@ -49,6 +49,7 @@ export * from './family-registration-test-data';
 export * from './individual-form-pdf';
 export * from './individual-organization-claims';
 export * from './organization-lifecycle';
+export * from './organization-did-binding';
 export * from './individual-organization-lifecycle';
 export * from './individual-onboarding-editor';
 export * from './individual-onboarding-document-reference';
@@ -60,6 +61,7 @@ export * from './interoperable-resource-operation';
 export * from './jwt';
 export * from './jwk-thumbprint';
 export * from './legal-organization-onboarding';
+export * from './legal-organization-verification-transaction';
 export * from './license';
 export * from './license-commercial-search';
 export * from './license-list-search';

package/dist/utils/index.js

@@ -49,6 +49,7 @@ export * from './family-registration-test-data.js';
 export * from './individual-form-pdf.js';
 export * from './individual-organization-claims.js';
 export * from './organization-lifecycle.js';
+export * from './organization-did-binding.js';
 export * from './individual-organization-lifecycle.js';
 export * from './individual-onboarding-editor.js';
 export * from './individual-onboarding-document-reference.js';
@@ -60,6 +61,7 @@ export * from './interoperable-resource-operation.js';
 export * from './jwt.js';
 export * from './jwk-thumbprint.js';
 export * from './legal-organization-onboarding.js';
+export * from './legal-organization-verification-transaction.js';
 export * from './license.js';
 export * from './license-commercial-search.js';
 export * from './license-list-search.js';

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

@@ -0,0 +1,90 @@
+import type { BundleJsonApi } from '../models/bundle';
+import type { ClaimsRecord } from '../models/resource-document';
+/**
+ * Canonical business entry type for the first host-side onboarding step that
+ * asks GW CORE to forward a legal-organization verification request to ICA.
+ *
+ * Responsibilities of this transaction:
+ * - carry the signed PDF evidence or PDF URL attachment
+ * - carry the controller business binding key
+ * - optionally carry the organization VC-signing public key chosen by the host
+ * - carry the legal organization claims that GW CORE should keep through the
+ *   verification/onboarding pipeline
+ *
+ * Non-responsibilities:
+ * - it is not the same thing as host `_activate`
+ * - it does not model Fabric/CSR enrollment
+ */
+export declare const LegalOrganizationVerificationTransactionEntryTypes: Readonly<{
+    readonly Request: "Organization-verification-transaction-request-v1.0";
+    readonly Response: "Organization-verification-transaction-response-v1.0";
+}>;
+export type LegalOrganizationVerificationTransactionEntryType = typeof LegalOrganizationVerificationTransactionEntryTypes[keyof typeof LegalOrganizationVerificationTransactionEntryTypes];
+/**
+ * Explicit controller binding material that ICA should project into the legal
+ * representative VC.
+ */
+export type LegalOrganizationVerificationTransactionController = Readonly<{
+    did?: string;
+    sameAs?: string;
+    publicKeyJwk?: Record<string, unknown>;
+    jwks?: {
+        keys: Array<Record<string, unknown>>;
+    };
+}>;
+/**
+ * Optional organization-side public key material that the hosting operator may
+ * already know before the final activation/publication step.
+ */
+export type LegalOrganizationVerificationTransactionOrganization = Readonly<{
+    did?: string;
+    url?: string;
+    publicKeyJwk?: Record<string, unknown>;
+    jwks?: {
+        keys: Array<Record<string, unknown>>;
+    };
+}>;
+/**
+ * Additional legal-representative payload fields forwarded to ICA `_verify`.
+ *
+ * These values help ICA derive `sameAs` when the signed document itself does
+ * not expose that contact value in a directly reusable way.
+ */
+export type LegalOrganizationVerificationRepresentativePayload = Readonly<{
+    email?: string;
+    sameAs?: string;
+}>;
+/**
+ * Optional verification routing hints for ICA.
+ *
+ * `resourceType` defaults to `contract`, which matches the current
+ * legal-organization terms flow in ICA.
+ */
+export type LegalOrganizationVerificationRouting = Readonly<{
+    resourceType?: string;
+}>;
+/**
+ * Canonical input accepted by shared SDK/GW helpers when building the first
+ * host onboarding transaction that wraps an ICA `_verify` request.
+ */
+export type LegalOrganizationVerificationTransactionInput = Readonly<{
+    claims: ClaimsRecord;
+    controller: LegalOrganizationVerificationTransactionController;
+    organization?: LegalOrganizationVerificationTransactionOrganization;
+    legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
+    verification?: LegalOrganizationVerificationRouting;
+    attachments?: unknown[];
+}>;
+/**
+ * Builds the canonical Bundle payload for host-side legal organization
+ * verification transactions.
+ *
+ * Contract notes:
+ * - business claims remain in `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
+ * - `Service.category` is the canonical business-sector input later used by GW
+ *   to target the appropriate ICA verification route
+ */
+export declare function buildLegalOrganizationVerificationTransactionBundle(input: LegalOrganizationVerificationTransactionInput): BundleJsonApi;

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

@@ -0,0 +1,65 @@
+import { ClaimsServiceSchemaorg } from '../constants/schemaorg.js';
+/**
+ * Canonical business entry type for the first host-side onboarding step that
+ * asks GW CORE to forward a legal-organization verification request to ICA.
+ *
+ * Responsibilities of this transaction:
+ * - carry the signed PDF evidence or PDF URL attachment
+ * - carry the controller business binding key
+ * - optionally carry the organization VC-signing public key chosen by the host
+ * - carry the legal organization claims that GW CORE should keep through the
+ *   verification/onboarding pipeline
+ *
+ * Non-responsibilities:
+ * - it is not the same thing as host `_activate`
+ * - it does not model Fabric/CSR enrollment
+ */
+export const LegalOrganizationVerificationTransactionEntryTypes = Object.freeze({
+    Request: 'Organization-verification-transaction-request-v1.0',
+    Response: 'Organization-verification-transaction-response-v1.0',
+});
+function normalizeText(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * Builds the canonical Bundle payload for host-side legal organization
+ * verification transactions.
+ *
+ * Contract notes:
+ * - business claims remain in `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
+ * - `Service.category` is the canonical business-sector input later used by GW
+ *   to target the appropriate ICA verification route
+ */
+export function buildLegalOrganizationVerificationTransactionBundle(input) {
+    const businessSector = normalizeText(input.claims?.[ClaimsServiceSchemaorg.category]);
+    if (!businessSector) {
+        throw new Error(`buildLegalOrganizationVerificationTransactionBundle requires ${ClaimsServiceSchemaorg.category}.`);
+    }
+    return {
+        resourceType: 'Bundle',
+        type: 'collection',
+        total: 1,
+        data: [{
+                type: LegalOrganizationVerificationTransactionEntryTypes.Request,
+                meta: {
+                    claims: input.claims,
+                },
+                resource: {
+                    controller: input.controller,
+                    ...(input.organization ? { organization: input.organization } : {}),
+                    ...(input.legalRepresentativePayload
+                        ? { legalRepresentativePayload: input.legalRepresentativePayload }
+                        : {}),
+                    verification: {
+                        resourceType: normalizeText(input.verification?.resourceType) || 'contract',
+                    },
+                },
+            }],
+        ...(Array.isArray(input.attachments) && input.attachments.length > 0
+            ? { attachments: input.attachments }
+            : {}),
+    };
+}

package/dist/utils/organization-did-binding.d.ts

@@ -0,0 +1,60 @@
+import type { BundleJsonApi } from '../models/bundle';
+export declare const OrganizationDidBindingEntryTypes: Readonly<{
+    readonly Request: "Organization-did-binding-request-v1.0";
+    readonly Response: "Organization-did-binding-response-v1.0";
+}>;
+export type OrganizationDidBindingErrorCode = 'MISSING_ORGANIZATION_URL' | 'UNSUPPORTED_ORGANIZATION_LOCATOR';
+export type OrganizationDidBindingValidationError = Readonly<{
+    code: OrganizationDidBindingErrorCode;
+    message: string;
+    claimPaths: string[];
+}>;
+export type OrganizationDidBindingControllerInput = Readonly<{
+    sameAs?: string;
+}>;
+export type OrganizationDidBindingOrganizationInput = Readonly<{
+    url: string | string[];
+    taxID?: string;
+    taxId?: string;
+    identifier?: string;
+}>;
+export type OrganizationDidBindingInput = Readonly<{
+    organization: OrganizationDidBindingOrganizationInput;
+    controller?: OrganizationDidBindingControllerInput;
+}>;
+export type ValidateOrganizationDidBindingInputResult = Readonly<{
+    ok: boolean;
+    errors: OrganizationDidBindingValidationError[];
+    normalizedInput: Readonly<{
+        organization: {
+            url: string[];
+        };
+        controller?: OrganizationDidBindingControllerInput;
+    }>;
+}>;
+/**
+ * Validates the tenant-scoped organization DID binding request.
+ *
+ * Canonical contract:
+ * - the organization is already identified by the tenant path in GW CORE
+ * - callers send one or more public aliases in `organization.url`
+ * - `controller.sameAs` is optional additional evidence, not a new key-binding
+ *   bootstrap step
+ *
+ * Current version limits:
+ * - no `taxID` / `identifier` locator is required
+ * - sending those legacy locator fields is rejected so callers do not mix path
+ *   identity with payload identity
+ */
+export declare function validateOrganizationDidBindingInput(input: OrganizationDidBindingInput): ValidateOrganizationDidBindingInputResult;
+/**
+ * Builds the canonical bundle payload for one tenant-scoped DID binding
+ * request.
+ *
+ * Result contract:
+ * - `resource.organization.url` carries the public alias replacement list
+ * - `resource.controller.sameAs` is optional corroborating identity material
+ * - organization identity is resolved from the tenant path, not from payload
+ *   locators
+ */
+export declare function buildOrganizationDidBindingBundle(input: OrganizationDidBindingInput): BundleJsonApi;

package/dist/utils/organization-did-binding.js

@@ -0,0 +1,103 @@
+export const OrganizationDidBindingEntryTypes = Object.freeze({
+    Request: 'Organization-did-binding-request-v1.0',
+    Response: 'Organization-did-binding-response-v1.0',
+});
+function normalizeOptionalText(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length ? trimmed : undefined;
+}
+function normalizeOrganizationUrls(value) {
+    if (Array.isArray(value)) {
+        const urls = value
+            .map((item) => normalizeOptionalText(item))
+            .filter((item) => Boolean(item));
+        return urls.length ? urls : undefined;
+    }
+    const raw = normalizeOptionalText(value);
+    if (!raw)
+        return undefined;
+    const urls = raw
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return urls.length ? urls : undefined;
+}
+/**
+ * Validates the tenant-scoped organization DID binding request.
+ *
+ * Canonical contract:
+ * - the organization is already identified by the tenant path in GW CORE
+ * - callers send one or more public aliases in `organization.url`
+ * - `controller.sameAs` is optional additional evidence, not a new key-binding
+ *   bootstrap step
+ *
+ * Current version limits:
+ * - no `taxID` / `identifier` locator is required
+ * - sending those legacy locator fields is rejected so callers do not mix path
+ *   identity with payload identity
+ */
+export function validateOrganizationDidBindingInput(input) {
+    const errors = [];
+    const normalizedUrls = normalizeOrganizationUrls(input?.organization?.url);
+    const taxID = normalizeOptionalText(input?.organization?.taxID || input?.organization?.taxId);
+    const identifier = normalizeOptionalText(input?.organization?.identifier);
+    const controllerSameAs = normalizeOptionalText(input?.controller?.sameAs);
+    if (!normalizedUrls?.length) {
+        errors.push({
+            code: 'MISSING_ORGANIZATION_URL',
+            message: 'Organization DID binding requires at least one organization.url value.',
+            claimPaths: ['organization.url'],
+        });
+    }
+    if (taxID || identifier) {
+        errors.push({
+            code: 'UNSUPPORTED_ORGANIZATION_LOCATOR',
+            message: 'Organization DID binding in GW CORE uses the tenant path as locator and does not accept organization.taxID or organization.identifier in this version.',
+            claimPaths: ['organization.taxID', 'organization.identifier'],
+        });
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        normalizedInput: {
+            organization: {
+                url: normalizedUrls || [],
+            },
+            ...(controllerSameAs ? { controller: { sameAs: controllerSameAs } } : {}),
+        },
+    };
+}
+/**
+ * Builds the canonical bundle payload for one tenant-scoped DID binding
+ * request.
+ *
+ * Result contract:
+ * - `resource.organization.url` carries the public alias replacement list
+ * - `resource.controller.sameAs` is optional corroborating identity material
+ * - organization identity is resolved from the tenant path, not from payload
+ *   locators
+ */
+export function buildOrganizationDidBindingBundle(input) {
+    const validation = validateOrganizationDidBindingInput(input);
+    if (!validation.ok) {
+        throw new Error(validation.errors.map((item) => item.message).join(' '));
+    }
+    return {
+        resourceType: 'Bundle',
+        type: 'collection',
+        total: 1,
+        data: [{
+                type: OrganizationDidBindingEntryTypes.Request,
+                resource: {
+                    organization: {
+                        url: validation.normalizedInput.organization.url,
+                    },
+                    ...(validation.normalizedInput.controller
+                        ? { controller: validation.normalizedInput.controller }
+                        : {}),
+                },
+            }],
+    };
+}

package/package.json

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