gdc-common-utils-ts 1.13.0 → 1.14.0

package/README.md

@@ -89,6 +89,9 @@ 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
 
@@ -105,9 +108,17 @@ Main entry points:
 - [`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)

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

@@ -1,6 +1,7 @@
 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';

package/dist/constants/index.js

@@ -1,6 +1,7 @@
 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';

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";
@@ -33,6 +35,8 @@ 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";

package/dist/examples/shared.js

@@ -16,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';
@@ -39,11 +41,13 @@ 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_DSPACE_VERSION_URL = `https://host.example.org/host/cds-ES/v1/${HostNetworkTypes.Test}/.well-known/dspace-version`;
-export const EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL = `https://host.example.org/host/cds-ES/v1/${HostNetworkTypes.Test}/dsp/catalog/dcat.json`;
+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';

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

@@ -13,6 +13,7 @@ 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';

package/dist/models/index.js

@@ -13,6 +13,7 @@ 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';

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

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

package/dist/utils/index.js

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

package/package.json

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