@twin.org/dataspace-control-plane-service 0.9.0 → 0.9.1-next.10

package/dist/es/factories/transferHandlerFactory.js

@@ -0,0 +1,11 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Factory } from "@twin.org/core";
+/**
+ * Factory for registering and retrieving format-specific ITransferHandler instances.
+ * Keys are DataspaceTransferFormat values (e.g. "HttpData-PULL").
+ * Throws GeneralError when get() is called with an unregistered format.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const TransferHandlerFactory = Factory.createFactory("transfer-handler");
+//# sourceMappingURL=transferHandlerFactory.js.map

package/dist/es/factories/transferHandlerFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferHandlerFactory.js","sourceRoot":"","sources":["../../../src/factories/transferHandlerFactory.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC;;;;GAIG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAmB,kBAAkB,CAAC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Factory } from \"@twin.org/core\";\nimport type { ITransferHandler } from \"../models/ITransferHandler.js\";\n\n/**\n * Factory for registering and retrieving format-specific ITransferHandler instances.\n * Keys are DataspaceTransferFormat values (e.g. \"HttpData-PULL\").\n * Throws GeneralError when get() is called with an unregistered format.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const TransferHandlerFactory = Factory.createFactory<ITransferHandler>(\"transfer-handler\");\n"]}

package/dist/es/handlers/httpDataPostTransferHandler.js

@@ -0,0 +1,111 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { HttpUrlHelper } from "@twin.org/api-models";
+import { ContextIdKeys } from "@twin.org/context";
+import { GeneralError, Guards, Is } from "@twin.org/core";
+import { DataspaceProtocolEndpointType, DataspaceProtocolTransferProcessTypes } from "@twin.org/standards-dataspace-protocol";
+import { EndpointProperties } from "../models/endpointProperties.js";
+/**
+ * Transfer handler for HttpData-POST format (provider-initiated push).
+ * The consumer does not supply a dataAddress. The provider returns its own /inbox URL
+ * along with a signed JWT so the consumer can authenticate when posting activities there.
+ */
+export class HttpDataPostTransferHandler {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "HttpDataPostTransferHandler";
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className() {
+        return HttpDataPostTransferHandler.CLASS_NAME;
+    }
+    /**
+     * POST consumers do not supply a dataAddress — provider returns its own /inbox on start.
+     * @param ctx Prepare context (unused for POST).
+     * @returns undefined.
+     */
+    buildConsumerDataAddress(ctx) {
+        return undefined;
+    }
+    /**
+     * Build the provider's /inbox dataAddress and signed JWT for the TransferStartMessage.
+     * @param ctx Start context containing entity, trust component, and path configuration.
+     * @returns The provider's ActivityStream inbox dataAddress with bearer token.
+     * @throws GeneralError When dataPlanePath is not configured or providerIdentity is missing.
+     */
+    async buildProviderStartDataAddress(ctx) {
+        const { entity, publicOrigin, dataPlanePath, organizationIdentity, trustComponent, overrideTrustGeneratorType } = ctx;
+        if (!Is.stringValue(dataPlanePath)) {
+            throw new GeneralError(HttpDataPostTransferHandler.CLASS_NAME, "pushTransferDataPathNotConfigured", { consumerPid: entity.consumerPid });
+        }
+        if (!Is.stringValue(entity.providerIdentity)) {
+            throw new GeneralError(HttpDataPostTransferHandler.CLASS_NAME, "providerIdentityMissing");
+        }
+        const accessToken = await trustComponent.generate(entity.providerIdentity, overrideTrustGeneratorType, {
+            subject: {
+                consumerPid: entity.consumerPid,
+                providerPid: entity.providerPid,
+                agreementId: entity.agreementId,
+                datasetId: entity.datasetId
+            }
+        });
+        Guards.stringValue(HttpDataPostTransferHandler.CLASS_NAME, "accessToken", accessToken);
+        const fullEndpoint = HttpUrlHelper.addQueryStringParam(`${publicOrigin}/${dataPlanePath}/inbox`, ContextIdKeys.Organization, organizationIdentity);
+        return {
+            "@type": DataspaceProtocolTransferProcessTypes.DataAddress,
+            endpointType: DataspaceProtocolEndpointType.HttpsActivityStreamEndpoint,
+            endpoint: fullEndpoint,
+            endpointProperties: [
+                {
+                    "@type": DataspaceProtocolTransferProcessTypes.EndpointProperty,
+                    name: EndpointProperties.Authorization,
+                    value: accessToken
+                },
+                {
+                    "@type": DataspaceProtocolTransferProcessTypes.EndpointProperty,
+                    name: EndpointProperties.AuthType,
+                    value: "bearer"
+                }
+            ]
+        };
+    }
+    /**
+     * No-op: POST transfers do not involve a provider-managed push subscription on start.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @param previousState The state before the STARTED transition.
+     * @returns A promise that resolves immediately.
+     */
+    async onProviderStart(dataPlaneComponent, consumerPid, previousState) { }
+    /**
+     * Tear down the data plane subscription when the transfer completes.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves when the subscription is torn down.
+     */
+    async onComplete(dataPlaneComponent, consumerPid) {
+        await dataPlaneComponent.teardownPushSubscription(consumerPid);
+    }
+    /**
+     * Suspend the data plane subscription when the transfer is suspended.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves when the subscription is suspended.
+     */
+    async onSuspend(dataPlaneComponent, consumerPid) {
+        await dataPlaneComponent.suspendPushSubscription(consumerPid);
+    }
+    /**
+     * Tear down the data plane subscription when the transfer terminates.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves when the subscription is torn down.
+     */
+    async onTerminate(dataPlaneComponent, consumerPid) {
+        await dataPlaneComponent.teardownPushSubscription(consumerPid);
+    }
+}
+//# sourceMappingURL=httpDataPostTransferHandler.js.map

package/dist/es/handlers/httpDataPostTransferHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpDataPostTransferHandler.js","sourceRoot":"","sources":["../../../src/handlers/httpDataPostTransferHandler.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { HttpUrlHelper } from \"@twin.org/api-models\";\nimport { ContextIdKeys } from \"@twin.org/context\";\nimport { GeneralError, Guards, Is } from \"@twin.org/core\";\nimport type { IDataspaceDataPlaneComponent } from \"@twin.org/dataspace-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport {\n\tDataspaceProtocolEndpointType,\n\tDataspaceProtocolTransferProcessTypes\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type {\n\tDataspaceProtocolTransferProcessStateType,\n\tIDataspaceProtocolDataAddress\n} from \"@twin.org/standards-dataspace-protocol\";\nimport { EndpointProperties } from \"../models/endpointProperties.js\";\nimport type { ITransferHandler } from \"../models/ITransferHandler.js\";\nimport type { ITransferHandlerPrepareContext } from \"../models/ITransferHandlerPrepareContext.js\";\nimport type { ITransferHandlerStartContext } from \"../models/ITransferHandlerStartContext.js\";\n\n/**\n * Transfer handler for HttpData-POST format (provider-initiated push).\n * The consumer does not supply a dataAddress. The provider returns its own /inbox URL\n * along with a signed JWT so the consumer can authenticate when posting activities there.\n */\nexport class HttpDataPostTransferHandler implements ITransferHandler {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<HttpDataPostTransferHandler>();\n\n\t/**\n\t * Returns the class name of the component.\n\t * @returns The class name of the component.\n\t */\n\tpublic className(): string {\n\t\treturn HttpDataPostTransferHandler.CLASS_NAME;\n\t}\n\n\t/**\n\t * POST consumers do not supply a dataAddress — provider returns its own /inbox on start.\n\t * @param ctx Prepare context (unused for POST).\n\t * @returns undefined.\n\t */\n\tpublic buildConsumerDataAddress(\n\t\tctx: ITransferHandlerPrepareContext\n\t): IDataspaceProtocolDataAddress | undefined {\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Build the provider's /inbox dataAddress and signed JWT for the TransferStartMessage.\n\t * @param ctx Start context containing entity, trust component, and path configuration.\n\t * @returns The provider's ActivityStream inbox dataAddress with bearer token.\n\t * @throws GeneralError When dataPlanePath is not configured or providerIdentity is missing.\n\t */\n\tpublic async buildProviderStartDataAddress(\n\t\tctx: ITransferHandlerStartContext\n\t): Promise<IDataspaceProtocolDataAddress | undefined> {\n\t\tconst {\n\t\t\tentity,\n\t\t\tpublicOrigin,\n\t\t\tdataPlanePath,\n\t\t\torganizationIdentity,\n\t\t\ttrustComponent,\n\t\t\toverrideTrustGeneratorType\n\t\t} = ctx;\n\n\t\tif (!Is.stringValue(dataPlanePath)) {\n\t\t\tthrow new GeneralError(\n\t\t\t\tHttpDataPostTransferHandler.CLASS_NAME,\n\t\t\t\t\"pushTransferDataPathNotConfigured\",\n\t\t\t\t{ consumerPid: entity.consumerPid }\n\t\t\t);\n\t\t}\n\n\t\tif (!Is.stringValue(entity.providerIdentity)) {\n\t\t\tthrow new GeneralError(HttpDataPostTransferHandler.CLASS_NAME, \"providerIdentityMissing\");\n\t\t}\n\n\t\tconst accessToken = await trustComponent.generate(\n\t\t\tentity.providerIdentity,\n\t\t\toverrideTrustGeneratorType,\n\t\t\t{\n\t\t\t\tsubject: {\n\t\t\t\t\tconsumerPid: entity.consumerPid,\n\t\t\t\t\tproviderPid: entity.providerPid,\n\t\t\t\t\tagreementId: entity.agreementId,\n\t\t\t\t\tdatasetId: entity.datasetId\n\t\t\t\t}\n\t\t\t}\n\t\t);\n\n\t\tGuards.stringValue(HttpDataPostTransferHandler.CLASS_NAME, nameof(accessToken), accessToken);\n\n\t\tconst fullEndpoint = HttpUrlHelper.addQueryStringParam(\n\t\t\t`${publicOrigin}/${dataPlanePath}/inbox`,\n\t\t\tContextIdKeys.Organization,\n\t\t\torganizationIdentity\n\t\t);\n\n\t\treturn {\n\t\t\t\"@type\": DataspaceProtocolTransferProcessTypes.DataAddress,\n\t\t\tendpointType: DataspaceProtocolEndpointType.HttpsActivityStreamEndpoint,\n\t\t\tendpoint: fullEndpoint,\n\t\t\tendpointProperties: [\n\t\t\t\t{\n\t\t\t\t\t\"@type\": DataspaceProtocolTransferProcessTypes.EndpointProperty,\n\t\t\t\t\tname: EndpointProperties.Authorization,\n\t\t\t\t\tvalue: accessToken\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"@type\": DataspaceProtocolTransferProcessTypes.EndpointProperty,\n\t\t\t\t\tname: EndpointProperties.AuthType,\n\t\t\t\t\tvalue: \"bearer\"\n\t\t\t\t}\n\t\t\t]\n\t\t};\n\t}\n\n\t/**\n\t * No-op: POST transfers do not involve a provider-managed push subscription on start.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @param previousState The state before the STARTED transition.\n\t * @returns A promise that resolves immediately.\n\t */\n\tpublic async onProviderStart(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string,\n\t\tpreviousState: DataspaceProtocolTransferProcessStateType\n\t): Promise<void> {}\n\n\t/**\n\t * Tear down the data plane subscription when the transfer completes.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves when the subscription is torn down.\n\t */\n\tpublic async onComplete(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string\n\t): Promise<void> {\n\t\tawait dataPlaneComponent.teardownPushSubscription(consumerPid);\n\t}\n\n\t/**\n\t * Suspend the data plane subscription when the transfer is suspended.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves when the subscription is suspended.\n\t */\n\tpublic async onSuspend(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string\n\t): Promise<void> {\n\t\tawait dataPlaneComponent.suspendPushSubscription(consumerPid);\n\t}\n\n\t/**\n\t * Tear down the data plane subscription when the transfer terminates.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves when the subscription is torn down.\n\t */\n\tpublic async onTerminate(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string\n\t): Promise<void> {\n\t\tawait dataPlaneComponent.teardownPushSubscription(consumerPid);\n\t}\n}\n"]}

package/dist/es/handlers/httpDataPullTransferHandler.js

@@ -0,0 +1,108 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { HttpUrlHelper } from "@twin.org/api-models";
+import { ContextIdKeys } from "@twin.org/context";
+import { GeneralError, Guards, Is } from "@twin.org/core";
+import { DataspaceProtocolEndpointType, DataspaceProtocolTransferProcessTypes } from "@twin.org/standards-dataspace-protocol";
+import { EndpointProperties } from "../models/endpointProperties.js";
+/**
+ * Transfer handler for HttpData-PULL format.
+ * Consumer queries the provider's data endpoint using a bearer token supplied in the
+ * TransferStartMessage dataAddress. No data-plane push subscription is involved.
+ */
+export class HttpDataPullTransferHandler {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "HttpDataPullTransferHandler";
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className() {
+        return HttpDataPullTransferHandler.CLASS_NAME;
+    }
+    /**
+     * PULL consumers do not supply a dataAddress — the provider generates one on start.
+     * @param ctx Prepare context (unused for PULL).
+     * @returns undefined.
+     */
+    buildConsumerDataAddress(ctx) {
+        return undefined;
+    }
+    /**
+     * Build the provider's data endpoint and bearer token for the TransferStartMessage.
+     * @param ctx Start context containing entity, trust component, and path configuration.
+     * @returns The dataAddress carrying the query endpoint and bearer token.
+     * @throws GeneralError When dataPlanePath is not configured or providerIdentity is missing.
+     */
+    async buildProviderStartDataAddress(ctx) {
+        const { entity, publicOrigin, dataPlanePath, organizationIdentity, trustComponent, overrideTrustGeneratorType } = ctx;
+        if (!Is.stringValue(dataPlanePath)) {
+            throw new GeneralError(HttpDataPullTransferHandler.CLASS_NAME, "pullTransfersNotSupported", {
+                consumerPid: entity.consumerPid,
+                providerPid: entity.providerPid
+            });
+        }
+        if (!Is.stringValue(entity.providerIdentity)) {
+            throw new GeneralError(HttpDataPullTransferHandler.CLASS_NAME, "providerIdentityMissing");
+        }
+        const accessToken = await trustComponent.generate(entity.providerIdentity, overrideTrustGeneratorType, {
+            subject: {
+                consumerPid: entity.consumerPid,
+                providerPid: entity.providerPid,
+                agreementId: entity.agreementId,
+                datasetId: entity.datasetId
+            }
+        });
+        Guards.stringValue(HttpDataPullTransferHandler.CLASS_NAME, "accessToken", accessToken);
+        const fullEndpoint = HttpUrlHelper.addQueryStringParam(`${publicOrigin}/${dataPlanePath}/entities`, ContextIdKeys.Organization, organizationIdentity);
+        return {
+            "@type": DataspaceProtocolTransferProcessTypes.DataAddress,
+            endpointType: DataspaceProtocolEndpointType.HttpsQueryEndpoint,
+            endpoint: fullEndpoint,
+            endpointProperties: [
+                {
+                    "@type": DataspaceProtocolTransferProcessTypes.EndpointProperty,
+                    name: EndpointProperties.Authorization,
+                    value: accessToken
+                },
+                {
+                    "@type": DataspaceProtocolTransferProcessTypes.EndpointProperty,
+                    name: EndpointProperties.AuthType,
+                    value: "bearer"
+                }
+            ]
+        };
+    }
+    /**
+     * No-op: PULL transfers require no push subscription.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @param previousState The state before the STARTED transition.
+     * @returns A promise that resolves immediately.
+     */
+    async onProviderStart(dataPlaneComponent, consumerPid, previousState) { }
+    /**
+     * No-op: PULL transfers have no push subscription to tear down.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves immediately.
+     */
+    async onComplete(dataPlaneComponent, consumerPid) { }
+    /**
+     * No-op: PULL transfers have no push subscription to suspend.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves immediately.
+     */
+    async onSuspend(dataPlaneComponent, consumerPid) { }
+    /**
+     * No-op: PULL transfers have no push subscription to tear down.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves immediately.
+     */
+    async onTerminate(dataPlaneComponent, consumerPid) { }
+}
+//# sourceMappingURL=httpDataPullTransferHandler.js.map

package/dist/es/handlers/httpDataPullTransferHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpDataPullTransferHandler.js","sourceRoot":"","sources":["../../../src/handlers/httpDataPullTransferHandler.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAG1D,OAAO,EACN,6BAA6B,EAC7B,qCAAqC,EACrC,MAAM,wCAAwC,CAAC;AAKhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAKrE;;;;GAIG;AACH,MAAM,OAAO,2BAA2B;IACvC;;OAEG;IACI,MAAM,CAAU,UAAU,iCAAiD;IAElF;;;OAGG;IACI,SAAS;QACf,OAAO,2BAA2B,CAAC,UAAU,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACI,wBAAwB,CAC9B,GAAmC;QAEnC,OAAO,SAAS,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,6BAA6B,CACzC,GAAiC;QAEjC,MAAM,EACL,MAAM,EACN,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,0BAA0B,EAC1B,GAAG,GAAG,CAAC;QAER,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,YAAY,CAAC,2BAA2B,CAAC,UAAU,EAAE,2BAA2B,EAAE;gBAC3F,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;aAC/B,CAAC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,YAAY,CAAC,2BAA2B,CAAC,UAAU,EAAE,yBAAyB,CAAC,CAAC;QAC3F,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,cAAc,CAAC,QAAQ,CAChD,MAAM,CAAC,gBAAgB,EACvB,0BAA0B,EAC1B;YACC,OAAO,EAAE;gBACR,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;aAC3B;SACD,CACD,CAAC;QAEF,MAAM,CAAC,WAAW,CAAC,2BAA2B,CAAC,UAAU,iBAAuB,WAAW,CAAC,CAAC;QAE7F,MAAM,YAAY,GAAG,aAAa,CAAC,mBAAmB,CACrD,GAAG,YAAY,IAAI,aAAa,WAAW,EAC3C,aAAa,CAAC,YAAY,EAC1B,oBAAoB,CACpB,CAAC;QAEF,OAAO;YACN,OAAO,EAAE,qCAAqC,CAAC,WAAW;YAC1D,YAAY,EAAE,6BAA6B,CAAC,kBAAkB;YAC9D,QAAQ,EAAE,YAAY;YACtB,kBAAkB,EAAE;gBACnB;oBACC,OAAO,EAAE,qCAAqC,CAAC,gBAAgB;oBAC/D,IAAI,EAAE,kBAAkB,CAAC,aAAa;oBACtC,KAAK,EAAE,WAAW;iBAClB;gBACD;oBACC,OAAO,EAAE,qCAAqC,CAAC,gBAAgB;oBAC/D,IAAI,EAAE,kBAAkB,CAAC,QAAQ;oBACjC,KAAK,EAAE,QAAQ;iBACf;aACD;SACD,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,eAAe,CAC3B,kBAAgD,EAChD,WAAmB,EACnB,aAAwD,IACvC,CAAC;IAEnB;;;;;OAKG;IACI,KAAK,CAAC,UAAU,CACtB,kBAAgD,EAChD,WAAmB,IACF,CAAC;IAEnB;;;;;OAKG;IACI,KAAK,CAAC,SAAS,CACrB,kBAAgD,EAChD,WAAmB,IACF,CAAC;IAEnB;;;;;OAKG;IACI,KAAK,CAAC,WAAW,CACvB,kBAAgD,EAChD,WAAmB,IACF,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { HttpUrlHelper } from \"@twin.org/api-models\";\nimport { ContextIdKeys } from \"@twin.org/context\";\nimport { GeneralError, Guards, Is } from \"@twin.org/core\";\nimport type { IDataspaceDataPlaneComponent } from \"@twin.org/dataspace-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport {\n\tDataspaceProtocolEndpointType,\n\tDataspaceProtocolTransferProcessTypes\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type {\n\tDataspaceProtocolTransferProcessStateType,\n\tIDataspaceProtocolDataAddress\n} from \"@twin.org/standards-dataspace-protocol\";\nimport { EndpointProperties } from \"../models/endpointProperties.js\";\nimport type { ITransferHandler } from \"../models/ITransferHandler.js\";\nimport type { ITransferHandlerPrepareContext } from \"../models/ITransferHandlerPrepareContext.js\";\nimport type { ITransferHandlerStartContext } from \"../models/ITransferHandlerStartContext.js\";\n\n/**\n * Transfer handler for HttpData-PULL format.\n * Consumer queries the provider's data endpoint using a bearer token supplied in the\n * TransferStartMessage dataAddress. No data-plane push subscription is involved.\n */\nexport class HttpDataPullTransferHandler implements ITransferHandler {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<HttpDataPullTransferHandler>();\n\n\t/**\n\t * Returns the class name of the component.\n\t * @returns The class name of the component.\n\t */\n\tpublic className(): string {\n\t\treturn HttpDataPullTransferHandler.CLASS_NAME;\n\t}\n\n\t/**\n\t * PULL consumers do not supply a dataAddress — the provider generates one on start.\n\t * @param ctx Prepare context (unused for PULL).\n\t * @returns undefined.\n\t */\n\tpublic buildConsumerDataAddress(\n\t\tctx: ITransferHandlerPrepareContext\n\t): IDataspaceProtocolDataAddress | undefined {\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Build the provider's data endpoint and bearer token for the TransferStartMessage.\n\t * @param ctx Start context containing entity, trust component, and path configuration.\n\t * @returns The dataAddress carrying the query endpoint and bearer token.\n\t * @throws GeneralError When dataPlanePath is not configured or providerIdentity is missing.\n\t */\n\tpublic async buildProviderStartDataAddress(\n\t\tctx: ITransferHandlerStartContext\n\t): Promise<IDataspaceProtocolDataAddress | undefined> {\n\t\tconst {\n\t\t\tentity,\n\t\t\tpublicOrigin,\n\t\t\tdataPlanePath,\n\t\t\torganizationIdentity,\n\t\t\ttrustComponent,\n\t\t\toverrideTrustGeneratorType\n\t\t} = ctx;\n\n\t\tif (!Is.stringValue(dataPlanePath)) {\n\t\t\tthrow new GeneralError(HttpDataPullTransferHandler.CLASS_NAME, \"pullTransfersNotSupported\", {\n\t\t\t\tconsumerPid: entity.consumerPid,\n\t\t\t\tproviderPid: entity.providerPid\n\t\t\t});\n\t\t}\n\n\t\tif (!Is.stringValue(entity.providerIdentity)) {\n\t\t\tthrow new GeneralError(HttpDataPullTransferHandler.CLASS_NAME, \"providerIdentityMissing\");\n\t\t}\n\n\t\tconst accessToken = await trustComponent.generate(\n\t\t\tentity.providerIdentity,\n\t\t\toverrideTrustGeneratorType,\n\t\t\t{\n\t\t\t\tsubject: {\n\t\t\t\t\tconsumerPid: entity.consumerPid,\n\t\t\t\t\tproviderPid: entity.providerPid,\n\t\t\t\t\tagreementId: entity.agreementId,\n\t\t\t\t\tdatasetId: entity.datasetId\n\t\t\t\t}\n\t\t\t}\n\t\t);\n\n\t\tGuards.stringValue(HttpDataPullTransferHandler.CLASS_NAME, nameof(accessToken), accessToken);\n\n\t\tconst fullEndpoint = HttpUrlHelper.addQueryStringParam(\n\t\t\t`${publicOrigin}/${dataPlanePath}/entities`,\n\t\t\tContextIdKeys.Organization,\n\t\t\torganizationIdentity\n\t\t);\n\n\t\treturn {\n\t\t\t\"@type\": DataspaceProtocolTransferProcessTypes.DataAddress,\n\t\t\tendpointType: DataspaceProtocolEndpointType.HttpsQueryEndpoint,\n\t\t\tendpoint: fullEndpoint,\n\t\t\tendpointProperties: [\n\t\t\t\t{\n\t\t\t\t\t\"@type\": DataspaceProtocolTransferProcessTypes.EndpointProperty,\n\t\t\t\t\tname: EndpointProperties.Authorization,\n\t\t\t\t\tvalue: accessToken\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"@type\": DataspaceProtocolTransferProcessTypes.EndpointProperty,\n\t\t\t\t\tname: EndpointProperties.AuthType,\n\t\t\t\t\tvalue: \"bearer\"\n\t\t\t\t}\n\t\t\t]\n\t\t};\n\t}\n\n\t/**\n\t * No-op: PULL transfers require no push subscription.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @param previousState The state before the STARTED transition.\n\t * @returns A promise that resolves immediately.\n\t */\n\tpublic async onProviderStart(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string,\n\t\tpreviousState: DataspaceProtocolTransferProcessStateType\n\t): Promise<void> {}\n\n\t/**\n\t * No-op: PULL transfers have no push subscription to tear down.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves immediately.\n\t */\n\tpublic async onComplete(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string\n\t): Promise<void> {}\n\n\t/**\n\t * No-op: PULL transfers have no push subscription to suspend.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves immediately.\n\t */\n\tpublic async onSuspend(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string\n\t): Promise<void> {}\n\n\t/**\n\t * No-op: PULL transfers have no push subscription to tear down.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves immediately.\n\t */\n\tpublic async onTerminate(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string\n\t): Promise<void> {}\n}\n"]}

package/dist/es/handlers/httpDataPushTransferHandler.js

@@ -0,0 +1,114 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { HttpUrlHelper } from "@twin.org/api-models";
+import { ContextIdKeys } from "@twin.org/context";
+import { GeneralError, Is } from "@twin.org/core";
+import { DataspaceProtocolEndpointType, DataspaceProtocolTransferProcessStateType, DataspaceProtocolTransferProcessTypes } from "@twin.org/standards-dataspace-protocol";
+/**
+ * Transfer handler for HttpData-PUSH format (consumer-initiated push).
+ * The consumer supplies its /inbox endpoint in the TransferRequestMessage dataAddress.
+ * The provider pushes ActivityStreams objects to that endpoint, and returns its own
+ * /inbox in the TransferStartMessage so the consumer can route data notifications.
+ */
+export class HttpDataPushTransferHandler {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "HttpDataPushTransferHandler";
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className() {
+        return HttpDataPushTransferHandler.CLASS_NAME;
+    }
+    /**
+     * Build the consumer's /inbox dataAddress for the TransferRequestMessage.
+     * @param ctx Prepare context containing path and organization identity.
+     * @returns The consumer's ActivityStream inbox dataAddress.
+     * @throws GeneralError When dataPlanePath is not configured.
+     */
+    buildConsumerDataAddress(ctx) {
+        const { consumerPid, origin, dataPlanePath, organizationIdentity } = ctx;
+        if (!Is.stringValue(dataPlanePath)) {
+            throw new GeneralError(HttpDataPushTransferHandler.CLASS_NAME, "pushTransferDataPathNotConfigured", {
+                consumerPid
+            });
+        }
+        const inboxEndpoint = HttpUrlHelper.addQueryStringParam(`${origin}/${dataPlanePath}/inbox`, ContextIdKeys.Organization, organizationIdentity);
+        return {
+            "@type": DataspaceProtocolTransferProcessTypes.DataAddress,
+            endpointType: DataspaceProtocolEndpointType.HttpsActivityStreamEndpoint,
+            endpoint: inboxEndpoint
+        };
+    }
+    /**
+     * Validate the consumer's dataAddress and build the provider's /inbox endpoint
+     * for the TransferStartMessage. No bearer token is included — the consumer authenticates
+     * via the DSP protocol trust payload on the push POST.
+     * @param ctx Start context containing entity and path configuration.
+     * @returns The provider's ActivityStream inbox dataAddress.
+     * @throws GeneralError When the consumer dataAddress is invalid or dataPlanePath is not configured.
+     */
+    async buildProviderStartDataAddress(ctx) {
+        const { entity, publicOrigin, dataPlanePath, organizationIdentity } = ctx;
+        if (!Is.stringValue(entity.dataAddress?.endpoint) ||
+            !Is.stringValue(entity.dataAddress?.endpointType)) {
+            throw new GeneralError(HttpDataPushTransferHandler.CLASS_NAME, "invalidPushDataAddress", {
+                consumerPid: entity.consumerPid
+            });
+        }
+        if (!Is.stringValue(dataPlanePath)) {
+            throw new GeneralError(HttpDataPushTransferHandler.CLASS_NAME, "pushTransferDataPathNotConfigured", { consumerPid: entity.consumerPid });
+        }
+        const fullEndpoint = HttpUrlHelper.addQueryStringParam(`${publicOrigin}/${dataPlanePath}/inbox`, ContextIdKeys.Organization, organizationIdentity);
+        return {
+            "@type": DataspaceProtocolTransferProcessTypes.DataAddress,
+            endpointType: DataspaceProtocolEndpointType.HttpsActivityStreamEndpoint,
+            endpoint: fullEndpoint
+        };
+    }
+    /**
+     * Set up (or resume) the data-plane push subscription after state is persisted to STARTED.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @param previousState The state before the STARTED transition.
+     * @returns A promise that resolves when the subscription is established.
+     */
+    async onProviderStart(dataPlaneComponent, consumerPid, previousState) {
+        if (previousState === DataspaceProtocolTransferProcessStateType.REQUESTED) {
+            await dataPlaneComponent.setupPushSubscription(consumerPid);
+        }
+        else if (previousState === DataspaceProtocolTransferProcessStateType.SUSPENDED) {
+            await dataPlaneComponent.resumePushSubscription(consumerPid);
+        }
+    }
+    /**
+     * Tear down the push subscription when the transfer completes.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves when the subscription is torn down.
+     */
+    async onComplete(dataPlaneComponent, consumerPid) {
+        await dataPlaneComponent.teardownPushSubscription(consumerPid);
+    }
+    /**
+     * Suspend the push subscription when the transfer is suspended.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves when the subscription is suspended.
+     */
+    async onSuspend(dataPlaneComponent, consumerPid) {
+        await dataPlaneComponent.suspendPushSubscription(consumerPid);
+    }
+    /**
+     * Tear down the push subscription when the transfer terminates.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves when the subscription is torn down.
+     */
+    async onTerminate(dataPlaneComponent, consumerPid) {
+        await dataPlaneComponent.teardownPushSubscription(consumerPid);
+    }
+}
+//# sourceMappingURL=httpDataPushTransferHandler.js.map

package/dist/es/handlers/httpDataPushTransferHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpDataPushTransferHandler.js","sourceRoot":"","sources":["../../../src/handlers/httpDataPushTransferHandler.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { HttpUrlHelper } from \"@twin.org/api-models\";\nimport { ContextIdKeys } from \"@twin.org/context\";\nimport { GeneralError, Is } from \"@twin.org/core\";\nimport type { IDataspaceDataPlaneComponent } from \"@twin.org/dataspace-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport {\n\tDataspaceProtocolEndpointType,\n\tDataspaceProtocolTransferProcessStateType,\n\tDataspaceProtocolTransferProcessTypes\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { IDataspaceProtocolDataAddress } from \"@twin.org/standards-dataspace-protocol\";\nimport type { ITransferHandler } from \"../models/ITransferHandler.js\";\nimport type { ITransferHandlerPrepareContext } from \"../models/ITransferHandlerPrepareContext.js\";\nimport type { ITransferHandlerStartContext } from \"../models/ITransferHandlerStartContext.js\";\n\n/**\n * Transfer handler for HttpData-PUSH format (consumer-initiated push).\n * The consumer supplies its /inbox endpoint in the TransferRequestMessage dataAddress.\n * The provider pushes ActivityStreams objects to that endpoint, and returns its own\n * /inbox in the TransferStartMessage so the consumer can route data notifications.\n */\nexport class HttpDataPushTransferHandler implements ITransferHandler {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<HttpDataPushTransferHandler>();\n\n\t/**\n\t * Returns the class name of the component.\n\t * @returns The class name of the component.\n\t */\n\tpublic className(): string {\n\t\treturn HttpDataPushTransferHandler.CLASS_NAME;\n\t}\n\n\t/**\n\t * Build the consumer's /inbox dataAddress for the TransferRequestMessage.\n\t * @param ctx Prepare context containing path and organization identity.\n\t * @returns The consumer's ActivityStream inbox dataAddress.\n\t * @throws GeneralError When dataPlanePath is not configured.\n\t */\n\tpublic buildConsumerDataAddress(\n\t\tctx: ITransferHandlerPrepareContext\n\t): IDataspaceProtocolDataAddress | undefined {\n\t\tconst { consumerPid, origin, dataPlanePath, organizationIdentity } = ctx;\n\n\t\tif (!Is.stringValue(dataPlanePath)) {\n\t\t\tthrow new GeneralError(\n\t\t\t\tHttpDataPushTransferHandler.CLASS_NAME,\n\t\t\t\t\"pushTransferDataPathNotConfigured\",\n\t\t\t\t{\n\t\t\t\t\tconsumerPid\n\t\t\t\t}\n\t\t\t);\n\t\t}\n\n\t\tconst inboxEndpoint = HttpUrlHelper.addQueryStringParam(\n\t\t\t`${origin}/${dataPlanePath}/inbox`,\n\t\t\tContextIdKeys.Organization,\n\t\t\torganizationIdentity\n\t\t);\n\n\t\treturn {\n\t\t\t\"@type\": DataspaceProtocolTransferProcessTypes.DataAddress,\n\t\t\tendpointType: DataspaceProtocolEndpointType.HttpsActivityStreamEndpoint,\n\t\t\tendpoint: inboxEndpoint\n\t\t};\n\t}\n\n\t/**\n\t * Validate the consumer's dataAddress and build the provider's /inbox endpoint\n\t * for the TransferStartMessage. No bearer token is included — the consumer authenticates\n\t * via the DSP protocol trust payload on the push POST.\n\t * @param ctx Start context containing entity and path configuration.\n\t * @returns The provider's ActivityStream inbox dataAddress.\n\t * @throws GeneralError When the consumer dataAddress is invalid or dataPlanePath is not configured.\n\t */\n\tpublic async buildProviderStartDataAddress(\n\t\tctx: ITransferHandlerStartContext\n\t): Promise<IDataspaceProtocolDataAddress | undefined> {\n\t\tconst { entity, publicOrigin, dataPlanePath, organizationIdentity } = ctx;\n\n\t\tif (\n\t\t\t!Is.stringValue(entity.dataAddress?.endpoint) ||\n\t\t\t!Is.stringValue(entity.dataAddress?.endpointType)\n\t\t) {\n\t\t\tthrow new GeneralError(HttpDataPushTransferHandler.CLASS_NAME, \"invalidPushDataAddress\", {\n\t\t\t\tconsumerPid: entity.consumerPid\n\t\t\t});\n\t\t}\n\n\t\tif (!Is.stringValue(dataPlanePath)) {\n\t\t\tthrow new GeneralError(\n\t\t\t\tHttpDataPushTransferHandler.CLASS_NAME,\n\t\t\t\t\"pushTransferDataPathNotConfigured\",\n\t\t\t\t{ consumerPid: entity.consumerPid }\n\t\t\t);\n\t\t}\n\n\t\tconst fullEndpoint = HttpUrlHelper.addQueryStringParam(\n\t\t\t`${publicOrigin}/${dataPlanePath}/inbox`,\n\t\t\tContextIdKeys.Organization,\n\t\t\torganizationIdentity\n\t\t);\n\n\t\treturn {\n\t\t\t\"@type\": DataspaceProtocolTransferProcessTypes.DataAddress,\n\t\t\tendpointType: DataspaceProtocolEndpointType.HttpsActivityStreamEndpoint,\n\t\t\tendpoint: fullEndpoint\n\t\t};\n\t}\n\n\t/**\n\t * Set up (or resume) the data-plane push subscription after state is persisted to STARTED.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @param previousState The state before the STARTED transition.\n\t * @returns A promise that resolves when the subscription is established.\n\t */\n\tpublic async onProviderStart(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string,\n\t\tpreviousState: DataspaceProtocolTransferProcessStateType\n\t): Promise<void> {\n\t\tif (previousState === DataspaceProtocolTransferProcessStateType.REQUESTED) {\n\t\t\tawait dataPlaneComponent.setupPushSubscription(consumerPid);\n\t\t} else if (previousState === DataspaceProtocolTransferProcessStateType.SUSPENDED) {\n\t\t\tawait dataPlaneComponent.resumePushSubscription(consumerPid);\n\t\t}\n\t}\n\n\t/**\n\t * Tear down the push subscription when the transfer completes.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves when the subscription is torn down.\n\t */\n\tpublic async onComplete(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string\n\t): Promise<void> {\n\t\tawait dataPlaneComponent.teardownPushSubscription(consumerPid);\n\t}\n\n\t/**\n\t * Suspend the push subscription when the transfer is suspended.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves when the subscription is suspended.\n\t */\n\tpublic async onSuspend(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string\n\t): Promise<void> {\n\t\tawait dataPlaneComponent.suspendPushSubscription(consumerPid);\n\t}\n\n\t/**\n\t * Tear down the push subscription when the transfer terminates.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves when the subscription is torn down.\n\t */\n\tpublic async onTerminate(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string\n\t): Promise<void> {\n\t\tawait dataPlaneComponent.teardownPushSubscription(consumerPid);\n\t}\n}\n"]}

package/dist/es/index.js

@@ -3,10 +3,17 @@
 export * from "./dataspaceControlPlanePolicyRequester.js";
 export * from "./dataspaceControlPlaneRoutes.js";
 export * from "./dataspaceControlPlaneService.js";
+export * from "./factories/transferHandlerFactory.js";
+export * from "./handlers/httpDataPostTransferHandler.js";
+export * from "./handlers/httpDataPullTransferHandler.js";
+export * from "./handlers/httpDataPushTransferHandler.js";
 export * from "./models/endpointProperties.js";
 export * from "./models/IDataspaceControlPlaneServiceConfig.js";
 export * from "./models/IDataspaceControlPlaneServiceConstructorOptions.js";
 export * from "./models/INegotiationState.js";
+export * from "./models/ITransferHandler.js";
+export * from "./models/ITransferHandlerPrepareContext.js";
+export * from "./models/ITransferHandlerStartContext.js";
 export * from "./restEntryPoints.js";
 export * from "./schema.js";
 //# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,2CAA2C,CAAC;AAC1D,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iDAAiD,CAAC;AAChE,cAAc,6DAA6D,CAAC;AAC5E,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./dataspaceControlPlanePolicyRequester.js\";\nexport * from \"./dataspaceControlPlaneRoutes.js\";\nexport * from \"./dataspaceControlPlaneService.js\";\nexport * from \"./models/endpointProperties.js\";\nexport * from \"./models/IDataspaceControlPlaneServiceConfig.js\";\nexport * from \"./models/IDataspaceControlPlaneServiceConstructorOptions.js\";\nexport * from \"./models/INegotiationState.js\";\nexport * from \"./restEntryPoints.js\";\nexport * from \"./schema.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,2CAA2C,CAAC;AAC1D,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iDAAiD,CAAC;AAChE,cAAc,6DAA6D,CAAC;AAC5E,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,0CAA0C,CAAC;AACzD,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./dataspaceControlPlanePolicyRequester.js\";\nexport * from \"./dataspaceControlPlaneRoutes.js\";\nexport * from \"./dataspaceControlPlaneService.js\";\nexport * from \"./factories/transferHandlerFactory.js\";\nexport * from \"./handlers/httpDataPostTransferHandler.js\";\nexport * from \"./handlers/httpDataPullTransferHandler.js\";\nexport * from \"./handlers/httpDataPushTransferHandler.js\";\nexport * from \"./models/endpointProperties.js\";\nexport * from \"./models/IDataspaceControlPlaneServiceConfig.js\";\nexport * from \"./models/IDataspaceControlPlaneServiceConstructorOptions.js\";\nexport * from \"./models/INegotiationState.js\";\nexport * from \"./models/ITransferHandler.js\";\nexport * from \"./models/ITransferHandlerPrepareContext.js\";\nexport * from \"./models/ITransferHandlerStartContext.js\";\nexport * from \"./restEntryPoints.js\";\nexport * from \"./schema.js\";\n"]}

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.\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\t/**\n\t * Whether the provider immediately starts a transfer once it has been requested. This is a\n\t * provider-side decision only; the consumer cannot request or influence auto-start. When false\n\t * (the default) the transfer stays in REQUESTED until the provider explicitly calls transferStarted.\n\t *\n\t * Defaults to false.\n\t */\n\tautoStartTransfers?: boolean;\n\n\t/**\n\t * How long (ms) a negotiation may sit without progress before the periodic cleanup treats it as\n\t * timed out, removes it, and notifies the registered callbacks (onTimeout, falling back to\n\t * onFailed with reason \"negotiationStalled\"). Requires a task-scheduler component to be configured.\n\t *\n\t * Defaults to 1800000 (30 minutes).\n\t */\n\tstalledNegotiationTimeoutMs?: number;\n\n\t/**\n\t * How long (ms) a consumer-initiated transfer may sit in REQUESTED without the provider progressing\n\t * it before the periodic cleanup treats it as timed out, removes it, and notifies the registered\n\t * transfer callbacks (onTimeout, falling back to onFailed with reason \"transferStalled\"). Requires a\n\t * task-scheduler component to be configured.\n\t *\n\t * Defaults to 1800000 (30 minutes).\n\t */\n\tstalledTransferTimeoutMs?: number;\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 * Base route path for the data plane service (path only, not full URL).\n\t * Combined with the public origin to form the `dataAddress.endpoint` sent to PULL consumers\n\t * and the inbox URL sent to PUSH providers.\n\t *\n\t * This must be the mount-point prefix of the data plane routes, NOT a specific route path.\n\t * Do NOT append sub-paths such as `/entities` or `/inbox` — those are appended automatically\n\t * by each transfer handler and by the data plane REST client.\n\t *\n\t * REQUIRED if PULL or PUSH transfers are supported.\n\t * If not specified, PULL and PUSH transfers will not be available.\n\t *\n\t * Example: \"dataspace\"\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\t/**\n\t * Whether the provider immediately starts a transfer once it has been requested. This is a\n\t * provider-side decision only; the consumer cannot request or influence auto-start. When false\n\t * (the default) the transfer stays in REQUESTED until the provider explicitly calls transferStarted.\n\t *\n\t * Defaults to false.\n\t */\n\tautoStartTransfers?: boolean;\n\n\t/**\n\t * How long (ms) a negotiation may sit without progress before the periodic cleanup treats it as\n\t * timed out, removes it, and notifies the registered callbacks (onTimeout, falling back to\n\t * onFailed with reason \"negotiationStalled\"). Requires a task-scheduler component to be configured.\n\t *\n\t * Defaults to 1800000 (30 minutes).\n\t */\n\tstalledNegotiationTimeoutMs?: number;\n\n\t/**\n\t * How long (ms) a consumer-initiated transfer may sit in REQUESTED without the provider progressing\n\t * it before the periodic cleanup treats it as timed out, removes it, and notifies the registered\n\t * transfer callbacks (onTimeout, falling back to onFailed with reason \"transferStalled\"). Requires a\n\t * task-scheduler component to be configured.\n\t *\n\t * Defaults to 1800000 (30 minutes).\n\t */\n\tstalledTransferTimeoutMs?: number;\n}\n"]}

package/dist/es/models/ITransferHandler.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ITransferHandler.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ITransferHandler.js","sourceRoot":"","sources":["../../../src/models/ITransferHandler.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type { IDataspaceDataPlaneComponent } from \"@twin.org/dataspace-models\";\nimport type {\n\tDataspaceProtocolTransferProcessStateType,\n\tIDataspaceProtocolDataAddress\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { ITransferHandlerPrepareContext } from \"./ITransferHandlerPrepareContext.js\";\nimport type { ITransferHandlerStartContext } from \"./ITransferHandlerStartContext.js\";\n\n/**\n * Format-specific handler for transfer process operations.\n * One implementation exists per DataspaceTransferFormat value; the TransferHandlerFactory\n * returns the correct instance keyed on the format string.\n */\nexport interface ITransferHandler extends IComponent {\n\t/**\n\t * Optionally build a consumer dataAddress for the TransferRequestMessage.\n\t * Called during prepareTransfer. Returns undefined for formats that do not\n\t * require a consumer-supplied dataAddress (PULL and POST).\n\t * @param ctx The prepare context.\n\t * @returns The consumer dataAddress, or undefined if not required for this format.\n\t */\n\tbuildConsumerDataAddress(\n\t\tctx: ITransferHandlerPrepareContext\n\t): IDataspaceProtocolDataAddress | undefined;\n\n\t/**\n\t * Build the provider dataAddress for the TransferStartMessage.\n\t * Called during startTransfer (provider role). Throws a GeneralError when\n\t * required configuration (e.g. dataPlanePath) is absent.\n\t * @param ctx The start context.\n\t * @returns The provider dataAddress, or undefined if not applicable.\n\t */\n\tbuildProviderStartDataAddress(\n\t\tctx: ITransferHandlerStartContext\n\t): Promise<IDataspaceProtocolDataAddress | undefined>;\n\n\t/**\n\t * Post-start hook for the provider role. Called after state has been persisted\n\t * to STARTED. PUSH transfers set up (or resume) the data-plane push subscription\n\t * here; all other formats are no-ops.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @param previousState The state before the STARTED transition.\n\t * @returns A promise that resolves when the hook completes.\n\t */\n\tonProviderStart(\n\t\tdataPlaneComponent: IDataspaceDataPlaneComponent,\n\t\tconsumerPid: string,\n\t\tpreviousState: DataspaceProtocolTransferProcessStateType\n\t): Promise<void>;\n\n\t/**\n\t * Called after a transfer transitions to COMPLETED.\n\t * PUSH and POST tear down the push subscription; PULL is a no-op.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves when the hook completes.\n\t */\n\tonComplete(dataPlaneComponent: IDataspaceDataPlaneComponent, consumerPid: string): Promise<void>;\n\n\t/**\n\t * Called after a transfer transitions to SUSPENDED.\n\t * PUSH and POST suspend the push subscription; PULL is a no-op.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves when the hook completes.\n\t */\n\tonSuspend(dataPlaneComponent: IDataspaceDataPlaneComponent, consumerPid: string): Promise<void>;\n\n\t/**\n\t * Called after a transfer transitions to TERMINATED.\n\t * PUSH and POST tear down the push subscription; PULL is a no-op.\n\t * @param dataPlaneComponent The data plane component instance.\n\t * @param consumerPid The consumer process ID.\n\t * @returns A promise that resolves when the hook completes.\n\t */\n\tonTerminate(dataPlaneComponent: IDataspaceDataPlaneComponent, consumerPid: string): Promise<void>;\n}\n"]}

package/dist/es/models/ITransferHandlerPrepareContext.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=ITransferHandlerPrepareContext.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ITransferHandlerPrepareContext.js","sourceRoot":"","sources":["../../../src/models/ITransferHandlerPrepareContext.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Context supplied to buildConsumerDataAddress during prepareTransfer.\n */\nexport interface ITransferHandlerPrepareContext {\n\t/**\n\t * The consumer process ID.\n\t */\n\tconsumerPid: string;\n\n\t/**\n\t * The consumer's base origin URL.\n\t */\n\torigin: string;\n\n\t/**\n\t * The data plane path segment, if configured.\n\t */\n\tdataPlanePath: string | undefined;\n\n\t/**\n\t * The organization identity resolved from the current context.\n\t */\n\torganizationIdentity: string;\n}\n"]}

package/dist/es/models/ITransferHandlerStartContext.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ITransferHandlerStartContext.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ITransferHandlerStartContext.js","sourceRoot":"","sources":["../../../src/models/ITransferHandlerStartContext.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { ITransferProcess } from \"@twin.org/dataspace-models\";\nimport type { ITrustComponent } from \"@twin.org/trust-models\";\n\n/**\n * Context supplied to buildProviderStartDataAddress during startTransfer (provider role).\n */\nexport interface ITransferHandlerStartContext {\n\t/**\n\t * The transfer process entity.\n\t */\n\tentity: ITransferProcess;\n\n\t/**\n\t * The provider's public origin URL.\n\t */\n\tpublicOrigin: string;\n\n\t/**\n\t * The data plane path segment, if configured.\n\t */\n\tdataPlanePath: string | undefined;\n\n\t/**\n\t * The organization identity resolved from the current context.\n\t */\n\torganizationIdentity: string;\n\n\t/**\n\t * The trust component for generating access tokens.\n\t */\n\ttrustComponent: ITrustComponent;\n\n\t/**\n\t * The override trust generator type, if configured.\n\t */\n\toverrideTrustGeneratorType: string | undefined;\n}\n"]}

package/dist/types/dataspaceControlPlaneRoutes.d.ts

@@ -1,4 +1,4 @@
-import type { IRestRoute, ITag } from "@twin.org/api-models";
+import { type IRestRoute, type ITag } from "@twin.org/api-models";
 /**
  * The tags to associate with the DSP protocol routes.
  */

package/dist/types/dataspaceControlPlaneService.d.ts

@@ -1,5 +1,5 @@
 import { type IDataspaceAppDataset, type IDataspaceControlPlaneComponent, type IDataspaceControlPlaneResolverComponent, type INegotiationCallback, type ITransferCallback, type ITransferContext } from "@twin.org/dataspace-models";
-import { type IDataspaceProtocolContractNegotiation, type IDataspaceProtocolContractNegotiationError, type IDataspaceProtocolDataset, type IDataspaceProtocolTransferCompletionMessage, type IDataspaceProtocolTransferError, type IDataspaceProtocolTransferProcess, type IDataspaceProtocolTransferRequestMessage, type IDataspaceProtocolTransferStartMessage, type IDataspaceProtocolTransferSuspensionMessage, type IDataspaceProtocolTransferTerminationMessage } from "@twin.org/standards-dataspace-protocol";
+import { type IDataspaceProtocolContractNegotiation, type IDataspaceProtocolContractNegotiationError, type IDataspaceProtocolDataset, type IDataspaceProtocolTransferCompletionMessage, type IDataspaceProtocolTransferError, type IDataspaceProtocolTransferProcess, type IDataspaceProtocolTransferRequestMessage, type IDataspaceProtocolTransferStartMessage, type IDataspaceProtocolTransferSuspensionMessage, type IDataspaceProtocolTransferTerminationMessage, type IDataspaceProtocolVersionResponse } from "@twin.org/standards-dataspace-protocol";
 import type { IDataspaceControlPlaneServiceConstructorOptions } from "./models/IDataspaceControlPlaneServiceConstructorOptions.js";
 /**
  * Dataspace Control Plane Service implementation.
@@ -235,4 +235,9 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
      * @returns A promise that resolves when the dataset has been removed from storage and the catalogue.
      */
     deleteAppDataset(id: string): Promise<void>;
+    /**
+     * Return the Dataspace Protocol versions supported by this connector.
+     * @returns The protocol version response listing all supported DSP versions.
+     */
+    getProtocolVersions(): Promise<IDataspaceProtocolVersionResponse>;
 }

package/dist/types/factories/transferHandlerFactory.d.ts

@@ -0,0 +1,8 @@
+import { Factory } from "@twin.org/core";
+import type { ITransferHandler } from "../models/ITransferHandler.js";
+/**
+ * Factory for registering and retrieving format-specific ITransferHandler instances.
+ * Keys are DataspaceTransferFormat values (e.g. "HttpData-PULL").
+ * Throws GeneralError when get() is called with an unregistered format.
+ */
+export declare const TransferHandlerFactory: Factory<ITransferHandler>;

package/dist/types/handlers/httpDataPostTransferHandler.d.ts

@@ -0,0 +1,63 @@
+import type { IDataspaceDataPlaneComponent } from "@twin.org/dataspace-models";
+import type { DataspaceProtocolTransferProcessStateType, IDataspaceProtocolDataAddress } from "@twin.org/standards-dataspace-protocol";
+import type { ITransferHandler } from "../models/ITransferHandler.js";
+import type { ITransferHandlerPrepareContext } from "../models/ITransferHandlerPrepareContext.js";
+import type { ITransferHandlerStartContext } from "../models/ITransferHandlerStartContext.js";
+/**
+ * Transfer handler for HttpData-POST format (provider-initiated push).
+ * The consumer does not supply a dataAddress. The provider returns its own /inbox URL
+ * along with a signed JWT so the consumer can authenticate when posting activities there.
+ */
+export declare class HttpDataPostTransferHandler implements ITransferHandler {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * POST consumers do not supply a dataAddress — provider returns its own /inbox on start.
+     * @param ctx Prepare context (unused for POST).
+     * @returns undefined.
+     */
+    buildConsumerDataAddress(ctx: ITransferHandlerPrepareContext): IDataspaceProtocolDataAddress | undefined;
+    /**
+     * Build the provider's /inbox dataAddress and signed JWT for the TransferStartMessage.
+     * @param ctx Start context containing entity, trust component, and path configuration.
+     * @returns The provider's ActivityStream inbox dataAddress with bearer token.
+     * @throws GeneralError When dataPlanePath is not configured or providerIdentity is missing.
+     */
+    buildProviderStartDataAddress(ctx: ITransferHandlerStartContext): Promise<IDataspaceProtocolDataAddress | undefined>;
+    /**
+     * No-op: POST transfers do not involve a provider-managed push subscription on start.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @param previousState The state before the STARTED transition.
+     * @returns A promise that resolves immediately.
+     */
+    onProviderStart(dataPlaneComponent: IDataspaceDataPlaneComponent, consumerPid: string, previousState: DataspaceProtocolTransferProcessStateType): Promise<void>;
+    /**
+     * Tear down the data plane subscription when the transfer completes.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves when the subscription is torn down.
+     */
+    onComplete(dataPlaneComponent: IDataspaceDataPlaneComponent, consumerPid: string): Promise<void>;
+    /**
+     * Suspend the data plane subscription when the transfer is suspended.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves when the subscription is suspended.
+     */
+    onSuspend(dataPlaneComponent: IDataspaceDataPlaneComponent, consumerPid: string): Promise<void>;
+    /**
+     * Tear down the data plane subscription when the transfer terminates.
+     * @param dataPlaneComponent The data plane component instance.
+     * @param consumerPid The consumer process ID.
+     * @returns A promise that resolves when the subscription is torn down.
+     */
+    onTerminate(dataPlaneComponent: IDataspaceDataPlaneComponent, consumerPid: string): Promise<void>;
+}