@twin.org/dataspace-control-plane-service 0.0.3-next.44 → 0.0.3-next.46

package/dist/es/models/IDataspaceControlPlaneServiceConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"IDataspaceControlPlaneServiceConfig.js","sourceRoot":"","sources":["../../../src/models/IDataspaceControlPlaneServiceConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Dataspace Control Plane service configuration.\n */\nexport interface IDataspaceControlPlaneServiceConfig {\n\t/**\n\t * Override the default trust generator type for token generation.\n\t * If not specified, the default trust generator configured in the trust component will be used.\n\t */\n\toverrideTrustGeneratorType?: string;\n\n\t/**\n\t * Data plane endpoint path for PULL transfers (path only, not full URL).\n\t * Will be combined with the public origin from the hosting component.\n\t *\n\t * REQUIRED if PULL transfers are supported.\n\t * If not specified, PULL transfers will not be available.\n\t *\n\t * Example: \"data-plane/data\" or \"api/data-plane/data\"\n\t */\n\tdataPlanePath?: string;\n}\n"]}
+{"version":3,"file":"IDataspaceControlPlaneServiceConfig.js","sourceRoot":"","sources":["../../../src/models/IDataspaceControlPlaneServiceConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Dataspace Control Plane service configuration.\n */\nexport interface IDataspaceControlPlaneServiceConfig {\n\t/**\n\t * Override the default trust generator type for token generation.\n\t * If not specified, the default trust generator configured in the trust component will be used.\n\t */\n\toverrideTrustGeneratorType?: string;\n\n\t/**\n\t * Data plane endpoint path for PULL transfers (path only, not full URL).\n\t * Will be combined with the public origin from the hosting component.\n\t *\n\t * REQUIRED if PULL transfers are supported.\n\t * If not specified, PULL transfers will not be available.\n\t *\n\t * Example: \"data-plane/data\" or \"api/data-plane/data\"\n\t */\n\tdataPlanePath?: string;\n\n\t/**\n\t * Control plane callback mount path (path only). Combined with this node's public origin to form the\n\t * consumer callbackAddress a provider POSTs DSP transfer messages back to (e.g.\n\t * `<origin>/<callbackPath>/transfers/:pid/start`), with `?organization=` appended for tenant routing.\n\t *\n\t * Example: \"dataspace\" or \"api/dataspace\".\n\t */\n\tcallbackPath?: string;\n}\n"]}

package/dist/es/restEntryPoints.js

@@ -1,8 +1,7 @@
 import { generateRestRoutesDataspaceControlPlane, tagsDataspaceControlPlane } from "./dataspaceControlPlaneRoutes.js";
 /**
  * Entry points for the REST API.
- * Defines REST routes for DSP protocol only.
- * Resolver methods (IDataspaceControlPlaneResolverComponent).
+ * Defines REST routes for DSP Transfer Process and Contract Negotiation Protocol.
  */
 export const restEntryPoints = [
     {

package/dist/es/restEntryPoints.js.map

@@ -1 +1 @@
-{"version":3,"file":"restEntryPoints.js","sourceRoot":"","sources":["../../src/restEntryPoints.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,uCAAuC,EACvC,yBAAyB,EACzB,MAAM,kCAAkC,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAA2B;IACtD;QACC,IAAI,EAAE,yBAAyB;QAC/B,gBAAgB,EAAE,yBAAyB;QAC3C,IAAI,EAAE,yBAAyB;QAC/B,cAAc,EAAE,uCAAuC;KACvD;CACD,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IRestRouteEntryPoint } from \"@twin.org/api-models\";\nimport {\n\tgenerateRestRoutesDataspaceControlPlane,\n\ttagsDataspaceControlPlane\n} from \"./dataspaceControlPlaneRoutes.js\";\n\n/**\n * Entry points for the REST API.\n * Defines REST routes for DSP protocol only.\n * Resolver methods (IDataspaceControlPlaneResolverComponent).\n */\nexport const restEntryPoints: IRestRouteEntryPoint[] = [\n\t{\n\t\tname: \"dataspace-control-plane\",\n\t\tdefaultBaseRoute: \"dataspace-control-plane\",\n\t\ttags: tagsDataspaceControlPlane,\n\t\tgenerateRoutes: generateRestRoutesDataspaceControlPlane\n\t}\n];\n"]}
+{"version":3,"file":"restEntryPoints.js","sourceRoot":"","sources":["../../src/restEntryPoints.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,uCAAuC,EACvC,yBAAyB,EACzB,MAAM,kCAAkC,CAAC;AAE1C;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAA2B;IACtD;QACC,IAAI,EAAE,yBAAyB;QAC/B,gBAAgB,EAAE,yBAAyB;QAC3C,IAAI,EAAE,yBAAyB;QAC/B,cAAc,EAAE,uCAAuC;KACvD;CACD,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IRestRouteEntryPoint } from \"@twin.org/api-models\";\nimport {\n\tgenerateRestRoutesDataspaceControlPlane,\n\ttagsDataspaceControlPlane\n} from \"./dataspaceControlPlaneRoutes.js\";\n\n/**\n * Entry points for the REST API.\n * Defines REST routes for DSP Transfer Process and Contract Negotiation Protocol.\n */\nexport const restEntryPoints: IRestRouteEntryPoint[] = [\n\t{\n\t\tname: \"dataspace-control-plane\",\n\t\tdefaultBaseRoute: \"dataspace-control-plane\",\n\t\ttags: tagsDataspaceControlPlane,\n\t\tgenerateRoutes: generateRestRoutesDataspaceControlPlane\n\t}\n];\n"]}

package/dist/es/utils/transferErrorUtils.js

@@ -68,9 +68,9 @@ export function isCatalogErrorName(error, errorName) {
     return error.code?.includes(errorName) ?? false;
 }
 /**
- * Check if a CatalogError contains a specific error name in its code.
- * @param error The CatalogError to check.
- * @returns True if the error code contains the specified error name.
+ * Type guard that checks whether an unknown value is a DSP CatalogError.
+ * @param error The value to check.
+ * @returns True if the value has the JSON-LD type of a DSP CatalogError.
  */
 export function isCatalogError(error) {
     return getJsonLdType(error) === DataspaceProtocolCatalogTypes.CatalogError;

package/dist/es/utils/transferErrorUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"transferErrorUtils.js","sourceRoot":"","sources":["../../../src/utils/transferErrorUtils.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAe,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EACN,6BAA6B,EAC7B,yBAAyB,EACzB,qCAAqC,EAGrC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CACvC,KAAc,EACd,IAAqD;IAErD,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAE3C,OAAO;QACN,UAAU,EAAE,CAAC,yBAAyB,CAAC,OAAO,CAAC;QAC/C,OAAO,EAAE,qCAAqC,CAAC,aAAa;QAC5D,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,WAAW;QAC7C,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,WAAW;QAC7C,IAAI,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE;QACpD,MAAM,EAAE,SAAS;KACjB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAe;IACzD,4BAA4B;IAC5B,IACC,EAAE,CAAC,MAAM,CAAkC,MAAM,CAAC;QAClD,MAAM,CAAC,OAAO,CAAC,KAAK,qCAAqC,CAAC,aAAa,EACtE,CAAC;QACF,gDAAgD;QAChD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,OAAO,eAAe,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC;QAC9E,CAAC;QACD,OAAO,cAAc,CAAC,UAAU,CAAC;IAClC,CAAC;IAED,gBAAgB;IAChB,IAAI,EAAE,CAAC,MAAM,CAAS,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7D,OAAO,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC;IACjF,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CACjC,KAAqC,EACrC,SAAiB;IAEjB,OAAO,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC5C,OAAO,aAAa,CAAC,KAAK,CAAC,KAAK,6BAA6B,CAAC,YAAY,CAAC;AAC5E,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { HttpErrorHelper } from \"@twin.org/api-models\";\nimport { BaseError, type IError, Is } from \"@twin.org/core\";\nimport { getJsonLdType } from \"@twin.org/dataspace-models\";\nimport {\n\tDataspaceProtocolCatalogTypes,\n\tDataspaceProtocolContexts,\n\tDataspaceProtocolTransferProcessTypes,\n\ttype IDataspaceProtocolCatalogError,\n\ttype IDataspaceProtocolTransferError\n} from \"@twin.org/standards-dataspace-protocol\";\nimport { HttpStatusCode } from \"@twin.org/web\";\n\n/**\n * Fallback value used when PIDs cannot be extracted from a malformed message.\n * DSP protocol requires consumerPid and providerPid in TransferError responses,\n * so we must provide a value even when the request is completely malformed.\n */\nconst UNKNOWN_PID = \"urn:dsp:unknown\";\n\n/**\n * Transform an error to DS Protocol TransferError format.\n * Used by both service and route layers to ensure consistent error responses.\n * Following the same pattern as Federated Catalogue's catalogErrorUtils.ts.\n * The code property uses semantic format \"ErrorName:message\".\n * The reason property contains the full flattened error chain for debugging.\n * @param error The error to transform.\n * @param pids Optional object containing consumerPid and/or providerPid.\n * @param pids.consumerPid Optional consumer process ID.\n * @param pids.providerPid Optional provider process ID.\n * @returns The TransferError.\n */\nexport function transformToTransferError(\n\terror: unknown,\n\tpids?: { consumerPid?: string; providerPid?: string }\n): IDataspaceProtocolTransferError {\n\tconst flattened = BaseError.flatten(error);\n\n\treturn {\n\t\t\"@context\": [DataspaceProtocolContexts.Context],\n\t\t\"@type\": DataspaceProtocolTransferProcessTypes.TransferError,\n\t\tconsumerPid: pids?.consumerPid ?? UNKNOWN_PID,\n\t\tproviderPid: pids?.providerPid ?? UNKNOWN_PID,\n\t\tcode: `${flattened[0].name}:${flattened[0].message}`,\n\t\treason: flattened\n\t};\n}\n\n/**\n * Transform the DS Protocol result to an HTTP status code.\n * Used by the routes layer to derive HTTP status from TransferError.\n *\n * @param result The result to transform.\n * @returns The transformed status code or undefined if no transformation was found or not an error.\n */\nexport function transformErrorToStatusCode(result: unknown): HttpStatusCode | undefined {\n\t// Is this a transfer error?\n\tif (\n\t\tIs.object<IDataspaceProtocolTransferError>(result) &&\n\t\tresult[\"@type\"] === DataspaceProtocolTransferProcessTypes.TransferError\n\t) {\n\t\t// Extract the error name to map to status codes\n\t\tif (result.code) {\n\t\t\tconst codePart = result.code.split(\":\")[0];\n\t\t\treturn HttpErrorHelper.ERROR_TYPE_MAP[codePart] ?? HttpStatusCode.badRequest;\n\t\t}\n\t\treturn HttpStatusCode.badRequest;\n\t}\n\n\t// Regular error\n\tif (Is.object<IError>(result) && !BaseError.isEmpty(result)) {\n\t\treturn HttpErrorHelper.ERROR_TYPE_MAP[result.name] ?? HttpStatusCode.badRequest;\n\t}\n\n\treturn undefined;\n}\n\n/**\n * Check if a CatalogError contains a specific error name in its code.\n * @param error The CatalogError to check.\n * @param errorName The error name to check for (e.g., NotFoundError.CLASS_NAME).\n * @returns True if the error code contains the specified error name.\n */\nexport function isCatalogErrorName(\n\terror: IDataspaceProtocolCatalogError,\n\terrorName: string\n): boolean {\n\treturn error.code?.includes(errorName) ?? false;\n}\n\n/**\n * Check if a CatalogError contains a specific error name in its code.\n * @param error The CatalogError to check.\n * @returns True if the error code contains the specified error name.\n */\nexport function isCatalogError(error: unknown): error is IDataspaceProtocolCatalogError {\n\treturn getJsonLdType(error) === DataspaceProtocolCatalogTypes.CatalogError;\n}\n"]}
+{"version":3,"file":"transferErrorUtils.js","sourceRoot":"","sources":["../../../src/utils/transferErrorUtils.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAe,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EACN,6BAA6B,EAC7B,yBAAyB,EACzB,qCAAqC,EAGrC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CACvC,KAAc,EACd,IAAqD;IAErD,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAE3C,OAAO;QACN,UAAU,EAAE,CAAC,yBAAyB,CAAC,OAAO,CAAC;QAC/C,OAAO,EAAE,qCAAqC,CAAC,aAAa;QAC5D,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,WAAW;QAC7C,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,WAAW;QAC7C,IAAI,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE;QACpD,MAAM,EAAE,SAAS;KACjB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAe;IACzD,4BAA4B;IAC5B,IACC,EAAE,CAAC,MAAM,CAAkC,MAAM,CAAC;QAClD,MAAM,CAAC,OAAO,CAAC,KAAK,qCAAqC,CAAC,aAAa,EACtE,CAAC;QACF,gDAAgD;QAChD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,OAAO,eAAe,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC;QAC9E,CAAC;QACD,OAAO,cAAc,CAAC,UAAU,CAAC;IAClC,CAAC;IAED,gBAAgB;IAChB,IAAI,EAAE,CAAC,MAAM,CAAS,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7D,OAAO,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC;IACjF,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CACjC,KAAqC,EACrC,SAAiB;IAEjB,OAAO,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC5C,OAAO,aAAa,CAAC,KAAK,CAAC,KAAK,6BAA6B,CAAC,YAAY,CAAC;AAC5E,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { HttpErrorHelper } from \"@twin.org/api-models\";\nimport { BaseError, type IError, Is } from \"@twin.org/core\";\nimport { getJsonLdType } from \"@twin.org/dataspace-models\";\nimport {\n\tDataspaceProtocolCatalogTypes,\n\tDataspaceProtocolContexts,\n\tDataspaceProtocolTransferProcessTypes,\n\ttype IDataspaceProtocolCatalogError,\n\ttype IDataspaceProtocolTransferError\n} from \"@twin.org/standards-dataspace-protocol\";\nimport { HttpStatusCode } from \"@twin.org/web\";\n\n/**\n * Fallback value used when PIDs cannot be extracted from a malformed message.\n * DSP protocol requires consumerPid and providerPid in TransferError responses,\n * so we must provide a value even when the request is completely malformed.\n */\nconst UNKNOWN_PID = \"urn:dsp:unknown\";\n\n/**\n * Transform an error to DS Protocol TransferError format.\n * Used by both service and route layers to ensure consistent error responses.\n * Following the same pattern as Federated Catalogue's catalogErrorUtils.ts.\n * The code property uses semantic format \"ErrorName:message\".\n * The reason property contains the full flattened error chain for debugging.\n * @param error The error to transform.\n * @param pids Optional object containing consumerPid and/or providerPid.\n * @param pids.consumerPid Optional consumer process ID.\n * @param pids.providerPid Optional provider process ID.\n * @returns The TransferError.\n */\nexport function transformToTransferError(\n\terror: unknown,\n\tpids?: { consumerPid?: string; providerPid?: string }\n): IDataspaceProtocolTransferError {\n\tconst flattened = BaseError.flatten(error);\n\n\treturn {\n\t\t\"@context\": [DataspaceProtocolContexts.Context],\n\t\t\"@type\": DataspaceProtocolTransferProcessTypes.TransferError,\n\t\tconsumerPid: pids?.consumerPid ?? UNKNOWN_PID,\n\t\tproviderPid: pids?.providerPid ?? UNKNOWN_PID,\n\t\tcode: `${flattened[0].name}:${flattened[0].message}`,\n\t\treason: flattened\n\t};\n}\n\n/**\n * Transform the DS Protocol result to an HTTP status code.\n * Used by the routes layer to derive HTTP status from TransferError.\n *\n * @param result The result to transform.\n * @returns The transformed status code or undefined if no transformation was found or not an error.\n */\nexport function transformErrorToStatusCode(result: unknown): HttpStatusCode | undefined {\n\t// Is this a transfer error?\n\tif (\n\t\tIs.object<IDataspaceProtocolTransferError>(result) &&\n\t\tresult[\"@type\"] === DataspaceProtocolTransferProcessTypes.TransferError\n\t) {\n\t\t// Extract the error name to map to status codes\n\t\tif (result.code) {\n\t\t\tconst codePart = result.code.split(\":\")[0];\n\t\t\treturn HttpErrorHelper.ERROR_TYPE_MAP[codePart] ?? HttpStatusCode.badRequest;\n\t\t}\n\t\treturn HttpStatusCode.badRequest;\n\t}\n\n\t// Regular error\n\tif (Is.object<IError>(result) && !BaseError.isEmpty(result)) {\n\t\treturn HttpErrorHelper.ERROR_TYPE_MAP[result.name] ?? HttpStatusCode.badRequest;\n\t}\n\n\treturn undefined;\n}\n\n/**\n * Check if a CatalogError contains a specific error name in its code.\n * @param error The CatalogError to check.\n * @param errorName The error name to check for (e.g., NotFoundError.CLASS_NAME).\n * @returns True if the error code contains the specified error name.\n */\nexport function isCatalogErrorName(\n\terror: IDataspaceProtocolCatalogError,\n\terrorName: string\n): boolean {\n\treturn error.code?.includes(errorName) ?? false;\n}\n\n/**\n * Type guard that checks whether an unknown value is a DSP CatalogError.\n * @param error The value to check.\n * @returns True if the value has the JSON-LD type of a DSP CatalogError.\n */\nexport function isCatalogError(error: unknown): error is IDataspaceProtocolCatalogError {\n\treturn getJsonLdType(error) === DataspaceProtocolCatalogTypes.CatalogError;\n}\n"]}

package/dist/types/dataspaceControlPlanePolicyRequester.d.ts

@@ -67,14 +67,14 @@ export declare class DataspaceControlPlanePolicyRequester implements IPolicyRequ
      * A policy finalisation has been sent by a provider.
      * Called by PNP when provider sends a FinalizedEvent.
      * @param negotiationId The id of the negotiation.
-     * @returns Nothing.
+     * @returns A promise that resolves when all finalisation callbacks have been notified.
      */
     finalised(negotiationId: string): Promise<void>;
     /**
      * A policy termination has been sent by a provider.
      * Called by PNP when provider sends a TerminatedMessage or negotiation fails.
      * @param negotiationId The id of the negotiation.
-     * @returns Nothing.
+     * @returns A promise that resolves when all termination callbacks have been notified.
      */
     terminated(negotiationId: string): Promise<void>;
 }

package/dist/types/dataspaceControlPlaneService.d.ts

@@ -49,27 +49,36 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
     /**
      * The service needs to be started when the application is initialized.
      * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when the federated catalogue is populated and the cleanup task is scheduled.
      */
     start(nodeLoggingComponentType?: string): Promise<void>;
     /**
      * Stop the service.
      * Removes the stalled negotiation cleanup task.
      * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when the cleanup task has been removed.
      */
     stop(nodeLoggingComponentType?: string): Promise<void>;
     /**
      * Request a Transfer Process.
      * Creates a new Transfer Process in REQUESTED state.
      * @param request Transfer request message (DSP compliant).
+     * @param publicOrigin The public origin of this provider node, resolved by the REST route from the
+     * hosting component; used to build the data-plane endpoint when auto-starting.
+     * @param options Request options.
+     * @param options.autoStart When true, the provider immediately starts the requested transfer (scheduled
+     * on the next tick); when omitted/false the provider start must be triggered explicitly.
      * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
      * @returns Transfer Process (DSP compliant) with state REQUESTED, or TransferError if the operation fails.
      *
      * Role Performed: Provider
      * Called by: Consumer when it wants to request a new Transfer Process
      */
-    requestTransfer(request: IDataspaceProtocolTransferRequestMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    requestTransfer(request: IDataspaceProtocolTransferRequestMessage, publicOrigin: string, options: {
+        autoStart?: boolean;
+    } | undefined, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
     /**
-     * Start a data transfer as a Consumer.
+     * Prepare a data transfer as a Consumer.
      * Generates a consumerPid, POSTs a TransferRequestMessage to the provider's DSP endpoint,
      * and (only if the provider accepts) persists a local TransferProcess in REQUESTED state.
      * @param agreementId The finalized agreement ID from contract negotiation.
@@ -87,7 +96,7 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
      * registration ignores the runtime `endpoint` arg and silently POSTs to its
      * static endpoint instead.
      */
-    startDataTransfer(agreementId: string, providerEndpoint: string, publicOrigin: string, format: string, trustPayload: unknown): Promise<{
+    prepareTransfer(agreementId: string, providerEndpoint: string, publicOrigin: string, format: string, trustPayload: unknown): Promise<{
         consumerPid: string;
     }>;
     /**
@@ -212,11 +221,13 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
      * @param id The stored dataset id.
      * @param appId The dataspace app this dataset belongs to.
      * @param dataset The dataset payload.
+     * @returns A promise that resolves when the dataset has been updated in storage and the catalogue.
      */
     updateAppDataset(id: string, appId: string, dataset: IDataspaceProtocolDataset): Promise<void>;
     /**
      * Delete a dataspace app dataset owned by the calling organization.
      * @param id The stored app dataset id.
+     * @returns A promise that resolves when the dataset has been removed from storage and the catalogue.
      */
     deleteAppDataset(id: string): Promise<void>;
 }

package/dist/types/models/IDataspaceControlPlaneServiceConfig.d.ts

@@ -17,4 +17,12 @@ export interface IDataspaceControlPlaneServiceConfig {
      * Example: "data-plane/data" or "api/data-plane/data"
      */
     dataPlanePath?: string;
+    /**
+     * Control plane callback mount path (path only). Combined with this node's public origin to form the
+     * consumer callbackAddress a provider POSTs DSP transfer messages back to (e.g.
+     * `<origin>/<callbackPath>/transfers/:pid/start`), with `?organization=` appended for tenant routing.
+     *
+     * Example: "dataspace" or "api/dataspace".
+     */
+    callbackPath?: string;
 }

package/dist/types/restEntryPoints.d.ts

@@ -1,7 +1,6 @@
 import type { IRestRouteEntryPoint } from "@twin.org/api-models";
 /**
  * Entry points for the REST API.
- * Defines REST routes for DSP protocol only.
- * Resolver methods (IDataspaceControlPlaneResolverComponent).
+ * Defines REST routes for DSP Transfer Process and Contract Negotiation Protocol.
  */
 export declare const restEntryPoints: IRestRouteEntryPoint[];

package/dist/types/utils/transferErrorUtils.d.ts

@@ -32,8 +32,8 @@ export declare function transformErrorToStatusCode(result: unknown): HttpStatusC
  */
 export declare function isCatalogErrorName(error: IDataspaceProtocolCatalogError, errorName: string): boolean;
 /**
- * Check if a CatalogError contains a specific error name in its code.
- * @param error The CatalogError to check.
- * @returns True if the error code contains the specified error name.
+ * Type guard that checks whether an unknown value is a DSP CatalogError.
+ * @param error The value to check.
+ * @returns True if the value has the JSON-LD type of a DSP CatalogError.
  */
 export declare function isCatalogError(error: unknown): error is IDataspaceProtocolCatalogError;

package/docs/changelog.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.0.3-next.46](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.45...dataspace-control-plane-service-v0.0.3-next.46) (2026-06-17)
+
+
+### Features
+
+* cross-node transfer callbacks and DataTransferManager auto-start ([#199](https://github.com/iotaledger/twin-dataspace/issues/199)) ([1089aa3](https://github.com/iotaledger/twin-dataspace/commit/1089aa344e3598e382f37a82ca03230c5cf6cacd))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/dataspace-models bumped from 0.0.3-next.45 to 0.0.3-next.46
+
+## [0.0.3-next.45](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.44...dataspace-control-plane-service-v0.0.3-next.45) (2026-06-17)
+
+
+### Bug Fixes
+
+* mock pnap ([35f21f8](https://github.com/iotaledger/twin-dataspace/commit/35f21f847d3fb9d2ffcb9191a18835093cd259b9))
+* use async getStore in tests ([739531e](https://github.com/iotaledger/twin-dataspace/commit/739531e1a159f728301835cd39cf06eab7a7bf4a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/dataspace-models bumped from 0.0.3-next.44 to 0.0.3-next.45
+
 ## [0.0.3-next.44](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.43...dataspace-control-plane-service-v0.0.3-next.44) (2026-06-12)
 
 

package/docs/reference/classes/DataspaceControlPlanePolicyRequester.md

@@ -210,7 +210,7 @@ The id of the negotiation.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when all finalisation callbacks have been notified.
 
 #### Implementation of
 
@@ -237,7 +237,7 @@ The id of the negotiation.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when all termination callbacks have been notified.
 
 #### Implementation of
 

package/docs/reference/classes/DataspaceControlPlaneService.md

@@ -186,6 +186,8 @@ The node logging component type.
 
 `Promise`\<`void`\>
 
+A promise that resolves when the federated catalogue is populated and the cleanup task is scheduled.
+
 #### Implementation of
 
 `IDataspaceControlPlaneComponent.start`
@@ -211,6 +213,8 @@ The node logging component type.
 
 `Promise`\<`void`\>
 
+A promise that resolves when the cleanup task has been removed.
+
 #### Implementation of
 
 `IDataspaceControlPlaneComponent.stop`
@@ -219,7 +223,7 @@ The node logging component type.
 
 ### requestTransfer() {#requesttransfer}
 
-> **requestTransfer**(`request`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
+> **requestTransfer**(`request`, `publicOrigin`, `options`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
 
 Request a Transfer Process.
 Creates a new Transfer Process in REQUESTED state.
@@ -232,6 +236,36 @@ Creates a new Transfer Process in REQUESTED state.
 
 Transfer request message (DSP compliant).
 
+##### publicOrigin
+
+`string`
+
+The public origin of this provider node, resolved by the REST route from the
+hosting component; used to build the data-plane endpoint when auto-starting.
+
+##### options
+
+\{ `autoStart?`: `boolean`; \} \| `undefined`
+
+Request options.
+
+###### Type Literal
+
+\{ `autoStart?`: `boolean`; \}
+
+Request options.
+
+###### autoStart?
+
+`boolean`
+
+When true, the provider immediately starts the requested transfer (scheduled
+on the next tick); when omitted/false the provider start must be triggered explicitly.
+
+***
+
+`undefined`
+
 ##### trustPayload
 
 `unknown`
@@ -253,11 +287,11 @@ Called by: Consumer when it wants to request a new Transfer Process
 
 ***
 
-### startDataTransfer() {#startdatatransfer}
+### prepareTransfer() {#preparetransfer}
 
-> **startDataTransfer**(`agreementId`, `providerEndpoint`, `publicOrigin`, `format`, `trustPayload`): `Promise`\<\{ `consumerPid`: `string`; \}\>
+> **prepareTransfer**(`agreementId`, `providerEndpoint`, `publicOrigin`, `format`, `trustPayload`): `Promise`\<\{ `consumerPid`: `string`; \}\>
 
-Start a data transfer as a Consumer.
+Prepare a data transfer as a Consumer.
 Generates a consumerPid, POSTs a TransferRequestMessage to the provider's DSP endpoint,
 and (only if the provider accepts) persists a local TransferProcess in REQUESTED state.
 
@@ -309,7 +343,7 @@ static endpoint instead.
 
 #### Implementation of
 
-`IDataspaceControlPlaneComponent.startDataTransfer`
+`IDataspaceControlPlaneComponent.prepareTransfer`
 
 ***
 
@@ -795,6 +829,8 @@ The dataset payload.
 
 `Promise`\<`void`\>
 
+A promise that resolves when the dataset has been updated in storage and the catalogue.
+
 #### Implementation of
 
 `IDataspaceControlPlaneComponent.updateAppDataset`
@@ -819,6 +855,8 @@ The stored app dataset id.
 
 `Promise`\<`void`\>
 
+A promise that resolves when the dataset has been removed from storage and the catalogue.
+
 #### Implementation of
 
 `IDataspaceControlPlaneComponent.deleteAppDataset`

package/docs/reference/interfaces/IDataspaceControlPlaneServiceConfig.md

@@ -24,3 +24,15 @@ REQUIRED if PULL transfers are supported.
 If not specified, PULL transfers will not be available.
 
 Example: "data-plane/data" or "api/data-plane/data"
+
+***
+
+### callbackPath? {#callbackpath}
+
+> `optional` **callbackPath?**: `string`
+
+Control plane callback mount path (path only). Combined with this node's public origin to form the
+consumer callbackAddress a provider POSTs DSP transfer messages back to (e.g.
+`<origin>/<callbackPath>/transfers/:pid/start`), with `?organization=` appended for tenant routing.
+
+Example: "dataspace" or "api/dataspace".

package/docs/reference/variables/restEntryPoints.md

@@ -3,5 +3,4 @@
 > `const` **restEntryPoints**: `IRestRouteEntryPoint`[]
 
 Entry points for the REST API.
-Defines REST routes for DSP protocol only.
-Resolver methods (IDataspaceControlPlaneResolverComponent).
+Defines REST routes for DSP Transfer Process and Contract Negotiation Protocol.

package/locales/en.json

@@ -23,8 +23,8 @@
 			"negotiationHistoryRetrieved": "Negotiation history retrieved successfully",
 			"stalledNegotiationsCleanupComplete": "Stalled negotiations cleanup completed (cleanedUp: {cleanedUp})",
 			"pushTransferStarted": "PUSH transfer started (consumerPid: {consumerPid}, providerPid: {providerPid}, endpoint: {endpoint})",
-			"startingDataTransfer": "Starting consumer-initiated data transfer (agreementId: {agreementId}, providerEndpoint: {providerEndpoint}, format: {format})",
-			"dataTransferStarted": "Consumer data transfer started successfully (consumerPid: {consumerPid}, providerPid: {providerPid}, agreementId: {agreementId}, format: {format})"
+			"preparingTransfer": "Preparing consumer-initiated data transfer (agreementId: {agreementId}, providerEndpoint: {providerEndpoint}, format: {format})",
+			"transferPrepared": "Consumer data transfer prepared successfully (consumerPid: {consumerPid}, providerPid: {providerPid}, agreementId: {agreementId}, format: {format})"
 		},
 		"dataspaceControlPlanePolicyRequester": {
 			"offerReceived": "Offer received from provider (negotiationId: {negotiationId}, offerId: {offerId})",
@@ -53,6 +53,10 @@
 	},
 	"error": {
 		"dataspaceControlPlaneService": {
+			"transferCallbackRejected": "Consumer rejected a transfer state-change callback (messageKind: {messageKind}, consumerPid: {consumerPid}, providerPid: {providerPid}, callbackAddress: {callbackAddress})",
+			"transferCallbackFailed": "Failed to deliver a transfer state-change callback to the consumer (messageKind: {messageKind}, consumerPid: {consumerPid}, providerPid: {providerPid}, callbackAddress: {callbackAddress})",
+			"autoStartFailed": "Provider auto-start of a requested transfer failed (consumerPid: {consumerPid})",
+			"autoStartPublicOriginMissing": "Cannot auto-start the transfer: this node's public origin could not be resolved; holding the transfer in REQUESTED (consumerPid: {consumerPid})",
 			"transferProcessNotFound": "Transfer Process not found",
 			"pullTransfersNotSupported": "PULL transfers are not supported. Configure dataPlanePath in service configuration to enable PULL transfers.",
 			"transferProcessTerminated": "Transfer Process \"{consumerPid}\" is terminated and cannot be used",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/dataspace-control-plane-service",
-	"version": "0.0.3-next.44",
+	"version": "0.0.3-next.46",
 	"description": "Implements agreement negotiation and transfer process lifecycle management for control plane operations.",
 	"repository": {
 		"type": "git",
@@ -19,7 +19,7 @@
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",
-		"@twin.org/dataspace-models": "0.0.3-next.44",
+		"@twin.org/dataspace-models": "0.0.3-next.46",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/federated-catalogue-models": "next",