gdc-common-utils-ts 1.11.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/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';

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';

package/dist/constants/schemaorg.d.ts

@@ -1,5 +1,6 @@
 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",

package/dist/constants/schemaorg.js

@@ -2,6 +2,7 @@
 // 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";

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/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/index.d.ts

@@ -1,5 +1,6 @@
 export * from './shared';
 export * from './ica-activation-proof';
+export * from './dataspace-discovery';
 export * from './organization-controller';
 export * from './individual-controller';
 export * from './professional';

package/dist/examples/index.js

@@ -1,5 +1,6 @@
 export * from './shared.js';
 export * from './ica-activation-proof.js';
+export * from './dataspace-discovery.js';
 export * from './organization-controller.js';
 export * from './individual-controller.js';
 export * from './professional.js';

package/dist/examples/shared.d.ts

@@ -31,6 +31,19 @@ export declare const EXAMPLE_SUBJECT_DID: "did:web:api.acme.org:individual:123";
 export declare const EXAMPLE_PROFESSIONAL_DID: "did:web:api.acme.org:professional:1";
 export declare const EXAMPLE_PROVIDER_ORGANIZATION_DID: "did:web:hospital.acme.org";
 export declare const EXAMPLE_PROVIDER_ORGANIZATION_URL: "https://hospital.acme.org";
+export declare const EXAMPLE_GATEWAY_PUBLIC_ORIGIN: "https://gateway.example.com";
+export declare const EXAMPLE_HOST_PUBLIC_HOSTNAME: "host.example.com";
+export declare const EXAMPLE_HOSTING_OPERATOR_DID: "did:web:host.example.org";
+export declare const EXAMPLE_TENANT_SERVICE_DID: "did:web:provider.example.org";
+export declare const EXAMPLE_SECONDARY_TENANT_SERVICE_DID: "did:web:provider-b.example.org";
+export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL: "https://host.example.org/.well-known/dcat3/catalog";
+export declare const EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL: "https://host.example.org/catalog/provider-a";
+export declare const EXAMPLE_PROVIDER_LEGAL_NAME: "ACME Health Provider";
+export declare const EXAMPLE_SECONDARY_PROVIDER_LEGAL_NAME: "Reader Only Provider";
+export declare const EXAMPLE_SECONDARY_PROVIDER_ALTERNATE_NAME: "reader-only";
+export declare const EXAMPLE_COVERAGE_SCOPE_EU: "EU";
+export declare const EXAMPLE_NON_EU_COUNTRY: "US";
+export declare const EXAMPLE_SECONDARY_EU_COUNTRY: "PT";
 export declare const EXAMPLE_PATIENT_DID: "did:web:patient.example";
 export declare const EXAMPLE_PROFILE_PROVIDER_DID: "did:web:provider.example.org";
 export declare const EXAMPLE_PROFILE_ORGANIZATION_DID: "did:web:org.example";
@@ -183,3 +196,10 @@ export declare function buildExampleDocumentReferenceSearchPayload(subjectDid?:
     };
 };
 export declare function cloneExample<T>(value: T): T;
+export type ExampleHostedTenantRouteContext = Readonly<{
+    alternateName: string;
+    jurisdiction: string;
+    version: string;
+    sector: string;
+}>;
+export declare function buildExampleHostedTenantBaseUrl(input: ExampleHostedTenantRouteContext): string;

package/dist/examples/shared.js

@@ -36,6 +36,19 @@ export const EXAMPLE_SUBJECT_DID = 'did:web:api.acme.org:individual:123';
 export const EXAMPLE_PROFESSIONAL_DID = 'did:web:api.acme.org:professional:1';
 export const EXAMPLE_PROVIDER_ORGANIZATION_DID = 'did:web:hospital.acme.org';
 export const EXAMPLE_PROVIDER_ORGANIZATION_URL = 'https://hospital.acme.org';
+export const EXAMPLE_GATEWAY_PUBLIC_ORIGIN = 'https://gateway.example.com';
+export const EXAMPLE_HOST_PUBLIC_HOSTNAME = 'host.example.com';
+export const EXAMPLE_HOSTING_OPERATOR_DID = 'did:web:host.example.org';
+export const EXAMPLE_TENANT_SERVICE_DID = 'did:web:provider.example.org';
+export const EXAMPLE_SECONDARY_TENANT_SERVICE_DID = 'did:web:provider-b.example.org';
+export const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL = 'https://host.example.org/.well-known/dcat3/catalog';
+export const EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL = 'https://host.example.org/catalog/provider-a';
+export const EXAMPLE_PROVIDER_LEGAL_NAME = 'ACME Health Provider';
+export const EXAMPLE_SECONDARY_PROVIDER_LEGAL_NAME = 'Reader Only Provider';
+export const EXAMPLE_SECONDARY_PROVIDER_ALTERNATE_NAME = 'reader-only';
+export const EXAMPLE_COVERAGE_SCOPE_EU = 'EU';
+export const EXAMPLE_NON_EU_COUNTRY = 'US';
+export const EXAMPLE_SECONDARY_EU_COUNTRY = 'PT';
 export const EXAMPLE_PATIENT_DID = 'did:web:patient.example';
 export const EXAMPLE_PROFILE_PROVIDER_DID = 'did:web:provider.example.org';
 export const EXAMPLE_PROFILE_ORGANIZATION_DID = 'did:web:org.example';
@@ -157,3 +170,6 @@ export function buildExampleDocumentReferenceSearchPayload(subjectDid = EXAMPLE_
 export function cloneExample(value) {
     return JSON.parse(JSON.stringify(value));
 }
+export function buildExampleHostedTenantBaseUrl(input) {
+    return `${EXAMPLE_GATEWAY_PUBLIC_ORIGIN}/${input.alternateName}/cds-${input.jurisdiction.toLowerCase()}/${input.version}/${input.sector}`;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Canonical shared coverage scopes derived from semantic service metadata.
+ *
+ * `EU` is a coverage scope, not a sector.
+ */
+export declare const DataspaceCoverageScope: {
+    readonly EuropeanUnion: "EU";
+};
+export type DataspaceCoverageScopeValue = typeof DataspaceCoverageScope[keyof typeof DataspaceCoverageScope];
+/**
+ * Runtime-neutral service-discovery record normalized from a semantic
+ * `credentialSubject` and optionally its flattened `meta.claims` projection.
+ */
+export type DataspaceServiceSemanticRecord = Readonly<{
+    subjectId?: string;
+    serviceTypes: string[];
+    categories: string[];
+    areaServed: string[];
+    addressCountry?: string;
+    coverageScope?: string;
+}>;
+/**
+ * Semantic hosting-operator record extracted from an ICA-issued VC or
+ * equivalent semantic payload.
+ */
+export type HostingOperatorSemanticRecord = DataspaceServiceSemanticRecord;
+/**
+ * Semantic tenant-service record extracted from an ICA-issued VC or equivalent
+ * semantic payload.
+ */
+export type TenantServiceSemanticRecord = DataspaceServiceSemanticRecord;
+/**
+ * Public provider entry expected from a host discovery catalog.
+ */
+export type PublishedProviderCatalogRecord = Readonly<{
+    providerDid: string;
+    serviceType: string;
+    category: string;
+    areaServed?: string;
+    endpointUrl?: string;
+    catalogUrl?: string;
+}>;
+/**
+ * Shared host-catalog filter for service autodiscovery.
+ *
+ * This shape is runtime-neutral and can be reused by GW, ICA, backend SDKs,
+ * and portal/native-app backends.
+ */
+export type DataspaceDiscoveryFilter = Readonly<{
+    sector: string;
+    capability?: string;
+    requiredCapabilities?: readonly string[];
+    jurisdiction?: string;
+    coverageScope?: string;
+}>;
+/**
+ * Public host/operator service-autodiscovery catalog.
+ *
+ * This is distinct from any dataset-specific catalog exposed by an individual
+ * `DigitalTwinProvider`.
+ */
+export type HostingOperatorDiscoveryCatalog = Readonly<{
+    hostingOperatorDid?: string;
+    catalogUrl?: string;
+    providers: PublishedProviderCatalogRecord[];
+}>;

package/dist/models/dataspace-discovery.js

@@ -0,0 +1,9 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Canonical shared coverage scopes derived from semantic service metadata.
+ *
+ * `EU` is a coverage scope, not a sector.
+ */
+export const DataspaceCoverageScope = {
+    EuropeanUnion: 'EU',
+};

package/dist/models/index.d.ts

@@ -12,6 +12,7 @@ export * from './confidential-storage';
 export * from './consent-rule';
 export * from './consent-access';
 export * from './crypto';
+export * from './dataspace-discovery';
 export * from './device-license';
 export * from './did';
 export * from './fhir-documents';

package/dist/models/index.js

@@ -12,6 +12,7 @@ export * from './confidential-storage.js';
 export * from './consent-rule.js';
 export * from './consent-access.js';
 export * from './crypto.js';
+export * from './dataspace-discovery.js';
 export * from './device-license.js';
 export * from './did.js';
 export * from './fhir-documents.js';

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

@@ -0,0 +1,146 @@
+import { type DataspaceDiscoveryFilter, type DataspaceServiceSemanticRecord, type HostingOperatorSemanticRecord, type HostingOperatorDiscoveryCatalog, type PublishedProviderCatalogRecord, type TenantServiceSemanticRecord } from '../models/dataspace-discovery';
+/**
+ * Parses the CSV or array representation of `serviceType`.
+ *
+ * @param value Semantic `credentialSubject.serviceType` or flattened
+ * `meta.claims['org.schema.Service.serviceType']`.
+ * @returns Normalized unique service capability tokens.
+ *
+ * @example
+ * ```ts
+ * parseServiceTypeCsv('indexing.cruds,digitaltwin.rs');
+ * // ['indexing.cruds', 'digitaltwin.rs']
+ * ```
+ */
+export declare function parseServiceTypeCsv(value: unknown): string[];
+/**
+ * Parses the Schema.org `category` service dimension used as the dataspace
+ * sector vocabulary in the current profile.
+ *
+ * @param value Semantic `credentialSubject.category` or flattened
+ * `meta.claims['org.schema.Service.category']`.
+ * @returns Normalized unique sector/category values.
+ *
+ * @example
+ * ```ts
+ * parseServiceCategories('animal-care,health-care');
+ * // ['animal-care', 'health-care']
+ * ```
+ */
+export declare function parseServiceCategories(value: unknown): string[];
+/**
+ * Parses Schema.org `areaServed` values.
+ *
+ * Accepts scalar strings, CSV strings, arrays, and simple
+ * `AdministrativeArea`-like objects with `name` or `@id`.
+ *
+ * @param value Semantic `credentialSubject.areaServed` or flattened
+ * `meta.claims['org.schema.Service.areaServed']`.
+ * @returns Normalized unique coverage values.
+ *
+ * @example
+ * ```ts
+ * parseAreaServed([{ '@type': 'AdministrativeArea', name: 'EU' }, 'ES']);
+ * // ['EU', 'ES']
+ * ```
+ */
+export declare function parseAreaServed(value: unknown): string[];
+/**
+ * Infers a broader coverage scope from an ISO-2 country code.
+ *
+ * `EU` is returned only as a coverage scope. It must not be treated as a
+ * sector.
+ *
+ * @param countryCode ISO-2 country code, typically from
+ * `credentialSubject.address.addressCountry`.
+ * @returns `EU` for EU member countries, otherwise the normalized country code.
+ *
+ * @example
+ * ```ts
+ * inferCoverageScopeFromCountryCode('ES');
+ * // 'EU'
+ * ```
+ */
+export declare function inferCoverageScopeFromCountryCode(countryCode: string | undefined | null): string | undefined;
+/**
+ * Infers a coverage scope from the semantic `credentialSubject`.
+ *
+ * @param subject Semantic service object containing `address.addressCountry`.
+ * @returns Broader coverage scope such as `EU`, or the normalized country code
+ * when the country is outside the EU set.
+ */
+export declare function inferCoverageScopeFromCredentialSubject(subject: unknown): string | undefined;
+/**
+ * Extracts the shared dataspace service semantics from a VC-like payload.
+ *
+ * Source-of-truth rule:
+ * - semantic values come from `credentialSubject` first
+ * - flattened `meta.claims` is accepted as a compatibility projection/fallback
+ * - when both exist they must agree
+ *
+ * @param input VC-like payload, direct semantic object, or equivalent DTO.
+ * @returns Runtime-neutral normalized dataspace discovery semantics.
+ *
+ * @example
+ * ```ts
+ * extractDataspaceServiceSemanticRecord({
+ *   credentialSubject: {
+ *     id: 'did:web:provider.example.org',
+ *     serviceType: 'indexing.cruds',
+ *     category: 'animal-care',
+ *     areaServed: { '@type': 'AdministrativeArea', name: 'EU' },
+ *     address: { addressCountry: 'ES' },
+ *   },
+ *   meta: {
+ *     claims: {
+ *       'org.schema.Service.serviceType': 'indexing.cruds',
+ *       'org.schema.Service.category': 'animal-care',
+ *       'org.schema.Service.areaServed': 'EU',
+ *       'org.schema.Organization.address.addressCountry': 'ES',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function extractDataspaceServiceSemanticRecord(input: unknown): DataspaceServiceSemanticRecord;
+/**
+ * Extracts a hosting-operator semantic record from a VC-like payload.
+ *
+ * @param input VC-like payload or direct semantic object.
+ * @returns Hosting-operator semantic record normalized with the common
+ * dataspace extraction rules.
+ */
+export declare function extractHostingOperatorSemanticRecord(input: unknown): HostingOperatorSemanticRecord;
+/**
+ * Extracts a tenant-service semantic record from a VC-like payload.
+ *
+ * @param input VC-like payload or direct semantic object.
+ * @returns Tenant-service semantic record normalized with the common dataspace
+ * extraction rules.
+ */
+export declare function extractTenantServiceSemanticRecord(input: unknown): TenantServiceSemanticRecord;
+/**
+ * Returns whether a normalized hosting-operator record satisfies a service
+ * autodiscovery filter.
+ */
+export declare function matchesHostingOperatorDiscoveryFilter(record: HostingOperatorSemanticRecord, filter: DataspaceDiscoveryFilter): boolean;
+/**
+ * Returns whether a published provider catalog entry satisfies a service
+ * autodiscovery filter.
+ */
+export declare function matchesPublishedProviderDiscoveryFilter(record: PublishedProviderCatalogRecord, filter: DataspaceDiscoveryFilter): boolean;
+/**
+ * Filters hosting-operator records using the shared service-autodiscovery
+ * semantics.
+ */
+export declare function filterHostingOperatorsByDiscoveryFilter(records: ReadonlyArray<HostingOperatorSemanticRecord>, filter: DataspaceDiscoveryFilter): HostingOperatorSemanticRecord[];
+/**
+ * Filters published provider entries using the shared service-autodiscovery
+ * semantics.
+ */
+export declare function filterPublishedProvidersByDiscoveryFilter(records: ReadonlyArray<PublishedProviderCatalogRecord>, filter: DataspaceDiscoveryFilter): PublishedProviderCatalogRecord[];
+/**
+ * Filters a host/operator discovery catalog down to the providers that satisfy
+ * the requested service-autodiscovery filter.
+ */
+export declare function filterHostingOperatorDiscoveryCatalog(catalog: HostingOperatorDiscoveryCatalog, filter: DataspaceDiscoveryFilter): HostingOperatorDiscoveryCatalog;

package/dist/utils/dataspace-discovery.js

@@ -0,0 +1,341 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { ClaimsOrganizationSchemaorg, ClaimsServiceSchemaorg } from '../constants/schemaorg.js';
+import { isEuCountryCode, normalizeCountryCode } from '../constants/eu-countries.js';
+import { isProviderServiceCapability } from '../constants/service-capabilities.js';
+import { DataspaceCoverageScope, } from '../models/dataspace-discovery.js';
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function asNonEmptyString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function toStringList(value) {
+    if (Array.isArray(value)) {
+        return Array.from(new Set(value
+            .flatMap((entry) => toStringList(entry))
+            .map((entry) => entry.trim())
+            .filter(Boolean)));
+    }
+    const raw = asNonEmptyString(value);
+    if (!raw)
+        return [];
+    return Array.from(new Set(raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean)));
+}
+function normalizeList(values) {
+    return Array.from(new Set(values
+        .map((value) => value.trim())
+        .filter(Boolean)));
+}
+function sameNormalizedList(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const normalizedLeft = [...normalizeList(left)].sort();
+    const normalizedRight = [...normalizeList(right)].sort();
+    return normalizedLeft.every((value, index) => value === normalizedRight[index]);
+}
+function parseAreaServedValue(value) {
+    if (Array.isArray(value)) {
+        return normalizeList(value.flatMap((entry) => parseAreaServedValue(entry)));
+    }
+    if (typeof value === 'string') {
+        return toStringList(value);
+    }
+    const objectValue = asObject(value);
+    if (!objectValue)
+        return [];
+    return normalizeList([
+        asNonEmptyString(objectValue.name),
+        asNonEmptyString(objectValue['@id']),
+        asNonEmptyString(objectValue.id),
+    ].filter(Boolean));
+}
+function getSemanticCredentialSubject(input) {
+    const objectInput = asObject(input);
+    if (!objectInput)
+        return undefined;
+    const credentialSubject = asObject(objectInput.credentialSubject);
+    if (credentialSubject)
+        return credentialSubject;
+    return objectInput;
+}
+function getFlattenedClaims(input) {
+    const objectInput = asObject(input);
+    if (!objectInput)
+        return undefined;
+    const meta = asObject(objectInput.meta);
+    const claims = asObject(meta?.claims);
+    return claims;
+}
+function getSemanticServiceTypes(subject) {
+    return toStringList(subject?.serviceType);
+}
+function getSemanticCategories(subject) {
+    return toStringList(subject?.category);
+}
+function getSemanticAreaServed(subject) {
+    return parseAreaServedValue(subject?.areaServed);
+}
+function getSemanticAddressCountry(subject) {
+    const address = asObject(subject?.address);
+    return normalizeCountryCode(asNonEmptyString(address?.addressCountry));
+}
+function getFlattenedServiceTypes(claims) {
+    return toStringList(claims?.[ClaimsServiceSchemaorg.serviceType]);
+}
+function getFlattenedCategories(claims) {
+    return toStringList(claims?.[ClaimsServiceSchemaorg.category]);
+}
+function getFlattenedAreaServed(claims) {
+    return parseAreaServedValue(claims?.[ClaimsServiceSchemaorg.areaServed]);
+}
+function getFlattenedAddressCountry(claims) {
+    return normalizeCountryCode(asNonEmptyString(claims?.[ClaimsOrganizationSchemaorg.addressCountry]));
+}
+function assertNoMismatch(kind, semantic, flattened) {
+    if (!semantic.length || !flattened.length)
+        return;
+    if (!sameNormalizedList(semantic, flattened)) {
+        throw new Error(`Dataspace discovery mismatch for ${kind}: credentialSubject and meta.claims disagree.`);
+    }
+}
+function assertNoScalarMismatch(kind, semantic, flattened) {
+    if (!semantic || !flattened)
+        return;
+    if (semantic !== flattened) {
+        throw new Error(`Dataspace discovery mismatch for ${kind}: credentialSubject and meta.claims disagree.`);
+    }
+}
+/**
+ * Parses the CSV or array representation of `serviceType`.
+ *
+ * @param value Semantic `credentialSubject.serviceType` or flattened
+ * `meta.claims['org.schema.Service.serviceType']`.
+ * @returns Normalized unique service capability tokens.
+ *
+ * @example
+ * ```ts
+ * parseServiceTypeCsv('indexing.cruds,digitaltwin.rs');
+ * // ['indexing.cruds', 'digitaltwin.rs']
+ * ```
+ */
+export function parseServiceTypeCsv(value) {
+    return toStringList(value);
+}
+/**
+ * Parses the Schema.org `category` service dimension used as the dataspace
+ * sector vocabulary in the current profile.
+ *
+ * @param value Semantic `credentialSubject.category` or flattened
+ * `meta.claims['org.schema.Service.category']`.
+ * @returns Normalized unique sector/category values.
+ *
+ * @example
+ * ```ts
+ * parseServiceCategories('animal-care,health-care');
+ * // ['animal-care', 'health-care']
+ * ```
+ */
+export function parseServiceCategories(value) {
+    return toStringList(value);
+}
+/**
+ * Parses Schema.org `areaServed` values.
+ *
+ * Accepts scalar strings, CSV strings, arrays, and simple
+ * `AdministrativeArea`-like objects with `name` or `@id`.
+ *
+ * @param value Semantic `credentialSubject.areaServed` or flattened
+ * `meta.claims['org.schema.Service.areaServed']`.
+ * @returns Normalized unique coverage values.
+ *
+ * @example
+ * ```ts
+ * parseAreaServed([{ '@type': 'AdministrativeArea', name: 'EU' }, 'ES']);
+ * // ['EU', 'ES']
+ * ```
+ */
+export function parseAreaServed(value) {
+    return parseAreaServedValue(value);
+}
+/**
+ * Infers a broader coverage scope from an ISO-2 country code.
+ *
+ * `EU` is returned only as a coverage scope. It must not be treated as a
+ * sector.
+ *
+ * @param countryCode ISO-2 country code, typically from
+ * `credentialSubject.address.addressCountry`.
+ * @returns `EU` for EU member countries, otherwise the normalized country code.
+ *
+ * @example
+ * ```ts
+ * inferCoverageScopeFromCountryCode('ES');
+ * // 'EU'
+ * ```
+ */
+export function inferCoverageScopeFromCountryCode(countryCode) {
+    const normalized = normalizeCountryCode(countryCode);
+    if (!normalized)
+        return undefined;
+    return isEuCountryCode(normalized)
+        ? DataspaceCoverageScope.EuropeanUnion
+        : normalized;
+}
+/**
+ * Infers a coverage scope from the semantic `credentialSubject`.
+ *
+ * @param subject Semantic service object containing `address.addressCountry`.
+ * @returns Broader coverage scope such as `EU`, or the normalized country code
+ * when the country is outside the EU set.
+ */
+export function inferCoverageScopeFromCredentialSubject(subject) {
+    const subjectObject = asObject(subject);
+    const address = asObject(subjectObject?.address);
+    return inferCoverageScopeFromCountryCode(asNonEmptyString(address?.addressCountry));
+}
+/**
+ * Extracts the shared dataspace service semantics from a VC-like payload.
+ *
+ * Source-of-truth rule:
+ * - semantic values come from `credentialSubject` first
+ * - flattened `meta.claims` is accepted as a compatibility projection/fallback
+ * - when both exist they must agree
+ *
+ * @param input VC-like payload, direct semantic object, or equivalent DTO.
+ * @returns Runtime-neutral normalized dataspace discovery semantics.
+ *
+ * @example
+ * ```ts
+ * extractDataspaceServiceSemanticRecord({
+ *   credentialSubject: {
+ *     id: 'did:web:provider.example.org',
+ *     serviceType: 'indexing.cruds',
+ *     category: 'animal-care',
+ *     areaServed: { '@type': 'AdministrativeArea', name: 'EU' },
+ *     address: { addressCountry: 'ES' },
+ *   },
+ *   meta: {
+ *     claims: {
+ *       'org.schema.Service.serviceType': 'indexing.cruds',
+ *       'org.schema.Service.category': 'animal-care',
+ *       'org.schema.Service.areaServed': 'EU',
+ *       'org.schema.Organization.address.addressCountry': 'ES',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function extractDataspaceServiceSemanticRecord(input) {
+    const subject = getSemanticCredentialSubject(input);
+    const claims = getFlattenedClaims(input);
+    const semanticServiceTypes = getSemanticServiceTypes(subject);
+    const semanticCategories = getSemanticCategories(subject);
+    const semanticAreaServed = getSemanticAreaServed(subject);
+    const semanticAddressCountry = getSemanticAddressCountry(subject);
+    const flattenedServiceTypes = getFlattenedServiceTypes(claims);
+    const flattenedCategories = getFlattenedCategories(claims);
+    const flattenedAreaServed = getFlattenedAreaServed(claims);
+    const flattenedAddressCountry = getFlattenedAddressCountry(claims);
+    assertNoMismatch('serviceType', semanticServiceTypes, flattenedServiceTypes);
+    assertNoMismatch('category', semanticCategories, flattenedCategories);
+    assertNoMismatch('areaServed', semanticAreaServed, flattenedAreaServed);
+    assertNoScalarMismatch('address.addressCountry', semanticAddressCountry, flattenedAddressCountry);
+    const serviceTypes = semanticServiceTypes.length ? semanticServiceTypes : flattenedServiceTypes;
+    const categories = semanticCategories.length ? semanticCategories : flattenedCategories;
+    const areaServed = semanticAreaServed.length ? semanticAreaServed : flattenedAreaServed;
+    const addressCountry = semanticAddressCountry || flattenedAddressCountry || undefined;
+    return {
+        subjectId: asNonEmptyString(subject?.id) || undefined,
+        serviceTypes,
+        categories,
+        areaServed,
+        addressCountry,
+        coverageScope: inferCoverageScopeFromCountryCode(addressCountry),
+    };
+}
+/**
+ * Extracts a hosting-operator semantic record from a VC-like payload.
+ *
+ * @param input VC-like payload or direct semantic object.
+ * @returns Hosting-operator semantic record normalized with the common
+ * dataspace extraction rules.
+ */
+export function extractHostingOperatorSemanticRecord(input) {
+    return extractDataspaceServiceSemanticRecord(input);
+}
+/**
+ * Extracts a tenant-service semantic record from a VC-like payload.
+ *
+ * @param input VC-like payload or direct semantic object.
+ * @returns Tenant-service semantic record normalized with the common dataspace
+ * extraction rules.
+ */
+export function extractTenantServiceSemanticRecord(input) {
+    return extractDataspaceServiceSemanticRecord(input);
+}
+function matchesCoverageFilter(areaServed, jurisdiction, coverageScope) {
+    const normalizedAreaServed = normalizeList([...(areaServed || [])]);
+    if (jurisdiction && !normalizedAreaServed.includes(jurisdiction))
+        return false;
+    if (coverageScope && !normalizedAreaServed.includes(coverageScope))
+        return false;
+    return true;
+}
+/**
+ * Returns whether a normalized hosting-operator record satisfies a service
+ * autodiscovery filter.
+ */
+export function matchesHostingOperatorDiscoveryFilter(record, filter) {
+    if (!record.categories.includes(filter.sector))
+        return false;
+    if (!matchesCoverageFilter(record.areaServed, filter.jurisdiction, filter.coverageScope))
+        return false;
+    if (filter.capability && !record.serviceTypes.includes(filter.capability))
+        return false;
+    if (filter.requiredCapabilities?.length) {
+        return filter.requiredCapabilities.every((capability) => record.serviceTypes.includes(capability));
+    }
+    return true;
+}
+/**
+ * Returns whether a published provider catalog entry satisfies a service
+ * autodiscovery filter.
+ */
+export function matchesPublishedProviderDiscoveryFilter(record, filter) {
+    if (!isProviderServiceCapability(record.serviceType))
+        return false;
+    if (record.category !== filter.sector)
+        return false;
+    if (filter.capability && record.serviceType !== filter.capability)
+        return false;
+    return matchesCoverageFilter(record.areaServed ? [record.areaServed] : [], filter.jurisdiction, filter.coverageScope);
+}
+/**
+ * Filters hosting-operator records using the shared service-autodiscovery
+ * semantics.
+ */
+export function filterHostingOperatorsByDiscoveryFilter(records, filter) {
+    return records.filter((record) => matchesHostingOperatorDiscoveryFilter(record, filter));
+}
+/**
+ * Filters published provider entries using the shared service-autodiscovery
+ * semantics.
+ */
+export function filterPublishedProvidersByDiscoveryFilter(records, filter) {
+    return records.filter((record) => matchesPublishedProviderDiscoveryFilter(record, filter));
+}
+/**
+ * Filters a host/operator discovery catalog down to the providers that satisfy
+ * the requested service-autodiscovery filter.
+ */
+export function filterHostingOperatorDiscoveryCatalog(catalog, filter) {
+    return {
+        ...catalog,
+        providers: filterPublishedProvidersByDiscoveryFilter(catalog.providers, filter),
+    };
+}

package/dist/utils/index.d.ts

@@ -7,6 +7,7 @@ export * from './content';
 export * from './consent';
 export * from './did';
 export * from './did-resolution';
+export * from './dataspace-discovery';
 export * from './didcomm';
 export * from './didcomm-submit';
 export * from './didcomm-submit-policy';

package/dist/utils/index.js

@@ -7,6 +7,7 @@ export * from './content.js';
 export * from './consent.js';
 export * from './did.js';
 export * from './did-resolution.js';
+export * from './dataspace-discovery.js';
 export * from './didcomm.js';
 export * from './didcomm-submit.js';
 export * from './didcomm-submit-policy.js';

package/package.json

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