gdc-common-utils-ts 2.0.2 → 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

@@ -136,6 +136,7 @@ export declare const EXAMPLE_VERIFY_RESPONSE_PERSON_PUBLIC_KEY_JWK: Readonly<{
     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")[];
@@ -154,6 +155,10 @@ export declare const EXAMPLE_VERIFY_RESPONSE_ORG_CREDENTIAL: Readonly<{
         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";

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

@@ -2,6 +2,7 @@
 // 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';
@@ -102,6 +103,7 @@ export const EXAMPLE_VERIFY_RESPONSE_PERSON_PUBLIC_KEY_JWK = Object.freeze({
     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],
@@ -120,6 +122,10 @@ export const EXAMPLE_VERIFY_RESPONSE_ORG_CREDENTIAL = Object.freeze({
         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,

package/dist/examples/index.d.ts

@@ -3,6 +3,8 @@ 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

@@ -3,6 +3,8 @@ 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.2",
+  "version": "2.0.4",
   "publishConfig": {
     "access": "public"
   },