@twin.org/dataspace-control-plane-service 0.0.3-next.15

package/docs/reference/interfaces/IDataspaceControlPlaneServiceConstructorOptions.md

@@ -0,0 +1,160 @@
+# Interface: IDataspaceControlPlaneServiceConstructorOptions
+
+Dataspace Control Plane service constructor options.
+
+## Properties
+
+### policyAdministrationPointComponentType?
+
+> `optional` **policyAdministrationPointComponentType**: `string`
+
+Policy Administration Point component type.
+Used for Agreement lookup and validation during Transfer Process initiation.
+
+#### Default
+
+```ts
+policy-administration-point
+```
+
+***
+
+### policyNegotiationPointComponentType?
+
+> `optional` **policyNegotiationPointComponentType**: `string`
+
+Policy Negotiation Point component type.
+Used for contract negotiation to create agreements before transfer processes.
+
+#### Default
+
+```ts
+policy-negotiation-point
+```
+
+***
+
+### policyNegotiationAdminPointComponentType?
+
+> `optional` **policyNegotiationAdminPointComponentType**: `string`
+
+Policy Negotiation Admin Point component type.
+Used for querying negotiation history.
+Optional - if not provided, negotiation history will not be available.
+
+#### Default
+
+```ts
+policy-negotiation-admin-point
+```
+
+***
+
+### federatedCatalogueComponentType?
+
+> `optional` **federatedCatalogueComponentType**: `string`
+
+Federated Catalogue component type.
+Used for dataset validation during Transfer Process initiation.
+Validates that Agreements reference valid catalog datasets.
+
+#### Default
+
+```ts
+federated-catalogue
+```
+
+***
+
+### loggingComponentType?
+
+> `optional` **loggingComponentType**: `string`
+
+Logging component type.
+
+#### Default
+
+```ts
+logging
+```
+
+***
+
+### identityComponentType?
+
+> `optional` **identityComponentType**: `string`
+
+Identity component type (for token signing/verification).
+
+#### Default
+
+```ts
+identity
+```
+
+***
+
+### identityAuthenticationComponentType?
+
+> `optional` **identityAuthenticationComponentType**: `string`
+
+Identity Authentication component type (for token validation).
+
+#### Default
+
+```ts
+identity-authentication
+```
+
+***
+
+### trustComponentType?
+
+> `optional` **trustComponentType**: `string`
+
+Trust component type for trust verification.
+Used to verify JWT/VC tokens and extract identity information.
+
+#### Default
+
+```ts
+trust
+```
+
+***
+
+### transferProcessEntityStorageType?
+
+> `optional` **transferProcessEntityStorageType**: `string`
+
+Entity storage type for Transfer Process entities.
+Used to persist transfer state for the consumerPid flow.
+Must match the Data Plane's transferProcessEntityStorageType for shared storage.
+
+#### Default
+
+```ts
+transfer-process
+```
+
+***
+
+### taskSchedulerComponentType?
+
+> `optional` **taskSchedulerComponentType**: `string`
+
+Task scheduler component type for periodic cleanup of stalled negotiations.
+
+#### Default
+
+```ts
+task-scheduler
+```
+
+***
+
+### config?
+
+> `optional` **config**: [`IDataspaceControlPlaneServiceConfig`](IDataspaceControlPlaneServiceConfig.md)
+
+The configuration of the Dataspace Control Plane Service.

package/docs/reference/interfaces/INegotiationState.md

@@ -0,0 +1,43 @@
+# Interface: INegotiationState
+
+Negotiation state tracked internally for callback routing.
+
+## Properties
+
+### negotiationId
+
+> **negotiationId**: `string`
+
+The negotiation ID (self-reference for lookup).
+
+***
+
+### state
+
+> **state**: `DataspaceProtocolContractNegotiationStateType`
+
+Current negotiation state.
+
+***
+
+### agreement?
+
+> `optional` **agreement**: `IOdrlAgreement`
+
+Agreement received from provider (stored until finalized).
+
+***
+
+### startedAt
+
+> **startedAt**: `number`
+
+Timestamp when negotiation started.
+
+***
+
+### updatedAt
+
+> **updatedAt**: `number`
+
+Timestamp when negotiation state was last updated.

package/docs/reference/variables/restEntryPoints.md

@@ -0,0 +1,7 @@
+# Variable: restEntryPoints
+
+> `const` **restEntryPoints**: `IRestRouteEntryPoint`[]
+
+Entry points for the REST API.
+Defines REST routes for DSP protocol only.
+Resolver methods (IDataspaceControlPlaneResolverComponent).

package/docs/reference/variables/tagsDataspaceControlPlane.md

@@ -0,0 +1,5 @@
+# Variable: tagsDataspaceControlPlane
+
+> `const` **tagsDataspaceControlPlane**: `ITag`[]
+
+The tags to associate with the DSP protocol routes.

package/locales/en.json

@@ -0,0 +1,93 @@
+{
+	"info": {
+		"dataspaceControlPlaneService": {
+			"transferProcessInitiated": "Transfer Process initiated",
+			"transferProcessQueried": "Transfer Process queried (role: {role})",
+			"transferProcessStarted": "Transfer Process started",
+			"dataAccessTokenGenerated": "Data access token generated for PULL transfer",
+			"transferProcessCompleted": "Transfer Process completed",
+			"transferProcessSuspended": "Transfer Process suspended",
+			"transferProcessTerminated": "Transfer Process terminated",
+			"resolvedConsumerPid": "Resolved consumerPid to Transfer Context",
+			"resolvedProviderPid": "Resolved providerPid to Transfer Context",
+			"catalogDatasetFound": "Dataset validated in Federated Catalogue",
+			"agreementMatchedOffer": "Agreement matched Catalog Offer",
+			"populatingFederatedCatalogue": "Populating Federated Catalogue with datasets from registered apps",
+			"federatedCataloguePopulated": "Federated Catalogue population completed (registered: {registeredCount}, errors: {errorCount}, apps: {totalApps})",
+			"startingContractNegotiation": "Starting contract negotiation with provider",
+			"offerFoundInCatalog": "Offer found in Federated Catalogue and validated",
+			"negotiationInitiated": "Contract negotiation initiated successfully",
+			"getNegotiation": "Retrieving negotiation status",
+			"negotiationStateRetrieved": "Negotiation state retrieved successfully",
+			"getNegotiationHistory": "Retrieving negotiation history",
+			"negotiationHistoryRetrieved": "Negotiation history retrieved successfully",
+			"stalledNegotiationsCleanupComplete": "Stalled negotiations cleanup completed (cleanedUp: {cleanedUp})"
+		},
+		"dataspaceControlPlanePolicyRequester": {
+			"offerReceived": "Offer received from provider (negotiationId: {negotiationId}, offerId: {offerId})",
+			"agreementReceived": "Agreement received from provider (negotiationId: {negotiationId}, agreementId: {agreementId})",
+			"negotiationFinalized": "Negotiation finalized by provider (negotiationId: {negotiationId})",
+			"negotiationCompleted": "Negotiation completed successfully (negotiationId: {negotiationId}, agreementId: {agreementId}, duration: {durationMs}ms)",
+			"negotiationRejected": "Negotiation was rejected/terminated (negotiationId: {negotiationId}, duration: {durationMs}ms)"
+		}
+	},
+	"debug": {
+		"dataspaceControlPlaneService": {
+			"engineCloneStart": "Skipping Federated Catalogue population (engine clone or no engine)",
+			"discoveredApps": "Discovered {count} registered Dataspace apps",
+			"datasetRegistered": "Dataset {datasetId} registered from app {appName}"
+		}
+	},
+	"warn": {
+		"dataspaceControlPlaneService": {
+			"catalogDatasetHasNoOffers": "Dataset has no Offers (odrl:hasPolicy) in Federated Catalogue",
+			"pushTransferModeNotImplemented": "PUSH transfer mode requested but not implemented. Consumer provided dataAddress endpoint but data push is not yet supported.",
+			"stalledNegotiationCleanedUp": "Stalled negotiation cleaned up (negotiationId: {negotiationId})"
+		},
+		"dataspaceControlPlanePolicyRequester": {
+			"unknownNegotiationFinalized": "Unknown negotiation finalized (negotiationId: {negotiationId})",
+			"negotiationTerminated": "Negotiation terminated by provider (negotiationId: {negotiationId})",
+			"unknownNegotiationTerminated": "Unknown negotiation terminated (negotiationId: {negotiationId})"
+		}
+	},
+	"error": {
+		"dataspaceControlPlaneService": {
+			"transferProcessNotFound": "Transfer Process not found",
+			"pullTransfersNotSupported": "PULL transfers are not supported. Configure dataPlanePath in service configuration to enable PULL transfers.",
+			"datasetRegistrationFailed": "Failed to register dataset {datasetId} from app {appName}",
+			"appDatasetsRetrievalFailed": "Failed to retrieve datasets from app {appName}",
+			"transferProcessTerminated": "Transfer Process \"{consumerPid}\" is terminated and cannot be used",
+			"transferProcessTerminatedProvider": "Transfer Process \"{providerPid}\" is terminated and cannot be used",
+			"invalidTransferRequest": "Transfer Request does not conform to Dataspace Protocol specification",
+			"invalidStateForStart": "Transfer Process cannot be started: current state is \"{currentState}\", expected REQUESTED or SUSPENDED",
+			"invalidStateForComplete": "Transfer Process cannot be completed: current state is \"{currentState}\", expected STARTED",
+			"invalidStateForSuspend": "Transfer Process cannot be suspended: current state is \"{currentState}\", expected STARTED",
+			"invalidTransferStartMessage": "Transfer Start Message does not conform to Dataspace Protocol specification",
+			"invalidTransferCompletionMessage": "Transfer Completion Message does not conform to Dataspace Protocol specification",
+			"invalidTransferSuspensionMessage": "Transfer Suspension Message does not conform to Dataspace Protocol specification",
+			"invalidTransferTerminationMessage": "Transfer Termination Message does not conform to Dataspace Protocol specification",
+			"agreementLookupFailed": "Failed to lookup Agreement: {agreementId}",
+			"agreementNotFound": "Agreement not found",
+			"agreementMissingTarget": "Agreement is missing target (dataset): {agreementId}",
+			"agreementMultipleTargetsNotSupported": "Agreement has multiple targets which is not supported. Only single target Agreements are allowed: {agreementId}, target count: {targetCount}",
+			"agreementTargetMissingUid": "Agreement target object is missing required \"uid\" property: {agreementId}",
+			"datasetNotInCatalog": "Dataset \"{datasetId}\" not found in Federated Catalogue (Agreement: {agreementId})",
+			"catalogLookupFailed": "Failed to lookup dataset in Federated Catalogue: {datasetId} (Agreement: {agreementId})",
+			"agreementNotMatchingOffer": "Agreement \"{agreementId}\" does not match any Catalog Offer for dataset {datasetId}. Available Offers: {availableOffers}",
+			"organizationContextMissing": "Organization context is missing. Cannot verify Agreement authorization for consumerPid: {consumerPid}",
+			"organizationContextMissingProvider": "Organization context is missing. Cannot verify Agreement authorization for providerPid: {providerPid}",
+			"agreementAssignerMismatch": "Agreement assigner does not match current organization. Agreement: {agreementId}, consumerPid: {consumerPid}, expected: {expectedOrgId}, actual: {actualAssigner}",
+			"agreementAssignerMismatchProvider": "Agreement assigner does not match current organization. Agreement: {agreementId}, providerPid: {providerPid}, expected: {expectedOrgId}, actual: {actualAssigner}",
+			"agreementAssigneeMismatch": "Agreement assignee does not match expected consumer identity. Agreement: {agreementId}, providerPid: {providerPid}, expected: {expectedConsumerIdentity}, actual: {actualAssignee}",
+			"negotiationInitiationFailed": "Failed to initiate contract negotiation",
+			"datasetNotFoundInCatalog": "Dataset/Offer \"{offerId}\" not found in Federated Catalogue. Cannot initiate negotiation for non-existent offer.",
+			"catalogLookupFailedForNegotiation": "Failed to lookup dataset/offer in Federated Catalogue before negotiation: {offerId}",
+			"datasetHasNoOffers": "Dataset \"{datasetId}\" has no ODRL offers (odrl:hasPolicy). Cannot negotiate without an offer.",
+			"datasetHasNoValidOffers": "Dataset \"{datasetId}\" has no valid ODRL offer objects. Cannot negotiate without a valid offer.",
+			"offerNotFoundInDataset": "Offer \"{offerId}\" not found in dataset \"{datasetId}\". Available offers: {availableOffers}",
+			"pnapNotConfigured": "Policy Negotiation Admin Point not configured. Cannot retrieve negotiation history without PNAP.",
+			"negotiationCallbackError": "Negotiation callback \"{key}\" threw an error during {method} for negotiation {negotiationId}"
+		},
+		"dataspaceControlPlanePolicyRequester": {}
+	}
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+	"name": "@twin.org/dataspace-control-plane-service",
+	"version": "0.0.3-next.15",
+	"description": "Dataspace Control Plane service implementation for Eclipse Dataspace Protocol Transfer Process Protocol",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/twinfoundation/dataspace.git",
+		"directory": "packages/dataspace-control-plane-service"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"dependencies": {
+		"@twin.org/api-models": "next",
+		"@twin.org/context": "next",
+		"@twin.org/core": "next",
+		"@twin.org/dataspace-models": "0.0.3-next.15",
+		"@twin.org/entity": "next",
+		"@twin.org/entity-storage-models": "next",
+		"@twin.org/federated-catalogue-models": "next",
+		"@twin.org/logging-models": "next",
+		"@twin.org/nameof": "next",
+		"@twin.org/rights-management-models": "next",
+		"@twin.org/standards-dataspace-protocol": "next",
+		"@twin.org/standards-w3c-odrl": "next",
+		"@twin.org/trust-models": "next"
+	},
+	"main": "./dist/es/index.js",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/es/index.js",
+			"default": "./dist/es/index.js"
+		},
+		"./locales/*.json": "./locales/*.json"
+	},
+	"files": [
+		"dist/es",
+		"dist/types",
+		"locales",
+		"docs"
+	],
+	"keywords": [
+		"twin",
+		"trade",
+		"iota",
+		"framework",
+		"blockchain",
+		"data",
+		"space",
+		"control",
+		"plane",
+		"service",
+		"dataspace",
+		"protocol",
+		"dsp",
+		"transfer",
+		"process",
+		"microservice",
+		"business-logic"
+	],
+	"bugs": {
+		"url": "git+https://github.com/twinfoundation/dataspace/issues"
+	},
+	"homepage": "https://twindev.org"
+}