gdc-common-utils-ts 1.10.0 → 1.12.0

package/README.md

@@ -86,6 +86,9 @@ import { JweObject, JwtCompactParts } from 'gdc-common-utils-ts/models';
 
 ## Cross-Repo Task Docs
 
+- [docs/DATASPACE_DISCOVERY_ROADMAP.md](docs/DATASPACE_DISCOVERY_ROADMAP.md)
+  - cross-repo contract for dataspace discovery semantics, EU coverage
+    inference, shared DTOs, and parameterized examples
 - [docs/consent-access-matrix-task.md](docs/consent-access-matrix-task.md)
   - next-step design/task document for active consent aggregation, explicit deny precedence, controller views, permission-request communications, and SMART access evaluation
 

package/dist/constants/cryptography.d.ts

@@ -14,6 +14,29 @@ export declare const CommunicationKeyPurposes: {
     readonly CommunicationSignature: "comm_sig";
     readonly VerifiableCredentialSignature: "vc_sign";
 };
+/**
+ * Classical JOSE signature algorithms currently recognized across GDC VP/JWT
+ * examples and gateway trust adapters.
+ *
+ * Notes:
+ * - `ES256K` is the JOSE name for ECDSA over `secp256k1`
+ * - `ES384` remains the common P-384 legacy example in current GW fixtures
+ */
+export declare const ClassicalJoseSignatureAlgorithms: {
+    readonly Es256: "ES256";
+    readonly Es256K: "ES256K";
+    readonly Es384: "ES384";
+};
+/**
+ * JOSE signature algorithms accepted by shared VP/JWT helpers.
+ *
+ * This intentionally covers both:
+ * - classical ECDSA JOSE algorithms (`ES256`, `ES256K`, `ES384`)
+ * - post-quantum ML-DSA JOSE algorithm labels already used by GW
+ *
+ * Use this type when a helper builds or documents a JWS/JWT/VP proof header.
+ */
+export type JoseSignatureAlgorithm = typeof ClassicalJoseSignatureAlgorithms[keyof typeof ClassicalJoseSignatureAlgorithms] | MldsaAlg;
 /**
  * Default post-quantum signing algorithms used for communication bootstrap.
  */

package/dist/constants/cryptography.js

@@ -15,6 +15,19 @@ export const CommunicationKeyPurposes = {
     CommunicationSignature: 'comm_sig',
     VerifiableCredentialSignature: 'vc_sign',
 };
+/**
+ * Classical JOSE signature algorithms currently recognized across GDC VP/JWT
+ * examples and gateway trust adapters.
+ *
+ * Notes:
+ * - `ES256K` is the JOSE name for ECDSA over `secp256k1`
+ * - `ES384` remains the common P-384 legacy example in current GW fixtures
+ */
+export const ClassicalJoseSignatureAlgorithms = {
+    Es256: 'ES256',
+    Es256K: 'ES256K',
+    Es384: 'ES384',
+};
 /**
  * Default post-quantum signing algorithms used for communication bootstrap.
  */

package/dist/constants/eu-countries.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ISO 3166-1 alpha-2 country codes that currently belong to the European Union.
+ *
+ * This list is intentionally kept in a runtime-neutral shared package because
+ * dataspace discovery may need to infer a broader coverage scope such as `EU`
+ * from the semantic country carried in a VC `credentialSubject`.
+ */
+export declare const EU_COUNTRY_CODES: readonly ["AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE"];
+export type EuCountryCode = typeof EU_COUNTRY_CODES[number];
+/**
+ * Normalizes a country code into canonical uppercase ISO-2 form.
+ *
+ * @param countryCode Country code from `credentialSubject.address.addressCountry`
+ * or the flattened operational projection.
+ * @returns Uppercase ISO-2 form or an empty string when the input is blank.
+ *
+ * @example
+ * ```ts
+ * normalizeCountryCode('es');
+ * // 'ES'
+ * ```
+ */
+export declare function normalizeCountryCode(countryCode: string | undefined | null): string;
+/**
+ * Checks whether the supplied country code belongs to the current EU member set.
+ *
+ * @param countryCode ISO-2 country code to evaluate.
+ * @returns `true` when the normalized code belongs to `EU_COUNTRY_CODES`.
+ *
+ * @example
+ * ```ts
+ * isEuCountryCode('ES');
+ * // true
+ * ```
+ */
+export declare function isEuCountryCode(countryCode: string | undefined | null): boolean;

package/dist/constants/eu-countries.js

@@ -0,0 +1,69 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * ISO 3166-1 alpha-2 country codes that currently belong to the European Union.
+ *
+ * This list is intentionally kept in a runtime-neutral shared package because
+ * dataspace discovery may need to infer a broader coverage scope such as `EU`
+ * from the semantic country carried in a VC `credentialSubject`.
+ */
+export const EU_COUNTRY_CODES = Object.freeze([
+    'AT',
+    'BE',
+    'BG',
+    'HR',
+    'CY',
+    'CZ',
+    'DK',
+    'EE',
+    'FI',
+    'FR',
+    'DE',
+    'GR',
+    'HU',
+    'IE',
+    'IT',
+    'LV',
+    'LT',
+    'LU',
+    'MT',
+    'NL',
+    'PL',
+    'PT',
+    'RO',
+    'SK',
+    'SI',
+    'ES',
+    'SE',
+]);
+/**
+ * Normalizes a country code into canonical uppercase ISO-2 form.
+ *
+ * @param countryCode Country code from `credentialSubject.address.addressCountry`
+ * or the flattened operational projection.
+ * @returns Uppercase ISO-2 form or an empty string when the input is blank.
+ *
+ * @example
+ * ```ts
+ * normalizeCountryCode('es');
+ * // 'ES'
+ * ```
+ */
+export function normalizeCountryCode(countryCode) {
+    return String(countryCode || '').trim().toUpperCase();
+}
+/**
+ * Checks whether the supplied country code belongs to the current EU member set.
+ *
+ * @param countryCode ISO-2 country code to evaluate.
+ * @returns `true` when the normalized code belongs to `EU_COUNTRY_CODES`.
+ *
+ * @example
+ * ```ts
+ * isEuCountryCode('ES');
+ * // true
+ * ```
+ */
+export function isEuCountryCode(countryCode) {
+    const normalized = normalizeCountryCode(countryCode);
+    return normalized ? EU_COUNTRY_CODES.includes(normalized) : false;
+}

package/dist/constants/index.d.ts

@@ -3,6 +3,7 @@ export * from './communication';
 export * from './cryptography';
 export * from './device';
 export * from './did-services';
+export * from './eu-countries';
 export * from './fhir-code-systems';
 export * from './fhir-resource-types';
 export * from './fhir-versions';
@@ -14,4 +15,5 @@ export * from './network';
 export * from './sectors';
 export * from './smart';
 export * from './service-capabilities';
+export * from './urn';
 export * from './verifiable-credentials';

package/dist/constants/index.js

@@ -3,6 +3,7 @@ export * from './communication.js';
 export * from './cryptography.js';
 export * from './device.js';
 export * from './did-services.js';
+export * from './eu-countries.js';
 export * from './fhir-code-systems.js';
 export * from './fhir-resource-types.js';
 export * from './fhir-versions.js';
@@ -14,4 +15,5 @@ export * from './network.js';
 export * from './sectors.js';
 export * from './smart.js';
 export * from './service-capabilities.js';
+export * from './urn.js';
 export * from './verifiable-credentials.js';

package/dist/constants/schemaorg.d.ts

@@ -1,11 +1,35 @@
 import { ParameterData } from "../models/params";
 export declare enum ClaimsServiceSchemaorg {
+    areaServed = "org.schema.Service.areaServed",
     category = "org.schema.Service.category",
     identifier = "org.schema.Service.identifier",
     serviceType = "org.schema.Service.serviceType",
     termsOfService = "org.schema.Service.termsOfService",
     url = "org.schema.Service.url"
 }
+/**
+ * Canonical claim names used by the current GDC profile when a VC models a
+ * `schema.org/SoftwareApplication`.
+ *
+ * Contract note:
+ * - `material` is the public cryptographic material of the software
+ *   application in the current GDC profile, typically the communication
+ *   signing key id bound by ICA to the software/application instance
+ * - when that identifier is expressed as a JWK thumbprint, RFC 7638 defines
+ *   the canonical thumbprint calculation over the public signing /
+ *   verification JWK and RFC 9278 defines the canonical URN form
+ *   `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+ * - the controller-side signature belongs to the prior ICA registration step,
+ *   not to every later app-service operational proof
+ */
+export declare enum ClaimsSoftwareApplicationSchemaorg {
+    id = "org.schema.SoftwareApplication.id",
+    name = "org.schema.SoftwareApplication.name",
+    url = "org.schema.SoftwareApplication.url",
+    sameAs = "org.schema.SoftwareApplication.sameAs",
+    /** Communication signing key id bound by the ICA-issued SoftwareApplication VC. */
+    material = "org.schema.SoftwareApplication.material"
+}
 /**
  * Defines the canonical claim names for the 'org.schema' context,
  * based on Schema.org vocabulary.
@@ -39,6 +63,16 @@ export declare enum ClaimsOrganizationSchemaorg {
     email = "org.schema.Organization.email",
     /** Public contact phone */
     telephone = "org.schema.Organization.telephone",
+    /**
+     * Public cryptographic material of the organization in VC/profile payloads.
+     *
+     * When represented as a JWK thumbprint identifier:
+     * - RFC 7638 defines the canonical thumbprint calculation over the public
+     *   signing / verification JWK
+     * - RFC 9278 defines the canonical URN form
+     *   `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+     */
+    hasCredentialMaterial = "org.schema.Organization.hasCredential.material",
     /** Individual/family owner email used by subject-index registration flows. */
     ownerEmail = "org.schema.Organization.owner.email",
     /** Individual/family owner telephone used by subject-index registration flows. */

package/dist/constants/schemaorg.js

@@ -2,12 +2,37 @@
 // File: src/models/schemaorg.ts
 export var ClaimsServiceSchemaorg;
 (function (ClaimsServiceSchemaorg) {
+    ClaimsServiceSchemaorg["areaServed"] = "org.schema.Service.areaServed";
     ClaimsServiceSchemaorg["category"] = "org.schema.Service.category";
     ClaimsServiceSchemaorg["identifier"] = "org.schema.Service.identifier";
     ClaimsServiceSchemaorg["serviceType"] = "org.schema.Service.serviceType";
     ClaimsServiceSchemaorg["termsOfService"] = "org.schema.Service.termsOfService";
     ClaimsServiceSchemaorg["url"] = "org.schema.Service.url";
 })(ClaimsServiceSchemaorg || (ClaimsServiceSchemaorg = {}));
+/**
+ * Canonical claim names used by the current GDC profile when a VC models a
+ * `schema.org/SoftwareApplication`.
+ *
+ * Contract note:
+ * - `material` is the public cryptographic material of the software
+ *   application in the current GDC profile, typically the communication
+ *   signing key id bound by ICA to the software/application instance
+ * - when that identifier is expressed as a JWK thumbprint, RFC 7638 defines
+ *   the canonical thumbprint calculation over the public signing /
+ *   verification JWK and RFC 9278 defines the canonical URN form
+ *   `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+ * - the controller-side signature belongs to the prior ICA registration step,
+ *   not to every later app-service operational proof
+ */
+export var ClaimsSoftwareApplicationSchemaorg;
+(function (ClaimsSoftwareApplicationSchemaorg) {
+    ClaimsSoftwareApplicationSchemaorg["id"] = "org.schema.SoftwareApplication.id";
+    ClaimsSoftwareApplicationSchemaorg["name"] = "org.schema.SoftwareApplication.name";
+    ClaimsSoftwareApplicationSchemaorg["url"] = "org.schema.SoftwareApplication.url";
+    ClaimsSoftwareApplicationSchemaorg["sameAs"] = "org.schema.SoftwareApplication.sameAs";
+    /** Communication signing key id bound by the ICA-issued SoftwareApplication VC. */
+    ClaimsSoftwareApplicationSchemaorg["material"] = "org.schema.SoftwareApplication.material";
+})(ClaimsSoftwareApplicationSchemaorg || (ClaimsSoftwareApplicationSchemaorg = {}));
 /**
  * Defines the canonical claim names for the 'org.schema' context,
  * based on Schema.org vocabulary.
@@ -42,6 +67,16 @@ export var ClaimsOrganizationSchemaorg;
     ClaimsOrganizationSchemaorg["email"] = "org.schema.Organization.email";
     /** Public contact phone */
     ClaimsOrganizationSchemaorg["telephone"] = "org.schema.Organization.telephone";
+    /**
+     * Public cryptographic material of the organization in VC/profile payloads.
+     *
+     * When represented as a JWK thumbprint identifier:
+     * - RFC 7638 defines the canonical thumbprint calculation over the public
+     *   signing / verification JWK
+     * - RFC 9278 defines the canonical URN form
+     *   `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+     */
+    ClaimsOrganizationSchemaorg["hasCredentialMaterial"] = "org.schema.Organization.hasCredential.material";
     /** Individual/family owner email used by subject-index registration flows. */
     ClaimsOrganizationSchemaorg["ownerEmail"] = "org.schema.Organization.owner.email";
     /** Individual/family owner telephone used by subject-index registration flows. */

package/dist/constants/service-capabilities.d.ts

@@ -75,3 +75,8 @@ export declare function getServiceCapabilityFamily(value: string | undefined): s
  * family.
  */
 export declare function hasServiceCapabilityFamily(value: unknown, family: ServiceCapabilityFamilyValue | string): boolean;
+/**
+ * Returns whether a capability token denotes a discoverable provider/service
+ * role rather than a reader-only role.
+ */
+export declare function isProviderServiceCapability(value: string | undefined | null): boolean;

package/dist/constants/service-capabilities.js

@@ -94,3 +94,12 @@ export function hasServiceCapabilityFamily(value, family) {
         return false;
     return parseServiceCapabilityTokens(value).some((item) => getServiceCapabilityFamily(item) === normalizedFamily);
 }
+/**
+ * Returns whether a capability token denotes a discoverable provider/service
+ * role rather than a reader-only role.
+ */
+export function isProviderServiceCapability(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    return normalized === ServiceCapabilityToken.IndexProvider
+        || normalized === ServiceCapabilityToken.DigitalTwinProvider;
+}

package/dist/constants/urn.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Canonical URN prefixes reused across bootstrap and proof examples.
+ *
+ * The JWK thumbprint URI prefix below follows RFC 9278 and is intended for
+ * cases where a key identifier is represented as a normalized URI instead of
+ * as a bare base64url thumbprint value.
+ */
+export declare const UrnPrefixes: Readonly<{
+    readonly JwkThumbprintSha256KeyId: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:";
+}>;
+export type UrnPrefix = typeof UrnPrefixes[keyof typeof UrnPrefixes];

package/dist/constants/urn.js

@@ -0,0 +1,11 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Canonical URN prefixes reused across bootstrap and proof examples.
+ *
+ * The JWK thumbprint URI prefix below follows RFC 9278 and is intended for
+ * cases where a key identifier is represented as a normalized URI instead of
+ * as a bare base64url thumbprint value.
+ */
+export const UrnPrefixes = Object.freeze({
+    JwkThumbprintSha256KeyId: 'urn:ietf:params:oauth:jwk-thumbprint:sha-256:',
+});

package/dist/examples/dataspace-discovery.d.ts

@@ -0,0 +1,88 @@
+import type { HostingOperatorDiscoveryCatalog, PublishedProviderCatalogRecord } from '../models/dataspace-discovery';
+export type ExampleDataspaceCredentialSubjectInput = Readonly<{
+    did?: string;
+    serviceTypes?: readonly string[];
+    categories?: readonly string[];
+    areaServed?: readonly string[];
+    addressCountry?: string;
+}>;
+/**
+ * Builds a synthetic hosting-operator semantic `credentialSubject`.
+ *
+ * This example is parameterized on purpose: public docs/tests must not hardcode
+ * business identities when demonstrating dataspace discovery semantics.
+ *
+ * @param input Optional overrides for the synthetic subject.
+ * @returns Schema.org-shaped semantic subject with service metadata.
+ */
+export declare function buildExampleHostingOperatorCredentialSubject(input?: ExampleDataspaceCredentialSubjectInput): {
+    id: string;
+    serviceType: string;
+    category: string;
+    areaServed: {
+        '@type': string;
+        name: string;
+    }[];
+    address: {
+        addressCountry: string;
+    };
+};
+/**
+ * Builds a synthetic tenant-service semantic `credentialSubject`.
+ *
+ * @param input Optional overrides for the synthetic tenant subject.
+ * @returns Schema.org-shaped semantic subject with public service metadata.
+ */
+export declare function buildExampleTenantServiceCredentialSubject(input?: ExampleDataspaceCredentialSubjectInput): {
+    id: string;
+    serviceType: string;
+    category: string;
+    areaServed: {
+        '@type': string;
+        name: string;
+    }[];
+    address: {
+        addressCountry: string;
+    };
+};
+/**
+ * Builds the flattened `meta.claims` projection for a hosting-operator semantic
+ * subject.
+ *
+ * @param input Optional overrides for the synthetic projection.
+ * @returns Flat operational claims derived from the semantic subject.
+ */
+export declare function buildExampleHostingOperatorMetaClaims(input?: ExampleDataspaceCredentialSubjectInput): {
+    "org.schema.Service.serviceType": string | undefined;
+    "org.schema.Service.category": string;
+    "org.schema.Service.areaServed": string;
+    "org.schema.Organization.address.addressCountry": string;
+};
+/**
+ * Builds the flattened `meta.claims` projection for a tenant-service semantic
+ * subject.
+ *
+ * @param input Optional overrides for the synthetic projection.
+ * @returns Flat operational claims derived from the semantic subject.
+ */
+export declare function buildExampleTenantServiceMetaClaims(input?: ExampleDataspaceCredentialSubjectInput): {
+    "org.schema.Service.serviceType": string | undefined;
+    "org.schema.Service.category": string;
+    "org.schema.Service.areaServed": string;
+    "org.schema.Organization.address.addressCountry": string;
+};
+/**
+ * Builds a synthetic published-provider record as it would appear in a host
+ * service-autodiscovery catalog.
+ *
+ * @param input Optional overrides for the synthetic provider publication.
+ * @returns Shared host-catalog provider entry.
+ */
+export declare function buildExamplePublishedProviderCatalogRecord(input?: ExampleDataspaceCredentialSubjectInput): PublishedProviderCatalogRecord;
+/**
+ * Builds a synthetic host/operator service-autodiscovery catalog.
+ *
+ * @param providers Optional published providers to include.
+ * @returns Shared catalog DTO for host-side public service autodiscovery.
+ */
+export declare function buildExampleHostingOperatorDiscoveryCatalog(providers?: ReadonlyArray<PublishedProviderCatalogRecord>): HostingOperatorDiscoveryCatalog;

package/dist/examples/dataspace-discovery.js

@@ -0,0 +1,129 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { ClaimsOrganizationSchemaorg, ClaimsServiceSchemaorg } from '../constants/schemaorg.js';
+import { serializeServiceCapabilityTokens, ServiceCapabilityToken } from '../constants/service-capabilities.js';
+import { EXAMPLE_HOSTING_OPERATOR_CATALOG_URL, EXAMPLE_HOSTING_OPERATOR_DID, EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL, EXAMPLE_JURISDICTION, EXAMPLE_SECTOR, EXAMPLE_TENANT_SERVICE_DID, } from './shared.js';
+function firstOrCsv(values) {
+    return values.length <= 1 ? (values[0] || '') : values.join(',');
+}
+/**
+ * Builds a synthetic hosting-operator semantic `credentialSubject`.
+ *
+ * This example is parameterized on purpose: public docs/tests must not hardcode
+ * business identities when demonstrating dataspace discovery semantics.
+ *
+ * @param input Optional overrides for the synthetic subject.
+ * @returns Schema.org-shaped semantic subject with service metadata.
+ */
+export function buildExampleHostingOperatorCredentialSubject(input = {}) {
+    const serviceTypes = input.serviceTypes || [
+        ServiceCapabilityToken.IndexProvider,
+        ServiceCapabilityToken.DigitalTwinProvider,
+    ];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU', EXAMPLE_JURISDICTION];
+    const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
+    return {
+        id: input.did || 'did:web:host.example.org',
+        serviceType: firstOrCsv(serviceTypes),
+        category: firstOrCsv(categories),
+        areaServed: areaServed.map((name) => ({ '@type': 'AdministrativeArea', name })),
+        address: {
+            addressCountry,
+        },
+    };
+}
+/**
+ * Builds a synthetic tenant-service semantic `credentialSubject`.
+ *
+ * @param input Optional overrides for the synthetic tenant subject.
+ * @returns Schema.org-shaped semantic subject with public service metadata.
+ */
+export function buildExampleTenantServiceCredentialSubject(input = {}) {
+    const serviceTypes = input.serviceTypes || [ServiceCapabilityToken.IndexProvider];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU'];
+    const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
+    return {
+        id: input.did || 'did:web:provider.example.org',
+        serviceType: firstOrCsv(serviceTypes),
+        category: firstOrCsv(categories),
+        areaServed: areaServed.map((name) => ({ '@type': 'AdministrativeArea', name })),
+        address: {
+            addressCountry,
+        },
+    };
+}
+/**
+ * Builds the flattened `meta.claims` projection for a hosting-operator semantic
+ * subject.
+ *
+ * @param input Optional overrides for the synthetic projection.
+ * @returns Flat operational claims derived from the semantic subject.
+ */
+export function buildExampleHostingOperatorMetaClaims(input = {}) {
+    const serviceTypes = input.serviceTypes || [
+        ServiceCapabilityToken.IndexProvider,
+        ServiceCapabilityToken.DigitalTwinProvider,
+    ];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU', EXAMPLE_JURISDICTION];
+    const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
+    return {
+        [ClaimsServiceSchemaorg.serviceType]: serializeServiceCapabilityTokens(serviceTypes),
+        [ClaimsServiceSchemaorg.category]: firstOrCsv(categories),
+        [ClaimsServiceSchemaorg.areaServed]: firstOrCsv(areaServed),
+        [ClaimsOrganizationSchemaorg.addressCountry]: addressCountry,
+    };
+}
+/**
+ * Builds the flattened `meta.claims` projection for a tenant-service semantic
+ * subject.
+ *
+ * @param input Optional overrides for the synthetic projection.
+ * @returns Flat operational claims derived from the semantic subject.
+ */
+export function buildExampleTenantServiceMetaClaims(input = {}) {
+    const serviceTypes = input.serviceTypes || [ServiceCapabilityToken.IndexProvider];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU'];
+    const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
+    return {
+        [ClaimsServiceSchemaorg.serviceType]: serializeServiceCapabilityTokens(serviceTypes),
+        [ClaimsServiceSchemaorg.category]: firstOrCsv(categories),
+        [ClaimsServiceSchemaorg.areaServed]: firstOrCsv(areaServed),
+        [ClaimsOrganizationSchemaorg.addressCountry]: addressCountry,
+    };
+}
+/**
+ * Builds a synthetic published-provider record as it would appear in a host
+ * service-autodiscovery catalog.
+ *
+ * @param input Optional overrides for the synthetic provider publication.
+ * @returns Shared host-catalog provider entry.
+ */
+export function buildExamplePublishedProviderCatalogRecord(input = {}) {
+    const serviceTypes = input.serviceTypes || [ServiceCapabilityToken.IndexProvider];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU'];
+    return {
+        providerDid: input.did || EXAMPLE_TENANT_SERVICE_DID,
+        serviceType: serviceTypes[0] || ServiceCapabilityToken.IndexProvider,
+        category: categories[0] || EXAMPLE_SECTOR,
+        areaServed: areaServed[0] || 'EU',
+        endpointUrl: EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL,
+        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_URL,
+    };
+}
+/**
+ * Builds a synthetic host/operator service-autodiscovery catalog.
+ *
+ * @param providers Optional published providers to include.
+ * @returns Shared catalog DTO for host-side public service autodiscovery.
+ */
+export function buildExampleHostingOperatorDiscoveryCatalog(providers = [buildExamplePublishedProviderCatalogRecord()]) {
+    return {
+        hostingOperatorDid: EXAMPLE_HOSTING_OPERATOR_DID,
+        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_URL,
+        providers: [...providers],
+    };
+}

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

@@ -2,33 +2,42 @@
  * Shared synthetic ICA activation-proof fixtures reused by docs/tests.
  *
  * Contract note:
- * - issuer/holder/audience DIDs, VC subtype names, and representative binding
- *   fields must be imported from this module instead of re-hardcoded inline
+ * - 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
+ *
+ * Modeling note:
+ * - this onboarding example intentionally anchors the business subject on the
+ *   organization tax ID rather than on a pre-existing provider DID
+ * - the VP envelope uses a synthetic RFC 7638-style JWK-thumbprint urn and a
+ *   host id, which better matches the initial registration stage than a
+ *   synthetic did:web
+ */
+/**
+ * Synthetic JWK-thumbprint-based signing key id for the organization
+ * controller who signs the initial legal-onboarding VP.
  */
-export declare const EXAMPLE_ICA_VP_ISSUER_DID: "did:web:controller.example.org";
-export declare const EXAMPLE_ICA_VP_AUDIENCE_DID: "did:web:host.example.com";
-export declare const EXAMPLE_ICA_VP_HOLDER_DID: "did:web:controller.example.org";
-export declare const EXAMPLE_ICA_ORGANIZATION_DID: "did:web:org.example.org";
-export declare const EXAMPLE_ICA_REPRESENTATIVE_DID: "did:web:rep.example.org";
-export declare const EXAMPLE_ICA_ORGANIZATION_TAX_ID: "ESB00112233";
-export declare const EXAMPLE_ICA_REPRESENTATIVE_ROLE_CODE: "RESPRSN";
-export declare const EXAMPLE_ICA_REPRESENTATIVE_BINDING_MATERIAL: "controller-sig-kid";
-export declare const EXAMPLE_ICA_ORGANIZATION_CREDENTIAL: Readonly<{
+export declare const EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+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_ORGANIZATION_ID: "ESB00112233";
+export declare const EXAMPLE_ORG_ACTIVATION_ORGANIZATION_CREDENTIAL: Readonly<{
     '@context': string[];
     type: ("VerifiableCredential" | "OrganizationCredential")[];
     credentialSubject: {
-        id: "did:web:org.example.org";
+        id: "ESB00112233";
         taxID: "ESB00112233";
     };
 }>;
-export declare const EXAMPLE_ICA_LEGAL_REPRESENTATIVE_CREDENTIAL: Readonly<{
+export declare const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL: Readonly<{
     '@context': string[];
     type: ("VerifiableCredential" | "LegalRepresentativeCredential")[];
     credentialSubject: {
-        id: "did:web:rep.example.org";
+        id: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
         memberOf: {
             taxID: "ESB00112233";
         };
@@ -38,18 +47,18 @@ export declare const EXAMPLE_ICA_LEGAL_REPRESENTATIVE_CREDENTIAL: Readonly<{
             };
         };
         hasCredential: {
-            material: "controller-sig-kid";
+            material: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
         };
     };
 }>;
-export declare const EXAMPLE_ICA_ACTIVATION_VP_PAYLOAD: Readonly<{
-    iss: "did:web:controller.example.org";
-    sub: "did:web:controller.example.org";
-    aud: "did:web:host.example.com";
+export declare const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD: Readonly<{
+    iss: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+    sub: "ESB00112233";
+    aud: "host:node-operator-es";
     vp: {
         '@context': "https://www.w3.org/2018/credentials/v1"[];
         type: "VerifiablePresentation"[];
-        holder: "did:web:controller.example.org";
+        holder: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
         verifiableCredential: string[];
     };
 }>;