gdc-sdk-node-ts 0.5.0 → 0.6.0

package/README.md

@@ -25,12 +25,15 @@ If you are integrating this package for the first time, open these in order:
    Real backend setup, imports, `initializeCommunicationIdentity(...)`,
    `new NodeHttpClient(...)`, route context, facade selection, and live method
    usage.
-3. [gdc-sdk-core-ts/docs/SDK_FLOWS_101.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/SDK_FLOWS_101.md)
+3. [docs/DISCOVERY_101.md](./docs/DISCOVERY_101.md)
+   Node/BFF dataspace discovery, hosting-operator resolution, provider
+   resolution, and the correct integration boundary for fallback and cache.
+4. [gdc-sdk-core-ts/docs/SDK_FLOWS_101.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/SDK_FLOWS_101.md)
    Actor split and business-flow map across organization, individual,
    permissions, invitation, import, and SMART flows.
-4. [gdc-common-utils-ts/src/examples/](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/tree/main/src/examples)
+5. [gdc-common-utils-ts/src/examples/](https://github.com/Global-DataCare/gdc-common-utils-ts/tree/main/src/examples)
    Shared payload values used by the docs and tests.
-5. [gdc-common-utils-ts/docs/LIFECYCLE_101.md](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/docs/LIFECYCLE_101.md)
+6. [gdc-common-utils-ts/docs/LIFECYCLE_101.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/LIFECYCLE_101.md)
    Canonical `enable/disable/delete` semantics and copy/paste placeholders.
 
 If you need the shortest path:
@@ -46,6 +49,8 @@ If you need the shortest path:
   [`NodeHttpClient`](src/node-runtime-client.ts)
 - step-by-step runtime usage:
   [docs/SDK_INTEGRATION_101.md](./docs/SDK_INTEGRATION_101.md)
+- dataspace discovery and fallback/cache boundary:
+  [docs/DISCOVERY_101.md](./docs/DISCOVERY_101.md)
 
 ## Executable Usage Examples
 
@@ -65,6 +70,42 @@ Open these tests when you want to see exact method calls and exact inputs:
   SMART token request flow.
 - [tests/live-gw-node-runtime.e2e.test.mjs](tests/live-gw-node-runtime.e2e.test.mjs)
   End-to-end runtime wiring against a real GW environment.
+- [tests/dataspace-resolver.101.test.mjs](tests/dataspace-resolver.101.test.mjs)
+  Dataspace discovery 101 with capability filtering, jurisdiction filtering,
+  reader-vs-provider semantics, and fetcher-level fallback/cache examples.
+
+## Dataspace Discovery Quick Map
+
+Use the Node resolver when your backend or BFF needs to:
+
+- start from preloaded hosting-operator semantics
+- fetch the canonical `/.well-known/dspace-version` entrypoint
+- derive the participant-scoped `/dsp/catalog/dcat.json` artifact
+- return normalized provider/operator matches to portal or app backends
+
+Primary references:
+
+- [docs/DISCOVERY_101.md](./docs/DISCOVERY_101.md)
+- [tests/dataspace-resolver.101.test.mjs](tests/dataspace-resolver.101.test.mjs)
+- [tests/dataspace-resolver.test.mjs](tests/dataspace-resolver.test.mjs)
+
+Copy/paste starting point:
+
+```ts
+import { HttpDataspaceResolver } from 'gdc-sdk-node-ts';
+import { ServiceCapabilityToken } from 'gdc-common-utils-ts/constants';
+
+const resolver = new HttpDataspaceResolver({
+  hostingOperators,
+  fetcher, // optional injection for tests, fallback, tracing, or custom agents
+});
+
+const providers = await resolver.resolvePublishedProviders({
+  sector: 'animal-care',
+  jurisdiction: 'ES',
+  providerCapability: ServiceCapabilityToken.IndexProvider,
+});
+```
 
 ## Actor Split And Runtime Scope
 
@@ -247,16 +288,16 @@ Teaching rule:
 ## Shared Contract Sources
 
 - [gdc-sdk-core-ts/README.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/README.md)
-- [gdc-common-utils-ts/docs/CONSENT_ACCESS_101.md](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/docs/CONSENT_ACCESS_101.md)
+- [gdc-common-utils-ts/docs/CONSENT_ACCESS_101.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/CONSENT_ACCESS_101.md)
 
 Reusable payload examples:
 
-- [gdc-common-utils-ts/src/examples/organization-controller.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/organization-controller.ts)
-- [gdc-common-utils-ts/src/examples/individual-controller.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/individual-controller.ts)
-- [gdc-common-utils-ts/src/examples/professional.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/professional.ts)
-- [gdc-common-utils-ts/src/examples/shared.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/shared.ts)
-- [gdc-common-utils-ts/src/examples/lifecycle.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/lifecycle.ts)
-- [gdc-common-utils-ts/src/examples/api-flow-examples.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/api-flow-examples.ts)
+- [gdc-common-utils-ts/src/examples/organization-controller.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/organization-controller.ts)
+- [gdc-common-utils-ts/src/examples/individual-controller.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/individual-controller.ts)
+- [gdc-common-utils-ts/src/examples/professional.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/professional.ts)
+- [gdc-common-utils-ts/src/examples/shared.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/shared.ts)
+- [gdc-common-utils-ts/src/examples/lifecycle.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/lifecycle.ts)
+- [gdc-common-utils-ts/src/examples/api-flow-examples.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/api-flow-examples.ts)
 
 ## API Index
 

package/dist/discovery/DataspaceResolver.d.ts

@@ -0,0 +1,24 @@
+import type { HostingOperatorMatch, PublishedProviderMatch, ResolveHostingOperatorsInput, ResolvePublishedProvidersInput } from './types.js';
+/**
+ * Backend/BFF-facing abstraction for dataspace discovery resolution.
+ *
+ * Responsibility boundary:
+ * - node runtimes orchestrate VC parsing, host-catalog fetch, and capability
+ *   filtering
+ * - semantic extraction and EU coverage inference come from
+ *   `gdc-common-utils-ts`
+ * - tenant-host linkage is resolved from host public catalogs, not from private
+ *   tenant VC fields
+ */
+export declare abstract class DataspaceResolver {
+    /**
+     * Resolves hosting operators whose semantic service metadata matches the
+     * requested sector, capability set, and optional coverage dimensions.
+     */
+    abstract resolveHostingOperators(input: ResolveHostingOperatorsInput): Promise<HostingOperatorMatch[]>;
+    /**
+     * Resolves publicly published provider offerings starting from eligible
+     * hosting operators and their public discovery catalogs.
+     */
+    abstract resolvePublishedProviders(input: ResolvePublishedProvidersInput): Promise<PublishedProviderMatch[]>;
+}

package/dist/discovery/DataspaceResolver.js

@@ -0,0 +1,14 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Backend/BFF-facing abstraction for dataspace discovery resolution.
+ *
+ * Responsibility boundary:
+ * - node runtimes orchestrate VC parsing, host-catalog fetch, and capability
+ *   filtering
+ * - semantic extraction and EU coverage inference come from
+ *   `gdc-common-utils-ts`
+ * - tenant-host linkage is resolved from host public catalogs, not from private
+ *   tenant VC fields
+ */
+export class DataspaceResolver {
+}

package/dist/discovery/HttpDataspaceResolver.d.ts

@@ -0,0 +1,30 @@
+import { DataspaceResolver } from './DataspaceResolver.js';
+import type { HostingOperatorMatch, HttpDataspaceResolverOptions, PublishedProviderMatch, ResolveHostingOperatorsInput, ResolvePublishedProvidersInput } from './types.js';
+/**
+ * Concrete node/BFF resolver that combines preloaded hosting-operator records
+ * with each host's public service-autodiscovery catalog.
+ */
+export declare class HttpDataspaceResolver extends DataspaceResolver {
+    private readonly hostingOperators;
+    private readonly fetcher;
+    constructor(options: HttpDataspaceResolverOptions);
+    /**
+     * Resolves hosting operators from the preloaded semantic records.
+     */
+    resolveHostingOperators(input: ResolveHostingOperatorsInput): Promise<HostingOperatorMatch[]>;
+    /**
+     * Resolves published providers by fetching and filtering eligible host public
+     * discovery catalogs.
+     */
+    resolvePublishedProviders(input: ResolvePublishedProvidersInput): Promise<PublishedProviderMatch[]>;
+    /**
+     * Fetches a public discovery catalog for a hosting operator.
+     *
+     * Resolution order:
+     * - canonical DSP entrypoint via `discoveryUrl` (`/.well-known/dspace-version`)
+     * - direct catalog artifact compatibility via `catalogUrl`
+     */
+    private fetchCatalog;
+    private resolveCatalogArtifactUrl;
+    private fetchDspaceVersionMetadata;
+}

package/dist/discovery/HttpDataspaceResolver.js

@@ -0,0 +1,231 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { DataspaceCoverageScope, DataspaceProtocolVersions, DataspaceWellKnownPaths, deriveGwCatalogArtifactUrlFromDspaceVersion, inferCoverageScopeFromCountryCode, isProviderServiceCapability, normalizeCountryCode, } from 'gdc-common-utils-ts';
+import { DataspaceResolver } from './DataspaceResolver.js';
+function isObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function equalsIgnoreCase(left, right) {
+    return left.trim().toLowerCase() === right.trim().toLowerCase();
+}
+function splitTokens(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => asString(entry)).filter(Boolean);
+    }
+    const raw = typeof value === 'string' ? value : '';
+    if (!raw)
+        return [];
+    return raw.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+function hasAllTokens(values, requiredValues) {
+    if (!requiredValues?.length)
+        return true;
+    const normalizedValues = new Set((values || []).map((value) => value.trim().toLowerCase()).filter(Boolean));
+    return requiredValues.every((requiredValue) => normalizedValues.has(requiredValue.trim().toLowerCase()));
+}
+function matchSectorValues(values, sector) {
+    if (!sector)
+        return true;
+    return (values || []).some((value) => equalsIgnoreCase(value, sector));
+}
+function buildCoverageTokens(recordCountry, areaServed, coverageScope) {
+    const tokens = new Set();
+    splitTokens(areaServed).forEach((token) => tokens.add(token.toUpperCase()));
+    const normalizedCountry = normalizeCountryCode(recordCountry);
+    if (normalizedCountry) {
+        tokens.add(normalizedCountry);
+        const inferred = inferCoverageScopeFromCountryCode(normalizedCountry);
+        if (inferred)
+            tokens.add(inferred.toUpperCase());
+    }
+    if (coverageScope) {
+        tokens.add(coverageScope.trim().toUpperCase());
+    }
+    return tokens;
+}
+function matchesDiscoveryCoverage(recordCountry, areaServed, filterJurisdiction, filterCoverageScope) {
+    const normalizedJurisdiction = normalizeCountryCode(filterJurisdiction);
+    const normalizedCoverageScope = asString(filterCoverageScope).toUpperCase();
+    if (!normalizedJurisdiction && !normalizedCoverageScope)
+        return true;
+    const tokens = buildCoverageTokens(recordCountry, areaServed, undefined);
+    if (normalizedJurisdiction && tokens.has(normalizedJurisdiction))
+        return true;
+    if (normalizedCoverageScope && tokens.has(normalizedCoverageScope))
+        return true;
+    if (normalizedJurisdiction) {
+        const inferred = inferCoverageScopeFromCountryCode(normalizedJurisdiction);
+        if (inferred && tokens.has(inferred.toUpperCase()))
+            return true;
+    }
+    if (normalizedCoverageScope === DataspaceCoverageScope.EuropeanUnion) {
+        if (Array.from(tokens).some((token) => inferCoverageScopeFromCountryCode(token) === DataspaceCoverageScope.EuropeanUnion)) {
+            return true;
+        }
+    }
+    return false;
+}
+function toHostingOperatorCatalog(value) {
+    if (!isObject(value))
+        return null;
+    const providers = value.providers;
+    if (!Array.isArray(providers))
+        return null;
+    const normalizedProviders = providers
+        .filter(isObject)
+        .map((provider) => {
+        const normalized = {
+            providerDid: asString(provider.providerDid),
+            serviceType: asString(provider.serviceType),
+            category: asString(provider.category),
+            areaServed: asString(provider.areaServed) || undefined,
+            endpointUrl: asString(provider.endpointUrl) || undefined,
+            discoveryUrl: asString(provider.discoveryUrl) || undefined,
+            catalogUrl: asString(provider.catalogUrl) || undefined,
+        };
+        return normalized.providerDid && normalized.serviceType && normalized.category
+            ? normalized
+            : null;
+    })
+        .filter((provider) => Boolean(provider));
+    return {
+        hostingOperatorDid: asString(value.hostingOperatorDid) || undefined,
+        discoveryUrl: asString(value.discoveryUrl) || undefined,
+        catalogUrl: asString(value.catalogUrl) || undefined,
+        providers: normalizedProviders,
+    };
+}
+function matchHostingOperatorRecord(record, input) {
+    if (!matchSectorValues(record.categories, input.sector))
+        return false;
+    if (!hasAllTokens(record.serviceTypes, input.requiredCapabilities))
+        return false;
+    if (!matchesDiscoveryCoverage(record.addressCountry, record.areaServed, input.jurisdiction, input.coverageScope))
+        return false;
+    return true;
+}
+function matchPublishedProviderRecord(provider, input) {
+    if (!equalsIgnoreCase(provider.category, input.sector))
+        return false;
+    if (!isProviderServiceCapability(provider.serviceType))
+        return false;
+    if (!equalsIgnoreCase(provider.serviceType, input.providerCapability))
+        return false;
+    if (!matchesDiscoveryCoverage(undefined, provider.areaServed, input.jurisdiction, input.coverageScope))
+        return false;
+    return true;
+}
+/**
+ * Concrete node/BFF resolver that combines preloaded hosting-operator records
+ * with each host's public service-autodiscovery catalog.
+ */
+export class HttpDataspaceResolver extends DataspaceResolver {
+    constructor(options) {
+        super();
+        this.hostingOperators = [...options.hostingOperators];
+        this.fetcher = options.fetcher || globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Resolves hosting operators from the preloaded semantic records.
+     */
+    async resolveHostingOperators(input) {
+        return this.hostingOperators
+            .filter(({ record }) => matchHostingOperatorRecord(record, input))
+            .map(({ operatorDid, discoveryUrl, record, catalogUrl }) => ({
+            operatorDid,
+            record,
+            matchedCapabilities: (input.requiredCapabilities || []).filter((capability) => record.serviceTypes.some((value) => equalsIgnoreCase(value, capability))),
+            discoveryUrl,
+            catalogUrl,
+        }))
+            .sort((left, right) => left.operatorDid.localeCompare(right.operatorDid));
+    }
+    /**
+     * Resolves published providers by fetching and filtering eligible host public
+     * discovery catalogs.
+     */
+    async resolvePublishedProviders(input) {
+        const eligibleHosts = await this.resolveHostingOperators({
+            sector: input.sector,
+            jurisdiction: input.jurisdiction,
+            coverageScope: input.coverageScope,
+            requiredCapabilities: [input.providerCapability],
+        });
+        const catalogs = await Promise.all(eligibleHosts.map(async (host) => ({
+            host,
+            catalog: await this.fetchCatalog(host.discoveryUrl, host.catalogUrl),
+        })));
+        return catalogs.flatMap(({ host, catalog }) => {
+            if (!catalog)
+                return [];
+            return catalog.providers
+                .filter((record) => matchPublishedProviderRecord(record, input))
+                .map((record) => ({
+                providerDid: record.providerDid,
+                record,
+                hostingOperator: host.record,
+                hostingOperatorDid: host.operatorDid,
+                discoveryUrl: record.discoveryUrl || catalog.discoveryUrl || host.discoveryUrl,
+                catalogUrl: record.catalogUrl || catalog.catalogUrl || host.catalogUrl,
+            }));
+        }).sort((left, right) => left.providerDid.localeCompare(right.providerDid));
+    }
+    /**
+     * Fetches a public discovery catalog for a hosting operator.
+     *
+     * Resolution order:
+     * - canonical DSP entrypoint via `discoveryUrl` (`/.well-known/dspace-version`)
+     * - direct catalog artifact compatibility via `catalogUrl`
+     */
+    async fetchCatalog(discoveryUrl, catalogUrl) {
+        const resolvedCatalogUrl = await this.resolveCatalogArtifactUrl(discoveryUrl, catalogUrl);
+        if (!resolvedCatalogUrl)
+            return undefined;
+        const response = await this.fetcher(resolvedCatalogUrl, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+            },
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const body = await response.json();
+        return toHostingOperatorCatalog(body) || undefined;
+    }
+    async resolveCatalogArtifactUrl(discoveryUrl, catalogUrl) {
+        const normalizedDiscoveryUrl = String(discoveryUrl || '').trim();
+        if (normalizedDiscoveryUrl) {
+            if (normalizedDiscoveryUrl.endsWith(DataspaceWellKnownPaths.VersionMetadata)) {
+                const metadata = await this.fetchDspaceVersionMetadata(normalizedDiscoveryUrl);
+                return deriveGwCatalogArtifactUrlFromDspaceVersion(normalizedDiscoveryUrl, metadata, DataspaceProtocolVersions.Current);
+            }
+            return normalizedDiscoveryUrl;
+        }
+        const normalizedCatalogUrl = String(catalogUrl || '').trim();
+        return normalizedCatalogUrl || undefined;
+    }
+    async fetchDspaceVersionMetadata(discoveryUrl) {
+        const response = await this.fetcher(discoveryUrl, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+            },
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const body = await response.json();
+        return isDspaceVersionMetadata(body)
+            ? body
+            : undefined;
+    }
+}
+function isDspaceVersionMetadata(value) {
+    if (!isObject(value))
+        return false;
+    return Array.isArray(value.protocolVersions)
+        && value.protocolVersions.every((entry) => isObject(entry) && asString(entry.version) && asString(entry.path));
+}

package/dist/discovery/index.d.ts

@@ -0,0 +1,3 @@
+export * from './DataspaceResolver.js';
+export * from './HttpDataspaceResolver.js';
+export * from './types.js';

package/dist/discovery/index.js

@@ -0,0 +1,4 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+export * from './DataspaceResolver.js';
+export * from './HttpDataspaceResolver.js';
+export * from './types.js';

package/dist/discovery/types.d.ts

@@ -0,0 +1,68 @@
+import type { DataspaceDiscoveryFilter, HostingOperatorDiscoveryCatalog, HostingOperatorSemanticRecord, PublishedProviderCatalogRecord, TenantServiceSemanticRecord } from 'gdc-common-utils-ts';
+/**
+ * Input for resolving hosting operators that can serve a given dataspace use
+ * case.
+ */
+export type ResolveHostingOperatorsInput = Omit<DataspaceDiscoveryFilter, 'capability'> & Readonly<{
+    requiredCapabilities: readonly string[];
+}>;
+/**
+ * Input for resolving publicly published providers through hosting-operator
+ * catalogs.
+ */
+export type ResolvePublishedProvidersInput = Omit<DataspaceDiscoveryFilter, 'capability' | 'requiredCapabilities'> & Readonly<{
+    providerCapability: string;
+}>;
+/**
+ * Preloaded semantic hosting-operator record used by the node runtime to
+ * resolve public discovery data without re-parsing VCs.
+ */
+export type PreloadedHostingOperatorRecord = Readonly<{
+    operatorDid: string;
+    /**
+     * Canonical DSP discovery entrypoint.
+     *
+     * For GW CORE this should normally be `/.well-known/dspace-version`.
+     */
+    discoveryUrl?: string;
+    /**
+     * @deprecated Prefer `discoveryUrl`. This remains as a compatibility field
+     * for direct catalog artifact URLs.
+     */
+    catalogUrl?: string;
+    record: HostingOperatorSemanticRecord;
+}>;
+/**
+ * Runtime configuration for the HTTP-capable dataspace resolver.
+ */
+export type HttpDataspaceResolverOptions = Readonly<{
+    hostingOperators: readonly PreloadedHostingOperatorRecord[];
+    fetcher?: typeof fetch;
+    requestHeaders?: Record<string, string>;
+}>;
+/**
+ * Normalized hosting-operator match returned by a node/BFF resolver.
+ */
+export type HostingOperatorMatch = Readonly<{
+    operatorDid: string;
+    record: HostingOperatorSemanticRecord;
+    matchedCapabilities: string[];
+    discoveryUrl?: string;
+    catalogUrl?: string;
+}>;
+/**
+ * Normalized published-provider match returned by a node/BFF resolver.
+ */
+export type PublishedProviderMatch = Readonly<{
+    providerDid: string;
+    record: PublishedProviderCatalogRecord;
+    hostingOperator: HostingOperatorSemanticRecord;
+    hostingOperatorDid: string;
+    discoveryUrl?: string;
+    catalogUrl?: string;
+    tenantSemanticRecord?: TenantServiceSemanticRecord;
+}>;
+/**
+ * Shared host catalog shape returned by HTTP discovery endpoints.
+ */
+export type HostingOperatorCatalog = HostingOperatorDiscoveryCatalog;

package/dist/discovery/types.js

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

package/dist/host-onboarding.d.ts

@@ -3,11 +3,13 @@ import type { PollOptions, SubmitAndPollResult } from './orchestration/client-po
  * Current host-registry route context for existing host endpoints.
  *
  * This is a routing object for host registry calls. It is not the same thing as
- * a node-operator discovery descriptor.
+ * a host discovery descriptor.
  */
 export type HostRouteContext = {
     jurisdiction: string;
-    sector: string;
+    hostNetwork?: string;
+    /** @deprecated Use `hostNetwork`. */
+    sector?: string;
     controllerDid?: string;
     hostDid?: string;
 };
@@ -17,6 +19,8 @@ export type HostRouteContext = {
 export type LegalOrganizationOrderInput = {
     offerId: string;
     jurisdiction?: string;
+    hostNetwork?: string;
+    /** @deprecated Use `hostNetwork`. */
     sector?: string;
     dataType?: string;
     additionalClaims?: Record<string, unknown>;

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from './smart-token.js';
 export * from './resource-operations.js';
 export * from './session.js';
 export * from './node-runtime-client.js';
+export * from './discovery/index.js';
 export * from './gdc-session-bridge.js';
 export * from './orchestration/client-port.js';
 export * from './orchestration/host-onboarding-sdk.js';

package/dist/index.js

@@ -12,6 +12,7 @@ export * from './smart-token.js';
 export * from './resource-operations.js';
 export * from './session.js';
 export * from './node-runtime-client.js';
+export * from './discovery/index.js';
 export * from './gdc-session-bridge.js';
 export * from './orchestration/client-port.js';
 export * from './orchestration/host-onboarding-sdk.js';

package/dist/node-runtime-client.d.ts

@@ -12,6 +12,21 @@ import type { NodeRuntimeClient, PollOptions, PollResult, SubmitAndPollResult, S
 export type HttpRuntimeClientOptions = {
     baseUrl: string;
     bearerToken?: string;
+    /**
+     * Optional ICA-issued runtime/software proof token reused as the default
+     * HTTP Bearer credential in demo/compat profiles when no explicit
+     * `bearerToken` is provided.
+     *
+     * This keeps the SDK wiring ready for a future ICA-authorized software
+     * runtime contract without forcing callers to overload the semantic name
+     * `bearerToken` in documentation or app code.
+     *
+     * Current `gwtemplate-node-ts` demo/bootstrap flows do not yet require a
+     * registered software/runtime proof for this path, so callers may omit this
+     * field or pass an empty string until the ICA runtime-registration contract
+     * is finalized.
+     */
+    runtimeVpToken?: string;
     /**
      * Host app identity required by GW CORE.
      *
@@ -44,6 +59,7 @@ export type NodeHttpClientOptions = HttpRuntimeClientOptions;
 export declare class HttpRuntimeClient implements NodeRuntimeClient {
     private readonly baseUrl;
     private readonly bearerToken?;
+    private readonly runtimeVpToken?;
     private readonly resolvedAppInfo?;
     private readonly ctx?;
     private readonly defaultHeaders;
@@ -54,6 +70,7 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * @param options.baseUrl Gateway base URL without trailing slash.
      * @param options.interopMode Optional runtime interoperability mode from the SDK config layer (`demo`, `compat`, `strict`).
      * @param options.bearerToken Optional bearer token reused for direct HTTP calls.
+     * @param options.runtimeVpToken Optional ICA-issued runtime/software proof token reused as Bearer when `bearerToken` is not set. Current `gwtemplate-node-ts` demo/bootstrap flows may omit it or pass an empty string because software/runtime registration is not enforced there yet.
      * @param options.appInfo Optional GW CORE app identity. When present, the
      * client injects `AppId` and `AppVersion` into all outgoing requests.
      * @param options.ctx Optional default route context.
@@ -69,6 +86,10 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * Returns the standard GW CORE headers currently injected by the Node client.
      */
     getAppHeaders(): Record<'AppId' | 'AppVersion', string> | undefined;
+    /**
+     * Returns the configured ICA-issued runtime/software proof token, when present.
+     */
+    getRuntimeVpToken(): string | undefined;
     /**
      * Builds a canonical GDC v1 resource/action path from a route context.
      */

package/dist/node-runtime-client.js

@@ -26,6 +26,7 @@ export class HttpRuntimeClient {
      * @param options.baseUrl Gateway base URL without trailing slash.
      * @param options.interopMode Optional runtime interoperability mode from the SDK config layer (`demo`, `compat`, `strict`).
      * @param options.bearerToken Optional bearer token reused for direct HTTP calls.
+     * @param options.runtimeVpToken Optional ICA-issued runtime/software proof token reused as Bearer when `bearerToken` is not set. Current `gwtemplate-node-ts` demo/bootstrap flows may omit it or pass an empty string because software/runtime registration is not enforced there yet.
      * @param options.appInfo Optional GW CORE app identity. When present, the
      * client injects `AppId` and `AppVersion` into all outgoing requests.
      * @param options.ctx Optional default route context.
@@ -35,7 +36,10 @@ export class HttpRuntimeClient {
     constructor(options) {
         this.tokenCache = new Map();
         this.baseUrl = String(options.baseUrl || '').replace(/\/+$/, '');
-        this.bearerToken = String(options.bearerToken || '').trim() || undefined;
+        this.runtimeVpToken = String(options.runtimeVpToken || '').trim() || undefined;
+        this.bearerToken = String(options.bearerToken || '').trim()
+            || this.runtimeVpToken
+            || undefined;
         this.resolvedAppInfo = options.appInfo ? resolveAppInfo(options.appInfo) : undefined;
         this.ctx = options.ctx;
         this.defaultHeaders = {
@@ -59,6 +63,12 @@ export class HttpRuntimeClient {
             return undefined;
         return buildAppHeaders(this.resolvedAppInfo);
     }
+    /**
+     * Returns the configured ICA-issued runtime/software proof token, when present.
+     */
+    getRuntimeVpToken() {
+        return this.runtimeVpToken;
+    }
     /**
      * Builds a canonical GDC v1 resource/action path from a route context.
      */
@@ -503,14 +513,15 @@ export class HttpRuntimeClient {
     }
     hostRegistryPath(ctx, resourceType, action) {
         const hostCtx = this.requireHostRouteContext(ctx);
-        return `/host/cds-${encodeURIComponent(hostCtx.jurisdiction)}/v1/${encodeURIComponent(hostCtx.sector)}/registry/org.schema/${encodeURIComponent(resourceType)}/${encodeURIComponent(action)}`;
+        return `/host/cds-${encodeURIComponent(hostCtx.jurisdiction)}/v1/${encodeURIComponent(hostCtx.hostNetwork || '')}/registry/org.schema/${encodeURIComponent(resourceType)}/${encodeURIComponent(action)}`;
     }
     requireHostRouteContext(ctx) {
+        const runtimeCtx = (this.ctx || {});
         const jurisdiction = String(ctx?.jurisdiction || this.ctx?.jurisdiction || '').trim();
-        const sector = String(ctx?.sector || this.ctx?.sector || '').trim();
-        if (!jurisdiction || !sector)
+        const hostNetwork = String(ctx?.hostNetwork || ctx?.sector || runtimeCtx.hostNetwork || runtimeCtx.sector || '').trim();
+        if (!jurisdiction || !hostNetwork)
             throw new Error('Host route context is required.');
-        return { jurisdiction, sector };
+        return { jurisdiction, hostNetwork };
     }
     hostRegistryOrganizationActivatePath(ctx) { return this.hostRegistryPath(ctx, 'Organization', '_activate'); }
     hostRegistryOrganizationActivatePollPath(ctx) { return this.hostRegistryPath(ctx, 'Organization', '_activate-response'); }

package/dist/runtime-contracts.d.ts

@@ -1,5 +1,6 @@
 import type { NodeOperatorNetworkType } from 'gdc-common-utils-ts/constants/network';
 import type { DataPersistencePolicy } from 'gdc-sdk-core-ts';
+type HostNetworkType = NodeOperatorNetworkType;
 export type LegacyNodeSourcePackage = never;
 /**
  * Deployment/runtime form factor of the Node SDK host process itself.
@@ -28,17 +29,19 @@ export type TenantContext = {
     sector: string;
 };
 /**
- * Discovery/bootstrap context for a node operator environment.
+ * Discovery/bootstrap context for a host environment.
  *
- * This describes the operator network/environment itself. It does not replace
+ * This describes the host network/environment itself. It does not replace
  * the tenant route context used by tenant-scoped GW endpoints.
  */
-export type NodeOperatorContext = {
-    networkType: NodeOperatorNetworkType;
+export type HostContext = {
+    networkType: HostNetworkType;
     jurisdiction: string;
     operatorDid?: string;
     baseUrl?: string;
 };
+/** @deprecated Use `HostContext`. */
+export type NodeOperatorContext = HostContext;
 export type NodeFetchLike = typeof fetch;
 /**
  * Node runtime configuration for backend/BFF integrations.
@@ -63,3 +66,4 @@ export type NodePackageStatus = {
     status: 'bootstrap';
 };
 export declare const GDC_SDK_NODE_STATUS: NodePackageStatus;
+export {};

package/dist/runtime-software-proof.d.ts

@@ -0,0 +1,51 @@
+import type { NodeSdkCommunicationIdentityBootstrapResult } from './identity-bootstrap.js';
+export type SoftwareRuntimeCredentialInput = {
+    /**
+     * Public DID of the portal/backend/software runtime profile.
+     */
+    softwareDid: string;
+    /**
+     * Technical communication identity previously created with
+     * `initializeCommunicationIdentity(...)`.
+     */
+    deviceIdentity: NodeSdkCommunicationIdentityBootstrapResult;
+    /**
+     * Optional VC identifier.
+     */
+    credentialId?: string;
+    /**
+     * Optional ICA issuer DID placeholder for examples/tests.
+     */
+    issuerDid?: string;
+    /**
+     * Optional human-readable software/application name.
+     */
+    softwareName?: string;
+    /**
+     * Optional issuance timestamp.
+     */
+    issuanceDate?: string;
+    /**
+     * Optional extra `credentialSubject` claims for profile-specific examples.
+     */
+    additionalCredentialSubject?: Record<string, unknown>;
+};
+export type SoftwareRuntimeCredential = {
+    '@context': string[];
+    type: string[];
+    id?: string;
+    issuer?: string;
+    issuanceDate?: string;
+    credentialSubject: Record<string, unknown>;
+};
+/**
+ * Builds a copy/paste-friendly VC example for an ICA-authorized software or
+ * runtime profile. The key binding is taken from the technical communication
+ * signing key generated by `initializeCommunicationIdentity(...)`.
+ *
+ * This helper is intentionally example-oriented. It wires the runtime
+ * communication `kid` into `credentialSubject.material` so SDK docs and tests
+ * can express the intended future ICA contract without hand-shaping the object
+ * inline every time.
+ */
+export declare function buildSoftwareRuntimeCredential(input: SoftwareRuntimeCredentialInput): SoftwareRuntimeCredential;

package/dist/runtime-software-proof.js

@@ -0,0 +1,34 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Builds a copy/paste-friendly VC example for an ICA-authorized software or
+ * runtime profile. The key binding is taken from the technical communication
+ * signing key generated by `initializeCommunicationIdentity(...)`.
+ *
+ * This helper is intentionally example-oriented. It wires the runtime
+ * communication `kid` into `credentialSubject.material` so SDK docs and tests
+ * can express the intended future ICA contract without hand-shaping the object
+ * inline every time.
+ */
+export function buildSoftwareRuntimeCredential(input) {
+    const communicationKid = String(input.deviceIdentity.commSigningKeyPair.publicJWKey.kid || '').trim();
+    if (!communicationKid) {
+        throw new Error('buildSoftwareRuntimeCredential requires deviceIdentity.commSigningKeyPair.publicJWKey.kid.');
+    }
+    const softwareDid = String(input.softwareDid || '').trim();
+    if (!softwareDid) {
+        throw new Error('buildSoftwareRuntimeCredential requires softwareDid.');
+    }
+    return {
+        '@context': ['https://www.w3.org/2018/credentials/v1', 'https://schema.org'],
+        type: ['VerifiableCredential', 'SoftwareApplicationCredential'],
+        ...(input.credentialId ? { id: input.credentialId } : {}),
+        ...(input.issuerDid ? { issuer: input.issuerDid } : {}),
+        ...(input.issuanceDate ? { issuanceDate: input.issuanceDate } : {}),
+        credentialSubject: {
+            id: softwareDid,
+            material: communicationKid,
+            ...(input.softwareName ? { name: input.softwareName } : {}),
+            ...(input.additionalCredentialSubject || {}),
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",
@@ -17,8 +17,8 @@
     "test:e2e:live-gw": "npm run build && RUN_LIVE_GW_E2E=1 node --test tests/live-gw-node-runtime.e2e.test.mjs"
   },
   "dependencies": {
-    "gdc-common-utils-ts": "^1.9.0",
-    "gdc-sdk-core-ts": "^0.5.0"
+    "gdc-common-utils-ts": "^1.13.0",
+    "gdc-sdk-core-ts": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",