gdc-common-utils-ts 1.12.0 → 1.14.0

package/README.md

@@ -89,9 +89,68 @@ import { JweObject, JwtCompactParts } from 'gdc-common-utils-ts/models';
 - [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/DATASPACE_DISCOVERY_DEFAULTS_101.md](docs/DATASPACE_DISCOVERY_DEFAULTS_101.md)
+  - portal/backend bootstrap guide for `defaults-only`, `default-first`, and
+    `internet-first` discovery seeding by `jurisdiction + version + networkType`
 - [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
 
+## Dataspace Protocol And Discovery
+
+Use `gdc-common-utils-ts` as the shared source of truth for DSP route building,
+`dspace-version` metadata, and normalized discovery DTOs.
+
+Main entry points:
+
+- [`src/utils/dataspace-protocol.ts`](src/utils/dataspace-protocol.ts)
+  - canonical GW CORE path builders for host-scoped and tenant-scoped DSP
+    routes
+- [`src/utils/dataspace-discovery.ts`](src/utils/dataspace-discovery.ts)
+  - semantic extraction, provider filtering, default DTO builders, and the
+    copy/paste fetcher harness used by docs/tests
+- [`src/utils/dataspace-discovery-defaults.ts`](src/utils/dataspace-discovery-defaults.ts)
+  - defaults registry for ICAs and hosting operators plus the backend
+    `default-first` bootstrap plan used to unblock portal integration
+- [`src/examples/dataspace-discovery.ts`](src/examples/dataspace-discovery.ts)
+  - synthetic provider/operator examples that distinguish discovery URL from
+    derived catalog artifact URL
+- [`docs/DATASPACE_DISCOVERY_DEFAULTS_101.md`](docs/DATASPACE_DISCOVERY_DEFAULTS_101.md)
+  - copy/paste backend bootstrap guide for portal `default-first` rollout
+- [`__tests__/dataspace-discovery-defaults.101.test.ts`](__tests__/dataspace-discovery-defaults.101.test.ts)
+  - executable defaults-registry examples for ICAs, hosting operators, and
+    source-mode behavior
+- [`__tests__/dataspace-protocol.test.ts`](__tests__/dataspace-protocol.test.ts)
+  - executable path and `dspace-version` examples
+- [`__tests__/dataspace-discovery.test.ts`](__tests__/dataspace-discovery.test.ts)
+  - executable semantic extraction and filtering examples
+
+Copy/paste example:
+
+```ts
+import {
+  buildDspaceVersionMetadata,
+  buildGwCatalogArtifactPath,
+  buildGwDspaceVersionWellKnownPath,
+  deriveGwCatalogArtifactUrlFromDspaceVersion,
+} from 'gdc-common-utils-ts/utils/dataspace-protocol';
+import { HostNetworkTypes } from 'gdc-common-utils-ts/constants/network';
+
+const hostContext = {
+  participantId: 'host',
+  jurisdiction: 'ES',
+  version: 'v1',
+  hostNetwork: HostNetworkTypes.Test,
+};
+
+const discoveryPath = buildGwDspaceVersionWellKnownPath(hostContext);
+const metadata = buildDspaceVersionMetadata('/host/cds-ES/v1/test/dsp');
+const catalogPath = buildGwCatalogArtifactPath(hostContext);
+const catalogUrl = deriveGwCatalogArtifactUrlFromDspaceVersion(
+  `https://host.example.org${discoveryPath}`,
+  metadata,
+);
+```
+
 ## API Index
 
 The canonical API contract should live in JSDoc on exported code. The README acts as a navigable index.
@@ -116,8 +175,8 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - Reusable professional role/permission examples tying actor role, consent action, SMART scope, and expected FHIR resource types together.
 - [`DeviceUserClasses`, `DeviceAppTypes`](src/constants/device.ts)
   - Shared user-class and app/device-type constants used by licensing and SDK flows.
-- [`NodeOperatorNetworkTypes`](src/constants/network.ts)
-  - Shared network/environment labels for node-operator discovery/bootstrap.
+- [`HostNetworkTypes`](src/constants/network.ts)
+  - Shared network/environment labels for host discovery/bootstrap.
 - [`SmartGatewayScopesFhirR4`](src/constants/smart.ts)
   - Current CORE GW SMART scope literals such as `organization/Consent.cruds`.
   - Treat these as optional elevated scopes. Do not add them to the first read-only tutorial by default.

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

@@ -0,0 +1,11 @@
+/**
+ * Shared discovery-source policies used by backend/bootstrap layers that must
+ * decide whether to start from configured defaults or from live internet/ICA
+ * discovery.
+ */
+export declare const DataspaceDiscoverySourceMode: Readonly<{
+    readonly DefaultFirst: "default-first";
+    readonly DefaultsOnly: "defaults-only";
+    readonly InternetFirst: "internet-first";
+}>;
+export type DataspaceDiscoverySourceModeValue = typeof DataspaceDiscoverySourceMode[keyof typeof DataspaceDiscoverySourceMode];

package/dist/constants/dataspace-discovery.js

@@ -0,0 +1,11 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Shared discovery-source policies used by backend/bootstrap layers that must
+ * decide whether to start from configured defaults or from live internet/ICA
+ * discovery.
+ */
+export const DataspaceDiscoverySourceMode = Object.freeze({
+    DefaultFirst: 'default-first',
+    DefaultsOnly: 'defaults-only',
+    InternetFirst: 'internet-first',
+});

package/dist/constants/dataspace-protocol.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical Dataspace Protocol version identifiers used by the current GW/SDK
+ * discovery flows.
+ */
+export declare const DataspaceProtocolVersions: Readonly<{
+    readonly Current: "2025-1";
+}>;
+/**
+ * Canonical well-known paths used by Dataspace Protocol discovery.
+ */
+export declare const DataspaceWellKnownPaths: Readonly<{
+    readonly VersionMetadata: "/.well-known/dspace-version";
+}>;
+/**
+ * Project-local GW CORE DSP binding paths.
+ *
+ * These preserve the current internal API structure while still ending in the
+ * DSP catalog route shapes.
+ */
+export declare const GwDataspaceBindingPaths: Readonly<{
+    readonly Base: "/dsp";
+    readonly CatalogCollectionSuffix: "/catalog";
+    readonly CatalogRequestSuffix: "/catalog/request";
+    readonly CatalogArtifactSuffix: "/catalog/dcat.json";
+    readonly CatalogDatasetsPrefix: "/catalog/datasets";
+}>;
+export type DataspaceProtocolVersionValue = typeof DataspaceProtocolVersions[keyof typeof DataspaceProtocolVersions];

package/dist/constants/dataspace-protocol.js

@@ -0,0 +1,27 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Canonical Dataspace Protocol version identifiers used by the current GW/SDK
+ * discovery flows.
+ */
+export const DataspaceProtocolVersions = Object.freeze({
+    Current: '2025-1',
+});
+/**
+ * Canonical well-known paths used by Dataspace Protocol discovery.
+ */
+export const DataspaceWellKnownPaths = Object.freeze({
+    VersionMetadata: '/.well-known/dspace-version',
+});
+/**
+ * Project-local GW CORE DSP binding paths.
+ *
+ * These preserve the current internal API structure while still ending in the
+ * DSP catalog route shapes.
+ */
+export const GwDataspaceBindingPaths = Object.freeze({
+    Base: '/dsp',
+    CatalogCollectionSuffix: '/catalog',
+    CatalogRequestSuffix: '/catalog/request',
+    CatalogArtifactSuffix: '/catalog/dcat.json',
+    CatalogDatasetsPrefix: '/catalog/datasets',
+});

package/dist/constants/index.d.ts

@@ -1,6 +1,8 @@
 export * from './actor-session';
 export * from './communication';
 export * from './cryptography';
+export * from './dataspace-discovery';
+export * from './dataspace-protocol';
 export * from './device';
 export * from './did-services';
 export * from './eu-countries';

package/dist/constants/index.js

@@ -1,6 +1,8 @@
 export * from './actor-session.js';
 export * from './communication.js';
 export * from './cryptography.js';
+export * from './dataspace-discovery.js';
+export * from './dataspace-protocol.js';
 export * from './device.js';
 export * from './did-services.js';
 export * from './eu-countries.js';

package/dist/constants/network.d.ts

@@ -1,13 +1,25 @@
 /**
- * Canonical network/environment labels used to identify node-operator networks
- * during discovery/bootstrap flows.
+ * Canonical network/environment labels used to identify host networks during
+ * discovery/bootstrap flows.
  *
- * These labels do not replace the clinical route `sector`. They describe the
- * operator environment itself.
+ * These labels do not replace the business route `sector`. They describe the
+ * host environment itself.
+ */
+export declare const HostNetworkTypes: Readonly<{
+    readonly Test: "test";
+    readonly TestNetwork: "test-network";
+    readonly Network: "network";
+}>;
+export type HostNetworkType = typeof HostNetworkTypes[keyof typeof HostNetworkTypes];
+/**
+ * @deprecated Use `HostNetworkTypes`.
  */
 export declare const NodeOperatorNetworkTypes: Readonly<{
     readonly Test: "test";
     readonly TestNetwork: "test-network";
     readonly Network: "network";
 }>;
-export type NodeOperatorNetworkType = typeof NodeOperatorNetworkTypes[keyof typeof NodeOperatorNetworkTypes];
+/**
+ * @deprecated Use `HostNetworkType`.
+ */
+export type NodeOperatorNetworkType = HostNetworkType;

package/dist/constants/network.js

@@ -1,13 +1,17 @@
 // Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
 /**
- * Canonical network/environment labels used to identify node-operator networks
- * during discovery/bootstrap flows.
+ * Canonical network/environment labels used to identify host networks during
+ * discovery/bootstrap flows.
  *
- * These labels do not replace the clinical route `sector`. They describe the
- * operator environment itself.
+ * These labels do not replace the business route `sector`. They describe the
+ * host environment itself.
  */
-export const NodeOperatorNetworkTypes = Object.freeze({
+export const HostNetworkTypes = Object.freeze({
     Test: 'test',
     TestNetwork: 'test-network',
     Network: 'network',
 });
+/**
+ * @deprecated Use `HostNetworkTypes`.
+ */
+export const NodeOperatorNetworkTypes = HostNetworkTypes;

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

@@ -75,6 +75,11 @@ export declare function buildExampleTenantServiceMetaClaims(input?: ExampleDatas
  * Builds a synthetic published-provider record as it would appear in a host
  * service-autodiscovery catalog.
  *
+ * URL rule:
+ * - `discoveryUrl` is the participant-scoped `/.well-known/dspace-version`
+ *   entrypoint
+ * - `catalogUrl` is the derived `/dsp/catalog/dcat.json` artifact
+ *
  * @param input Optional overrides for the synthetic provider publication.
  * @returns Shared host-catalog provider entry.
  */
@@ -82,6 +87,11 @@ export declare function buildExamplePublishedProviderCatalogRecord(input?: Examp
 /**
  * Builds a synthetic host/operator service-autodiscovery catalog.
  *
+ * URL rule:
+ * - `discoveryUrl` is the canonical entrypoint clients should fetch first
+ * - `catalogUrl` is the read-only DSP artifact derived from the advertised
+ *   base path
+ *
  * @param providers Optional published providers to include.
  * @returns Shared catalog DTO for host-side public service autodiscovery.
  */

package/dist/examples/dataspace-discovery.js

@@ -1,7 +1,7 @@
 // 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';
+import { EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL, EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_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(',');
 }
@@ -98,6 +98,11 @@ export function buildExampleTenantServiceMetaClaims(input = {}) {
  * Builds a synthetic published-provider record as it would appear in a host
  * service-autodiscovery catalog.
  *
+ * URL rule:
+ * - `discoveryUrl` is the participant-scoped `/.well-known/dspace-version`
+ *   entrypoint
+ * - `catalogUrl` is the derived `/dsp/catalog/dcat.json` artifact
+ *
  * @param input Optional overrides for the synthetic provider publication.
  * @returns Shared host-catalog provider entry.
  */
@@ -109,21 +114,28 @@ export function buildExamplePublishedProviderCatalogRecord(input = {}) {
         providerDid: input.did || EXAMPLE_TENANT_SERVICE_DID,
         serviceType: serviceTypes[0] || ServiceCapabilityToken.IndexProvider,
         category: categories[0] || EXAMPLE_SECTOR,
-        areaServed: areaServed[0] || 'EU',
+        areaServed: firstOrCsv(areaServed) || 'EU',
         endpointUrl: EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL,
-        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_URL,
+        discoveryUrl: EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL,
+        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL,
     };
 }
 /**
  * Builds a synthetic host/operator service-autodiscovery catalog.
  *
+ * URL rule:
+ * - `discoveryUrl` is the canonical entrypoint clients should fetch first
+ * - `catalogUrl` is the read-only DSP artifact derived from the advertised
+ *   base path
+ *
  * @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,
+        discoveryUrl: EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL,
+        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL,
         providers: [...providers],
     };
 }

package/dist/examples/shared.d.ts

@@ -10,6 +10,8 @@
  */
 export declare const EXAMPLE_TENANT_IDENTIFIER: "acme-id";
 export declare const EXAMPLE_JURISDICTION: "ES";
+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_EMAIL_CONTROLLER_INDIVIDUAL: "ana.parent@example.org";
@@ -20,7 +22,7 @@ export declare const EXAMPLE_TENANT_ROUTE_CONTEXT: {
 };
 export declare const EXAMPLE_HOST_ROUTE_CONTEXT: {
     readonly jurisdiction: "ES";
-    readonly sector: "health-care";
+    readonly sector: "test";
 };
 export declare const EXAMPLE_CONTROLLER_DID: "did:web:people.acme.org:controllers:primary";
 export declare const EXAMPLE_CONTROLLER_EMAIL: "controller@acme.org";
@@ -33,10 +35,15 @@ export declare const EXAMPLE_PROVIDER_ORGANIZATION_DID: "did:web:hospital.acme.o
 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_DEFAULT_ICA_URL: "https://ica.example.org";
+export declare const EXAMPLE_DEFAULT_ICA_DID: "did:web:ica.example.org";
 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_HOSTING_OPERATOR_DSPACE_VERSION_URL: "https://host.example.org/host/cds-ES/v1/test/.well-known/dspace-version";
+export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL: "https://host.example.org/host/cds-ES/v1/test/dsp/catalog/dcat.json";
+/** @deprecated Use `EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL`. */
+export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL: "https://host.example.org/host/cds-ES/v1/test/.well-known/dspace-version";
 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";

package/dist/examples/shared.js

@@ -1,6 +1,7 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 // Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 import { DataspaceSectors } from '../constants/sectors.js';
+import { HostNetworkTypes } from '../constants/network.js';
 import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, } from '../constants/healthcare.js';
 import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
 /**
@@ -15,6 +16,8 @@ import { CommunicationClaim } from '../models/interoperable-claims/communication
  */
 export const EXAMPLE_TENANT_IDENTIFIER = 'acme-id';
 export const EXAMPLE_JURISDICTION = 'ES';
+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_EMAIL_CONTROLLER_INDIVIDUAL = 'ana.parent@example.org';
@@ -25,7 +28,7 @@ export const EXAMPLE_TENANT_ROUTE_CONTEXT = {
 };
 export const EXAMPLE_HOST_ROUTE_CONTEXT = {
     jurisdiction: EXAMPLE_JURISDICTION,
-    sector: EXAMPLE_SECTOR,
+    sector: HostNetworkTypes.Test,
 };
 export const EXAMPLE_CONTROLLER_DID = 'did:web:people.acme.org:controllers:primary';
 export const EXAMPLE_CONTROLLER_EMAIL = EXAMPLE_EMAIL_CONTROLLER_ORG;
@@ -38,10 +41,15 @@ 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_DEFAULT_ICA_URL = 'https://ica.example.org';
+export const EXAMPLE_DEFAULT_ICA_DID = 'did:web:ica.example.org';
 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_HOSTING_OPERATOR_DSPACE_VERSION_URL = `https://host.example.org/host/cds-ES/${EXAMPLE_ROUTE_VERSION}/${EXAMPLE_NETWORK_TYPE}/.well-known/dspace-version`;
+export const EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL = `https://host.example.org/host/cds-ES/${EXAMPLE_ROUTE_VERSION}/${EXAMPLE_NETWORK_TYPE}/dsp/catalog/dcat.json`;
+/** @deprecated Use `EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL`. */
+export const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL = EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL;
 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';

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

@@ -0,0 +1,78 @@
+import type { DataspaceDiscoverySourceModeValue } from '../constants/dataspace-discovery';
+import type { HostingOperatorSemanticRecord } from './dataspace-discovery';
+/**
+ * Shared host/ICA context used to select dataspace discovery defaults.
+ *
+ * `networkType` belongs to the host/ICA side.
+ * Tenant/provider resolution later uses `sector`.
+ */
+export type DataspaceDiscoveryNetworkContext = Readonly<{
+    jurisdiction: string;
+    version: string;
+    networkType: string;
+}>;
+/**
+ * Configured ICA seed for a given host/network context.
+ */
+export type DefaultIcaRegistration = DataspaceDiscoveryNetworkContext & Readonly<{
+    icaUrl: string;
+    icaDid?: string;
+    title?: string;
+}>;
+/**
+ * Configured hosting-operator seed for a given host/network context.
+ *
+ * This mirrors the record shape consumed later by backend resolvers.
+ */
+export type DefaultHostingOperatorRegistration = DataspaceDiscoveryNetworkContext & Readonly<{
+    operatorDid: string;
+    discoveryUrl?: string;
+    catalogUrl?: string;
+    record: HostingOperatorSemanticRecord;
+    title?: string;
+}>;
+/**
+ * Optional seed data used when constructing a defaults registry.
+ */
+export type DataspaceDiscoveryDefaultsRegistrySeed = Readonly<{
+    icas?: readonly DefaultIcaRegistration[];
+    hostingOperators?: readonly DefaultHostingOperatorRegistration[];
+}>;
+/**
+ * Filter used to list configured ICA defaults for a host/network context.
+ */
+export type DataspaceDiscoveryDefaultIcaFilter = Readonly<Partial<DataspaceDiscoveryNetworkContext>>;
+/**
+ * Filter used to list configured hosting-operator defaults for a discovery
+ * request.
+ */
+export type DataspaceDiscoveryDefaultHostingFilter = Readonly<Partial<DataspaceDiscoveryNetworkContext> & {
+    sector?: string;
+    coverageScope?: string;
+    requiredCapabilities?: readonly string[];
+}>;
+/**
+ * Input used to decide how a backend should bootstrap discovery for a
+ * frontend/API request.
+ */
+export type DataspaceDiscoveryBootstrapInput = DataspaceDiscoveryNetworkContext & Readonly<{
+    sector: string;
+    coverageScope?: string;
+    requiredCapabilities?: readonly string[];
+    sourceMode?: DataspaceDiscoverySourceModeValue;
+}>;
+/**
+ * Bootstrap plan returned by the defaults registry.
+ *
+ * Backend usage:
+ * - use `hostingOperators` immediately when `shouldUseDefaultsFirst` is true
+ * - try live ICA/internet only when `shouldTryInternet` is true
+ */
+export type DataspaceDiscoveryBootstrapPlan = Readonly<{
+    sourceMode: DataspaceDiscoverySourceModeValue;
+    icas: DefaultIcaRegistration[];
+    hostingOperators: DefaultHostingOperatorRegistration[];
+    hasDefaults: boolean;
+    shouldUseDefaultsFirst: boolean;
+    shouldTryInternet: boolean;
+}>;

package/dist/models/dataspace-discovery-defaults.js

@@ -0,0 +1,2 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+export {};

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

@@ -38,6 +38,7 @@ export type PublishedProviderCatalogRecord = Readonly<{
     category: string;
     areaServed?: string;
     endpointUrl?: string;
+    discoveryUrl?: string;
     catalogUrl?: string;
 }>;
 /**
@@ -61,6 +62,7 @@ export type DataspaceDiscoveryFilter = Readonly<{
  */
 export type HostingOperatorDiscoveryCatalog = Readonly<{
     hostingOperatorDid?: string;
+    discoveryUrl?: string;
     catalogUrl?: string;
     providers: PublishedProviderCatalogRecord[];
 }>;

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

@@ -0,0 +1,14 @@
+/**
+ * One advertised Dataspace Protocol version entry from `/.well-known/dspace-version`.
+ */
+export type DspaceProtocolVersionEntry = Readonly<{
+    version: string;
+    path: string;
+}>;
+/**
+ * Minimal version metadata payload returned by the DSP well-known discovery
+ * endpoint.
+ */
+export type DspaceVersionMetadata = Readonly<{
+    protocolVersions: readonly DspaceProtocolVersionEntry[];
+}>;

package/dist/models/dataspace-protocol.js

@@ -0,0 +1,2 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+export {};

package/dist/models/index.d.ts

@@ -13,6 +13,8 @@ export * from './consent-rule';
 export * from './consent-access';
 export * from './crypto';
 export * from './dataspace-discovery';
+export * from './dataspace-discovery-defaults';
+export * from './dataspace-protocol';
 export * from './device-license';
 export * from './did';
 export * from './fhir-documents';

package/dist/models/index.js

@@ -13,6 +13,8 @@ export * from './consent-rule.js';
 export * from './consent-access.js';
 export * from './crypto.js';
 export * from './dataspace-discovery.js';
+export * from './dataspace-discovery-defaults.js';
+export * from './dataspace-protocol.js';
 export * from './device-license.js';
 export * from './did.js';
 export * from './fhir-documents.js';

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

@@ -0,0 +1,66 @@
+import type { DataspaceDiscoveryBootstrapInput, DataspaceDiscoveryBootstrapPlan, DataspaceDiscoveryDefaultHostingFilter, DataspaceDiscoveryDefaultIcaFilter, DataspaceDiscoveryDefaultsRegistrySeed, DefaultHostingOperatorRegistration, DefaultIcaRegistration } from '../models/dataspace-discovery-defaults';
+/**
+ * Mutable in-memory registry for discovery defaults used by portal/backend
+ * bootstrap code.
+ *
+ * Scope:
+ * - ICA defaults are indexed by `jurisdiction + version + networkType`
+ * - hosting defaults are indexed by `jurisdiction + version + networkType`
+ * - sector filtering is applied only when listing hosting operators, because
+ *   sectors belong to tenant/provider discovery rather than to the host network
+ *
+ * This registry is intentionally simple and synchronous so backend code can
+ * preload defaults during startup and immediately serve the frontend in
+ * `defaults-only` or `default-first` mode.
+ */
+export declare class DataspaceDiscoveryDefaultsRegistry {
+    private readonly icas;
+    private readonly hostingOperators;
+    constructor(seed?: DataspaceDiscoveryDefaultsRegistrySeed);
+    /**
+     * Adds one ICA default for a concrete host/network context.
+     *
+     * @example
+     * ```ts
+     * registry.addIca({
+     *   jurisdiction: 'ES',
+     *   version: 'v1',
+     *   networkType: 'test',
+     *   icaUrl: 'https://ica.example.org',
+     * });
+     * ```
+     */
+    addIca(input: DefaultIcaRegistration): this;
+    /**
+     * Adds one hosting-operator default for a concrete host/network context.
+     *
+     * The record itself may later serve multiple sectors depending on the
+     * semantic categories and capabilities published in `record`.
+     */
+    addHostingOperator(input: DefaultHostingOperatorRegistration): this;
+    /**
+     * Lists configured ICA defaults for a host/network context.
+     */
+    listIcas(filter?: DataspaceDiscoveryDefaultIcaFilter): DefaultIcaRegistration[];
+    /**
+     * Lists configured hosting-operator defaults for a frontend/backend discovery
+     * request.
+     *
+     * Sector and capability filtering are applied against the semantic host
+     * record because those dimensions belong to the provider/tenant side.
+     */
+    listHostingOperators(filter?: DataspaceDiscoveryDefaultHostingFilter): DefaultHostingOperatorRegistration[];
+    /**
+     * Builds the backend bootstrap plan for one provider-discovery request.
+     *
+     * Current default-first policy:
+     * - use configured hosting defaults immediately when they exist
+     * - only try live ICA/internet when no host defaults match the request and at
+     *   least one ICA default is configured for the same host/network context
+     */
+    buildBootstrapPlan(input: DataspaceDiscoveryBootstrapInput): DataspaceDiscoveryBootstrapPlan;
+}
+/**
+ * Convenience factory for the in-memory defaults registry.
+ */
+export declare function createDataspaceDiscoveryDefaultsRegistry(seed?: DataspaceDiscoveryDefaultsRegistrySeed): DataspaceDiscoveryDefaultsRegistry;

package/dist/utils/dataspace-discovery-defaults.js

@@ -0,0 +1,172 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { DataspaceDiscoverySourceMode, } from '../constants/dataspace-discovery.js';
+import { matchesHostingOperatorDiscoveryFilter } from './dataspace-discovery.js';
+function normalizeString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function normalizeCapabilities(values) {
+    return Array.from(new Set((values || []).map((value) => normalizeString(value)).filter(Boolean)));
+}
+function normalizeIcaRegistration(input) {
+    return {
+        jurisdiction: normalizeString(input.jurisdiction),
+        version: normalizeString(input.version),
+        networkType: normalizeString(input.networkType),
+        icaUrl: normalizeString(input.icaUrl),
+        icaDid: normalizeString(input.icaDid) || undefined,
+        title: normalizeString(input.title) || undefined,
+    };
+}
+function normalizeHostingOperatorRegistration(input) {
+    return {
+        jurisdiction: normalizeString(input.jurisdiction),
+        version: normalizeString(input.version),
+        networkType: normalizeString(input.networkType),
+        operatorDid: normalizeString(input.operatorDid),
+        discoveryUrl: normalizeString(input.discoveryUrl) || undefined,
+        catalogUrl: normalizeString(input.catalogUrl) || undefined,
+        record: {
+            ...input.record,
+            subjectId: normalizeString(input.record.subjectId) || undefined,
+            serviceTypes: normalizeCapabilities(input.record.serviceTypes),
+            categories: Array.from(new Set((input.record.categories || []).map((value) => normalizeString(value)).filter(Boolean))),
+            areaServed: Array.from(new Set((input.record.areaServed || []).map((value) => normalizeString(value)).filter(Boolean))),
+            addressCountry: normalizeString(input.record.addressCountry) || undefined,
+            coverageScope: normalizeString(input.record.coverageScope) || undefined,
+        },
+        title: normalizeString(input.title) || undefined,
+    };
+}
+function matchesNetworkContext(left, right) {
+    if (right.jurisdiction && normalizeString(right.jurisdiction) !== left.jurisdiction)
+        return false;
+    if (right.version && normalizeString(right.version) !== left.version)
+        return false;
+    if (right.networkType && normalizeString(right.networkType) !== left.networkType)
+        return false;
+    return true;
+}
+/**
+ * Mutable in-memory registry for discovery defaults used by portal/backend
+ * bootstrap code.
+ *
+ * Scope:
+ * - ICA defaults are indexed by `jurisdiction + version + networkType`
+ * - hosting defaults are indexed by `jurisdiction + version + networkType`
+ * - sector filtering is applied only when listing hosting operators, because
+ *   sectors belong to tenant/provider discovery rather than to the host network
+ *
+ * This registry is intentionally simple and synchronous so backend code can
+ * preload defaults during startup and immediately serve the frontend in
+ * `defaults-only` or `default-first` mode.
+ */
+export class DataspaceDiscoveryDefaultsRegistry {
+    icas = [];
+    hostingOperators = [];
+    constructor(seed = {}) {
+        for (const registration of seed.icas || []) {
+            this.addIca(registration);
+        }
+        for (const registration of seed.hostingOperators || []) {
+            this.addHostingOperator(registration);
+        }
+    }
+    /**
+     * Adds one ICA default for a concrete host/network context.
+     *
+     * @example
+     * ```ts
+     * registry.addIca({
+     *   jurisdiction: 'ES',
+     *   version: 'v1',
+     *   networkType: 'test',
+     *   icaUrl: 'https://ica.example.org',
+     * });
+     * ```
+     */
+    addIca(input) {
+        this.icas.push(normalizeIcaRegistration(input));
+        return this;
+    }
+    /**
+     * Adds one hosting-operator default for a concrete host/network context.
+     *
+     * The record itself may later serve multiple sectors depending on the
+     * semantic categories and capabilities published in `record`.
+     */
+    addHostingOperator(input) {
+        this.hostingOperators.push(normalizeHostingOperatorRegistration(input));
+        return this;
+    }
+    /**
+     * Lists configured ICA defaults for a host/network context.
+     */
+    listIcas(filter = {}) {
+        return this.icas
+            .filter((registration) => matchesNetworkContext(registration, filter))
+            .map((registration) => ({ ...registration }));
+    }
+    /**
+     * Lists configured hosting-operator defaults for a frontend/backend discovery
+     * request.
+     *
+     * Sector and capability filtering are applied against the semantic host
+     * record because those dimensions belong to the provider/tenant side.
+     */
+    listHostingOperators(filter = {}) {
+        return this.hostingOperators
+            .filter((registration) => matchesNetworkContext(registration, filter))
+            .filter((registration) => {
+            if (!filter.sector)
+                return true;
+            return matchesHostingOperatorDiscoveryFilter(registration.record, {
+                sector: normalizeString(filter.sector),
+                coverageScope: normalizeString(filter.coverageScope) || undefined,
+                requiredCapabilities: normalizeCapabilities(filter.requiredCapabilities),
+            });
+        })
+            .map((registration) => ({
+            ...registration,
+            record: {
+                ...registration.record,
+                serviceTypes: [...registration.record.serviceTypes],
+                categories: [...registration.record.categories],
+                areaServed: [...registration.record.areaServed],
+            },
+        }));
+    }
+    /**
+     * Builds the backend bootstrap plan for one provider-discovery request.
+     *
+     * Current default-first policy:
+     * - use configured hosting defaults immediately when they exist
+     * - only try live ICA/internet when no host defaults match the request and at
+     *   least one ICA default is configured for the same host/network context
+     */
+    buildBootstrapPlan(input) {
+        const sourceMode = normalizeString(input.sourceMode)
+            || DataspaceDiscoverySourceMode.DefaultFirst;
+        const icas = this.listIcas(input);
+        const hostingOperators = this.listHostingOperators(input);
+        const hasDefaults = Boolean(icas.length || hostingOperators.length);
+        const shouldUseDefaultsFirst = sourceMode !== DataspaceDiscoverySourceMode.InternetFirst;
+        const shouldTryInternet = sourceMode !== DataspaceDiscoverySourceMode.DefaultsOnly
+            && icas.length > 0
+            && (sourceMode === DataspaceDiscoverySourceMode.InternetFirst
+                || hostingOperators.length === 0);
+        return {
+            sourceMode,
+            icas,
+            hostingOperators,
+            hasDefaults,
+            shouldUseDefaultsFirst,
+            shouldTryInternet,
+        };
+    }
+}
+/**
+ * Convenience factory for the in-memory defaults registry.
+ */
+export function createDataspaceDiscoveryDefaultsRegistry(seed = {}) {
+    return new DataspaceDiscoveryDefaultsRegistry(seed);
+}

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

@@ -1,4 +1,46 @@
 import { type DataspaceDiscoveryFilter, type DataspaceServiceSemanticRecord, type HostingOperatorSemanticRecord, type HostingOperatorDiscoveryCatalog, type PublishedProviderCatalogRecord, type TenantServiceSemanticRecord } from '../models/dataspace-discovery';
+export type DiscoveryCatalogFetchResponse = Readonly<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export declare const DiscoveryCatalogSource: Readonly<{
+    readonly Internet: "internet";
+    readonly Cache: "cache";
+    readonly Default: "default";
+}>;
+export type DiscoveryCatalogSourceValue = typeof DiscoveryCatalogSource[keyof typeof DiscoveryCatalogSource];
+export type DiscoveryCatalogFetcherOptions = Readonly<{
+    internetCatalogs?: Record<string, HostingOperatorDiscoveryCatalog>;
+    internetJsonByUrl?: Record<string, unknown>;
+    defaultCatalogs?: Record<string, HostingOperatorDiscoveryCatalog>;
+}>;
+export type DiscoveryCatalogFetcherHarness = Readonly<{
+    fetcher(input: string, init?: unknown): Promise<DiscoveryCatalogFetchResponse>;
+    calls: string[];
+    sources: Map<string, DiscoveryCatalogSourceValue>;
+    cache: Map<string, HostingOperatorDiscoveryCatalog>;
+    setInternetCatalog(url: string, catalog: HostingOperatorDiscoveryCatalog): void;
+    setInternetJson(url: string, payload: unknown): void;
+    setInternetFailure(url: string, status?: number, body?: unknown): void;
+    clearInternetRoute(url: string): void;
+}>;
+export type DefaultPublishedProviderCatalogRecordInput = Readonly<{
+    providerDid: string;
+    serviceType: string;
+    category: string;
+    areaServed?: string | readonly string[];
+    endpointUrl?: string;
+    discoveryUrl?: string;
+    catalogUrl?: string;
+}>;
+export type DefaultHostingOperatorDiscoveryCatalogInput = Readonly<{
+    hostingOperatorDid?: string;
+    discoveryUrl?: string;
+    catalogUrl?: string;
+    providers?: ReadonlyArray<PublishedProviderCatalogRecord>;
+}>;
 /**
  * Parses the CSV or array representation of `serviceType`.
  *
@@ -144,3 +186,50 @@ export declare function filterPublishedProvidersByDiscoveryFilter(records: Reado
  * the requested service-autodiscovery filter.
  */
 export declare function filterHostingOperatorDiscoveryCatalog(catalog: HostingOperatorDiscoveryCatalog, filter: DataspaceDiscoveryFilter): HostingOperatorDiscoveryCatalog;
+/**
+ * Builds a normalized published-provider catalog DTO suitable for:
+ *
+ * - backend-owned fallback catalogs
+ * - default discovery data loaded from configuration
+ * - tests that should use the same DTO constructors as production code
+ *
+ * This helper is intentionally neutral:
+ * - no example DIDs
+ * - no example URLs
+ * - no hidden business defaults
+ *
+ * @param input Required provider catalog fields plus optional URLs.
+ * @returns Normalized published-provider catalog record.
+ */
+export declare function buildDefaultPublishedProviderCatalogRecord(input: DefaultPublishedProviderCatalogRecordInput): PublishedProviderCatalogRecord;
+/**
+ * Builds a normalized hosting-operator discovery catalog DTO suitable for:
+ *
+ * - backend-owned fallback catalogs
+ * - default host catalogs assembled from configuration
+ * - tests that should reuse the same constructor as production code
+ *
+ * @param input Optional host identity fields plus the provider list.
+ * @returns Normalized host discovery catalog.
+ */
+export declare function buildDefaultHostingOperatorDiscoveryCatalog(input?: DefaultHostingOperatorDiscoveryCatalogInput): HostingOperatorDiscoveryCatalog;
+/**
+ * Creates a generic host-catalog fetcher with cache and default fallback.
+ *
+ * Intended use:
+ * - docs
+ * - SDK integration examples
+ * - tests that need to demonstrate the transport boundary around discovery
+ *
+ * Behavior:
+ * - successful network catalog refreshes cache
+ * - later network failures reuse cached catalog when available
+ * - when both network and cache are unavailable, configured defaults are used
+ *
+ * Production integrations may follow the same policy while replacing this
+ * in-memory harness with real logging, metrics, and storage.
+ *
+ * @param options Optional initial network and default catalogs keyed by URL.
+ * @returns Fetcher plus observable state and mutation helpers.
+ */
+export declare function createDiscoveryCatalogFetcher(options?: DiscoveryCatalogFetcherOptions): DiscoveryCatalogFetcherHarness;

package/dist/utils/dataspace-discovery.js

@@ -11,6 +11,19 @@ function asObject(value) {
 function asNonEmptyString(value) {
     return typeof value === 'string' ? value.trim() : '';
 }
+export const DiscoveryCatalogSource = Object.freeze({
+    Internet: 'internet',
+    Cache: 'cache',
+    Default: 'default',
+});
+function createDiscoveryCatalogFetchResponse(payload, init = {}) {
+    return {
+        ok: init.ok ?? true,
+        status: init.status ?? 200,
+        json: async () => payload,
+        text: async () => JSON.stringify(payload),
+    };
+}
 function toStringList(value) {
     if (Array.isArray(value)) {
         return Array.from(new Set(value
@@ -339,3 +352,131 @@ export function filterHostingOperatorDiscoveryCatalog(catalog, filter) {
         providers: filterPublishedProvidersByDiscoveryFilter(catalog.providers, filter),
     };
 }
+/**
+ * Builds a normalized published-provider catalog DTO suitable for:
+ *
+ * - backend-owned fallback catalogs
+ * - default discovery data loaded from configuration
+ * - tests that should use the same DTO constructors as production code
+ *
+ * This helper is intentionally neutral:
+ * - no example DIDs
+ * - no example URLs
+ * - no hidden business defaults
+ *
+ * @param input Required provider catalog fields plus optional URLs.
+ * @returns Normalized published-provider catalog record.
+ */
+export function buildDefaultPublishedProviderCatalogRecord(input) {
+    const normalizedAreaServed = Array.isArray(input.areaServed)
+        ? normalizeList(input.areaServed.map((value) => asNonEmptyString(value)).filter(Boolean))
+        : toStringList(input.areaServed);
+    return {
+        providerDid: asNonEmptyString(input.providerDid),
+        serviceType: asNonEmptyString(input.serviceType),
+        category: asNonEmptyString(input.category),
+        areaServed: normalizedAreaServed.length ? normalizedAreaServed.join(',') : undefined,
+        endpointUrl: asNonEmptyString(input.endpointUrl) || undefined,
+        discoveryUrl: asNonEmptyString(input.discoveryUrl) || undefined,
+        catalogUrl: asNonEmptyString(input.catalogUrl) || undefined,
+    };
+}
+/**
+ * Builds a normalized hosting-operator discovery catalog DTO suitable for:
+ *
+ * - backend-owned fallback catalogs
+ * - default host catalogs assembled from configuration
+ * - tests that should reuse the same constructor as production code
+ *
+ * @param input Optional host identity fields plus the provider list.
+ * @returns Normalized host discovery catalog.
+ */
+export function buildDefaultHostingOperatorDiscoveryCatalog(input = {}) {
+    return {
+        hostingOperatorDid: asNonEmptyString(input.hostingOperatorDid) || undefined,
+        discoveryUrl: asNonEmptyString(input.discoveryUrl) || undefined,
+        catalogUrl: asNonEmptyString(input.catalogUrl) || undefined,
+        providers: [...(input.providers || [])],
+    };
+}
+function isHostingOperatorCatalogPayload(value) {
+    const objectValue = asObject(value);
+    return Boolean(objectValue && Array.isArray(objectValue.providers));
+}
+/**
+ * Creates a generic host-catalog fetcher with cache and default fallback.
+ *
+ * Intended use:
+ * - docs
+ * - SDK integration examples
+ * - tests that need to demonstrate the transport boundary around discovery
+ *
+ * Behavior:
+ * - successful network catalog refreshes cache
+ * - later network failures reuse cached catalog when available
+ * - when both network and cache are unavailable, configured defaults are used
+ *
+ * Production integrations may follow the same policy while replacing this
+ * in-memory harness with real logging, metrics, and storage.
+ *
+ * @param options Optional initial network and default catalogs keyed by URL.
+ * @returns Fetcher plus observable state and mutation helpers.
+ */
+export function createDiscoveryCatalogFetcher(options = {}) {
+    const internetResponses = new Map([
+        ...Object.entries(options.internetCatalogs || {}).map(([url, catalog]) => [url, createDiscoveryCatalogFetchResponse(catalog, { ok: true, status: 200 })]),
+        ...Object.entries(options.internetJsonByUrl || {}).map(([url, payload]) => [url, createDiscoveryCatalogFetchResponse(payload, { ok: true, status: 200 })]),
+    ]);
+    const internetPayloads = new Map([
+        ...Object.entries(options.internetCatalogs || {}).map(([url, catalog]) => [String(url), catalog]),
+        ...Object.entries(options.internetJsonByUrl || {}).map(([url, payload]) => [String(url), payload]),
+    ]);
+    const defaultCatalogs = new Map(Object.entries(options.defaultCatalogs || {}));
+    const cache = new Map();
+    const sources = new Map();
+    const calls = [];
+    return {
+        calls,
+        sources,
+        cache,
+        setInternetCatalog(url, catalog) {
+            internetResponses.set(String(url), createDiscoveryCatalogFetchResponse(catalog, { ok: true, status: 200 }));
+            internetPayloads.set(String(url), catalog);
+        },
+        setInternetJson(url, payload) {
+            internetResponses.set(String(url), createDiscoveryCatalogFetchResponse(payload, { ok: true, status: 200 }));
+            internetPayloads.set(String(url), payload);
+        },
+        setInternetFailure(url, status = 503, body = { error: 'temporary failure' }) {
+            internetResponses.set(String(url), createDiscoveryCatalogFetchResponse(body, { ok: false, status }));
+            internetPayloads.delete(String(url));
+        },
+        clearInternetRoute(url) {
+            internetResponses.delete(String(url));
+            internetPayloads.delete(String(url));
+        },
+        async fetcher(input) {
+            const key = String(input);
+            calls.push(key);
+            const internetResponse = internetResponses.get(key);
+            if (internetResponse && internetResponse.ok) {
+                const payload = internetPayloads.get(key);
+                if (isHostingOperatorCatalogPayload(payload)) {
+                    cache.set(key, payload);
+                }
+                sources.set(key, DiscoveryCatalogSource.Internet);
+                return internetResponse;
+            }
+            if (cache.has(key)) {
+                sources.set(key, DiscoveryCatalogSource.Cache);
+                return createDiscoveryCatalogFetchResponse(cache.get(key), { ok: true, status: 200 });
+            }
+            if (defaultCatalogs.has(key)) {
+                sources.set(key, DiscoveryCatalogSource.Default);
+                return createDiscoveryCatalogFetchResponse(defaultCatalogs.get(key), { ok: true, status: 200 });
+            }
+            sources.set(key, DiscoveryCatalogSource.Default);
+            return createDiscoveryCatalogFetchResponse({ error: 'not found' }, { ok: false, status: 404 });
+        },
+    };
+}

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

@@ -0,0 +1,66 @@
+import { type DataspaceProtocolVersionValue } from '../constants/dataspace-protocol';
+import type { DspaceProtocolVersionEntry, DspaceVersionMetadata } from '../models/dataspace-protocol';
+/**
+ * Route context used to build tenant-scoped or host-scoped GW CORE DSP paths.
+ *
+ * Semantic rule:
+ * - `tenantId` participants use `businessSector`
+ * - `host`/ICA/runtime participants use `hostNetwork`
+ */
+export type GwDataspaceRouteContext = Readonly<{
+    participantId?: string;
+    tenantId?: string;
+    jurisdiction?: string;
+    version?: string;
+    hostNetwork?: string;
+    /** @deprecated Use `hostNetwork`. */
+    hostNetworkOrBusinessSector?: string;
+    businessSector?: string;
+    sector?: string;
+}>;
+/**
+ * Builds the GW CORE base DSP path.
+ *
+ * Participant scope:
+ * - `/{participantId}/cds-{jurisdiction}/{version}/{hostNetwork|businessSector}/dsp`
+ */
+export declare function buildGwDataspaceBasePath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the canonical DSP version-discovery well-known path for GW CORE.
+ *
+ * Participant scope:
+ * - `/{participantId}/cds-{jurisdiction}/{version}/{hostNetwork|businessSector}/.well-known/dspace-version`
+ */
+export declare function buildGwDspaceVersionWellKnownPath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the project-local GW CORE DSP catalog request endpoint.
+ */
+export declare function buildGwCatalogRequestPath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the GW CORE catalog collection base path.
+ */
+export declare function buildGwCatalogCollectionPath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the project-local GW CORE catalog artifact URL path used for public
+ * read-only autodiscovery.
+ */
+export declare function buildGwCatalogArtifactPath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the project-local GW CORE dataset lookup path.
+ */
+export declare function buildGwCatalogDatasetPath(input?: GwDataspaceRouteContext, datasetId?: string): string;
+/**
+ * Builds a minimal DSP version metadata payload for a given GW CORE DSP base
+ * path.
+ */
+export declare function buildDspaceVersionMetadata(path: string, version?: DataspaceProtocolVersionValue): DspaceVersionMetadata;
+/**
+ * Selects the preferred advertised DSP version entry from a `dspace-version`
+ * payload.
+ */
+export declare function selectDspaceProtocolVersionEntry(metadata: DspaceVersionMetadata | null | undefined, version?: string): DspaceProtocolVersionEntry | undefined;
+/**
+ * Derives the GW CORE catalog artifact URL from a `dspace-version` endpoint URL
+ * and its parsed payload.
+ */
+export declare function deriveGwCatalogArtifactUrlFromDspaceVersion(dspaceVersionUrl: string, metadata: DspaceVersionMetadata | null | undefined, version?: string): string | undefined;

package/dist/utils/dataspace-protocol.js

@@ -0,0 +1,109 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { DataspaceProtocolVersions, DataspaceWellKnownPaths, GwDataspaceBindingPaths, } from '../constants/dataspace-protocol.js';
+function resolveParticipantId(input) {
+    return String(input.participantId || input.tenantId || '').trim();
+}
+function resolveSectorLikeSegment(input) {
+    return String(input.hostNetwork
+        || input.hostNetworkOrBusinessSector
+        || input.businessSector
+        || input.sector
+        || '').trim();
+}
+function hasParticipantRouteContext(input) {
+    return Boolean(resolveParticipantId(input)
+        && String(input.jurisdiction || '').trim()
+        && String(input.version || '').trim()
+        && resolveSectorLikeSegment(input));
+}
+/**
+ * Builds the GW CORE base DSP path.
+ *
+ * Participant scope:
+ * - `/{participantId}/cds-{jurisdiction}/{version}/{hostNetwork|businessSector}/dsp`
+ */
+export function buildGwDataspaceBasePath(input = {}) {
+    if (!hasParticipantRouteContext(input)) {
+        return GwDataspaceBindingPaths.Base;
+    }
+    return `/${resolveParticipantId(input)}`
+        + `/cds-${String(input.jurisdiction).trim()}`
+        + `/${String(input.version).trim()}`
+        + `/${resolveSectorLikeSegment(input)}`
+        + GwDataspaceBindingPaths.Base;
+}
+/**
+ * Builds the canonical DSP version-discovery well-known path for GW CORE.
+ *
+ * Participant scope:
+ * - `/{participantId}/cds-{jurisdiction}/{version}/{hostNetwork|businessSector}/.well-known/dspace-version`
+ */
+export function buildGwDspaceVersionWellKnownPath(input = {}) {
+    if (!hasParticipantRouteContext(input)) {
+        return DataspaceWellKnownPaths.VersionMetadata;
+    }
+    return `/${resolveParticipantId(input)}`
+        + `/cds-${String(input.jurisdiction).trim()}`
+        + `/${String(input.version).trim()}`
+        + `/${resolveSectorLikeSegment(input)}`
+        + DataspaceWellKnownPaths.VersionMetadata;
+}
+/**
+ * Builds the project-local GW CORE DSP catalog request endpoint.
+ */
+export function buildGwCatalogRequestPath(input = {}) {
+    return `${buildGwDataspaceBasePath(input)}${GwDataspaceBindingPaths.CatalogRequestSuffix}`;
+}
+/**
+ * Builds the GW CORE catalog collection base path.
+ */
+export function buildGwCatalogCollectionPath(input = {}) {
+    return `${buildGwDataspaceBasePath(input)}${GwDataspaceBindingPaths.CatalogCollectionSuffix}`;
+}
+/**
+ * Builds the project-local GW CORE catalog artifact URL path used for public
+ * read-only autodiscovery.
+ */
+export function buildGwCatalogArtifactPath(input = {}) {
+    return `${buildGwDataspaceBasePath(input)}${GwDataspaceBindingPaths.CatalogArtifactSuffix}`;
+}
+/**
+ * Builds the project-local GW CORE dataset lookup path.
+ */
+export function buildGwCatalogDatasetPath(input = {}, datasetId = ':id') {
+    return `${buildGwDataspaceBasePath(input)}${GwDataspaceBindingPaths.CatalogDatasetsPrefix}/${datasetId}`;
+}
+/**
+ * Builds a minimal DSP version metadata payload for a given GW CORE DSP base
+ * path.
+ */
+export function buildDspaceVersionMetadata(path, version = DataspaceProtocolVersions.Current) {
+    return {
+        protocolVersions: [
+            {
+                version,
+                path,
+            },
+        ],
+    };
+}
+/**
+ * Selects the preferred advertised DSP version entry from a `dspace-version`
+ * payload.
+ */
+export function selectDspaceProtocolVersionEntry(metadata, version = DataspaceProtocolVersions.Current) {
+    const entries = metadata?.protocolVersions || [];
+    return entries.find((entry) => String(entry.version || '').trim() === String(version).trim())
+        || entries[0];
+}
+/**
+ * Derives the GW CORE catalog artifact URL from a `dspace-version` endpoint URL
+ * and its parsed payload.
+ */
+export function deriveGwCatalogArtifactUrlFromDspaceVersion(dspaceVersionUrl, metadata, version = DataspaceProtocolVersions.Current) {
+    const entry = selectDspaceProtocolVersionEntry(metadata, version);
+    if (!entry?.path)
+        return undefined;
+    const base = new URL(dspaceVersionUrl);
+    return new URL(`${String(entry.path).trim()}${GwDataspaceBindingPaths.CatalogArtifactSuffix}`, `${base.protocol}//${base.host}`).toString();
+}

package/dist/utils/index.d.ts

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

package/dist/utils/index.js

@@ -8,6 +8,8 @@ export * from './consent.js';
 export * from './did.js';
 export * from './did-resolution.js';
 export * from './dataspace-discovery.js';
+export * from './dataspace-discovery-defaults.js';
+export * from './dataspace-protocol.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.12.0",
+  "version": "1.14.0",
   "publishConfig": {
     "access": "public"
   },