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

package/dist/types/dataspaceControlPlaneService.d.ts

@@ -0,0 +1,153 @@
+import { type IDataspaceControlPlaneComponent, type IDataspaceControlPlaneResolverComponent, type INegotiationCallback, type ITransferContext } from "@twin.org/dataspace-models";
+import { type IDataspaceProtocolContractNegotiation, type IDataspaceProtocolContractNegotiationError, type IDataspaceProtocolTransferCompletionMessage, type IDataspaceProtocolTransferError, type IDataspaceProtocolTransferProcess, type IDataspaceProtocolTransferRequestMessage, type IDataspaceProtocolTransferStartMessage, type IDataspaceProtocolTransferSuspensionMessage, type IDataspaceProtocolTransferTerminationMessage } from "@twin.org/standards-dataspace-protocol";
+import type { IDataspaceControlPlaneServiceConstructorOptions } from "./models/IDataspaceControlPlaneServiceConstructorOptions.js";
+/**
+ * Dataspace Control Plane Service implementation.
+ *
+ * Handles contract negotiation (via PNP callbacks) and transfer process management.
+ * Negotiation is fully callback-driven: negotiateAgreement() returns immediately with
+ * a negotiationId, and the caller is notified via INegotiationCallback when complete.
+ */
+export declare class DataspaceControlPlaneService implements IDataspaceControlPlaneComponent, IDataspaceControlPlaneResolverComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of DataspaceControlPlaneService.
+     * @param options The options for the service.
+     */
+    constructor(options?: IDataspaceControlPlaneServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Register a callback to receive negotiation state change notifications.
+     * Upstream modules (e.g. supply-chain) register their callback here.
+     * @param key A unique key identifying this callback registration.
+     * @param callback The callback interface to register.
+     */
+    registerNegotiationCallback(key: string, callback: INegotiationCallback): void;
+    /**
+     * Unregister a previously registered negotiation callback.
+     * @param key The key used when registering the callback.
+     */
+    unregisterNegotiationCallback(key: string): void;
+    /**
+     * The service needs to be started when the application is initialized.
+     * Populates the Federated Catalogue with datasets from registered apps
+     * and starts the stalled negotiation cleanup task.
+     * @param nodeLoggingComponentType The node logging component type.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Stop the service.
+     * Removes the stalled negotiation cleanup task.
+     * @param nodeLoggingComponentType The node logging component type.
+     */
+    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 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>;
+    /**
+     * Start a Transfer Process.
+     * Transitions Transfer Process from REQUESTED to STARTED state or resumes from SUSPENDED state.
+     * @param message Transfer start message (DSP compliant).
+     * @param publicOrigin The public origin URL of this service.
+     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.
+     *
+     * Role Performed: Provider / Consumer
+     */
+    startTransfer(message: IDataspaceProtocolTransferStartMessage, publicOrigin: string, trustPayload: unknown): Promise<IDataspaceProtocolTransferStartMessage | IDataspaceProtocolTransferError>;
+    /**
+     * Complete a Transfer Process.
+     * @param message Transfer completion message (DSP compliant).
+     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @returns Transfer Process (DSP compliant) with state COMPLETED, or TransferError if the operation fails.
+     */
+    completeTransfer(message: IDataspaceProtocolTransferCompletionMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Suspend a Transfer Process.
+     * @param message Transfer suspension message (DSP compliant).
+     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @returns Transfer Process (DSP compliant) with state SUSPENDED, or TransferError if the operation fails.
+     */
+    suspendTransfer(message: IDataspaceProtocolTransferSuspensionMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Terminate a Transfer Process.
+     * @param message Transfer termination message (DSP compliant).
+     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @returns Transfer Process (DSP compliant) with state TERMINATED, or TransferError if the operation fails.
+     */
+    terminateTransfer(message: IDataspaceProtocolTransferTerminationMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Get Transfer Process state.
+     * @param pid Process ID (consumerPid or providerPid).
+     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @returns Transfer Process (DSP compliant) with current state, or TransferError if the operation fails.
+     */
+    getTransferProcess(pid: string, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Negotiate a contract agreement with a provider.
+     * Returns immediately with a negotiationId. The caller is notified
+     * via the registered INegotiationCallback when the negotiation completes.
+     *
+     * @param offerId The offer ID from the provider's catalog.
+     * @param providerEndpoint The provider's contract negotiation endpoint URL.
+     * @param publicOrigin The public origin URL of this control plane (for callbacks).
+     * @param trustPayload The trust payload for authentication.
+     * @returns The negotiation ID. Use the registered callback for completion notification.
+     */
+    negotiateAgreement(offerId: string, providerEndpoint: string, publicOrigin: string, trustPayload: unknown): Promise<{
+        negotiationId: string;
+    }>;
+    /**
+     * Get the current state of a contract negotiation.
+     * @param negotiationId The unique identifier of the negotiation.
+     * @param trustPayload The trust payload for authentication.
+     * @returns Current state of the negotiation.
+     */
+    getNegotiation(negotiationId: string, trustPayload: unknown): Promise<IDataspaceProtocolContractNegotiation | IDataspaceProtocolContractNegotiationError>;
+    /**
+     * Get negotiation history.
+     * @param state Optional filter by negotiation state.
+     * @param cursor Optional pagination cursor.
+     * @param trustPayload Trust payload for authentication.
+     * @returns List of negotiation history entries with pagination.
+     */
+    getNegotiationHistory(state: string | undefined, cursor: string | undefined, trustPayload: unknown): Promise<{
+        negotiations: {
+            negotiation: IDataspaceProtocolContractNegotiation | IDataspaceProtocolContractNegotiationError;
+            createdAt: string;
+            offerId?: string;
+            agreementId?: string;
+        }[];
+        cursor?: string;
+        count: number;
+    }>;
+    /**
+     * Resolve consumerPid to Transfer Context.
+     * @param consumerPid Consumer Process ID.
+     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @returns Transfer Context with Agreement, datasetId, and Transfer Process metadata.
+     */
+    resolveConsumerPid(consumerPid: string, trustPayload: unknown): Promise<ITransferContext>;
+    /**
+     * Resolve providerPid to Transfer Context.
+     * @param providerPid Provider Process ID.
+     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @returns Transfer Context with Agreement, datasetId, and Transfer Process metadata.
+     */
+    resolveProviderPid(providerPid: string, trustPayload: unknown): Promise<ITransferContext>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./dataspaceControlPlanePolicyRequester.js";
+export * from "./dataspaceControlPlaneRoutes.js";
+export * from "./dataspaceControlPlaneService.js";
+export * from "./models/IDataspaceControlPlaneServiceConfig.js";
+export * from "./models/IDataspaceControlPlaneServiceConstructorOptions.js";
+export * from "./models/INegotiationState.js";
+export * from "./restEntryPoints.js";
+export * from "./schema.js";

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

@@ -0,0 +1,20 @@
+/**
+ * Dataspace Control Plane service configuration.
+ */
+export interface IDataspaceControlPlaneServiceConfig {
+    /**
+     * Override the default trust generator type for token generation.
+     * If not specified, the default trust generator configured in the trust component will be used.
+     */
+    overrideTrustGeneratorType?: string;
+    /**
+     * Data plane endpoint path for PULL transfers (path only, not full URL).
+     * Will be combined with the public origin from the hosting component.
+     *
+     * REQUIRED if PULL transfers are supported.
+     * If not specified, PULL transfers will not be available.
+     *
+     * Example: "data-plane/data" or "api/data-plane/data"
+     */
+    dataPlanePath?: string;
+}

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

@@ -0,0 +1,69 @@
+import type { IDataspaceControlPlaneServiceConfig } from "./IDataspaceControlPlaneServiceConfig.js";
+/**
+ * Dataspace Control Plane service constructor options.
+ */
+export interface IDataspaceControlPlaneServiceConstructorOptions {
+    /**
+     * Policy Administration Point component type.
+     * Used for Agreement lookup and validation during Transfer Process initiation.
+     * @default policy-administration-point
+     */
+    policyAdministrationPointComponentType?: string;
+    /**
+     * Policy Negotiation Point component type.
+     * Used for contract negotiation to create agreements before transfer processes.
+     * @default policy-negotiation-point
+     */
+    policyNegotiationPointComponentType?: string;
+    /**
+     * Policy Negotiation Admin Point component type.
+     * Used for querying negotiation history.
+     * Optional - if not provided, negotiation history will not be available.
+     * @default policy-negotiation-admin-point
+     */
+    policyNegotiationAdminPointComponentType?: string;
+    /**
+     * Federated Catalogue component type.
+     * Used for dataset validation during Transfer Process initiation.
+     * Validates that Agreements reference valid catalog datasets.
+     * @default federated-catalogue
+     */
+    federatedCatalogueComponentType?: string;
+    /**
+     * Logging component type.
+     * @default logging
+     */
+    loggingComponentType?: string;
+    /**
+     * Identity component type (for token signing/verification).
+     * @default identity
+     */
+    identityComponentType?: string;
+    /**
+     * Identity Authentication component type (for token validation).
+     * @default identity-authentication
+     */
+    identityAuthenticationComponentType?: string;
+    /**
+     * Trust component type for trust verification.
+     * Used to verify JWT/VC tokens and extract identity information.
+     * @default trust
+     */
+    trustComponentType?: 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 transfer-process
+     */
+    transferProcessEntityStorageType?: string;
+    /**
+     * Task scheduler component type for periodic cleanup of stalled negotiations.
+     * @default task-scheduler
+     */
+    taskSchedulerComponentType?: string;
+    /**
+     * The configuration of the Dataspace Control Plane Service.
+     */
+    config?: IDataspaceControlPlaneServiceConfig;
+}

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

@@ -0,0 +1,27 @@
+import type { DataspaceProtocolContractNegotiationStateType } from "@twin.org/standards-dataspace-protocol";
+import type { IOdrlAgreement } from "@twin.org/standards-w3c-odrl";
+/**
+ * Negotiation state tracked internally for callback routing.
+ */
+export interface INegotiationState {
+    /**
+     * The negotiation ID (self-reference for lookup).
+     */
+    negotiationId: string;
+    /**
+     * Current negotiation state.
+     */
+    state: DataspaceProtocolContractNegotiationStateType;
+    /**
+     * Agreement received from provider (stored until finalized).
+     */
+    agreement?: IOdrlAgreement;
+    /**
+     * Timestamp when negotiation started.
+     */
+    startedAt: number;
+    /**
+     * Timestamp when negotiation state was last updated.
+     */
+    updatedAt: number;
+}

package/dist/types/restEntryPoints.d.ts

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

package/dist/types/schema.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Inits schemas for Control Plane entities.
+ */
+export declare function initSchema(): void;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,39 @@
+import { type IDataspaceProtocolCatalogError, type IDataspaceProtocolTransferError } from "@twin.org/standards-dataspace-protocol";
+import { HttpStatusCode } from "@twin.org/web";
+/**
+ * Transform an error to DS Protocol TransferError format.
+ * Used by both service and route layers to ensure consistent error responses.
+ * Following the same pattern as Federated Catalogue's catalogErrorUtils.ts.
+ * The code property uses semantic format "ErrorName:message".
+ * The reason property contains the full flattened error chain for debugging.
+ * @param error The error to transform.
+ * @param pids Optional object containing consumerPid and/or providerPid.
+ * @param pids.consumerPid Optional consumer process ID.
+ * @param pids.providerPid Optional provider process ID.
+ * @returns The TransferError.
+ */
+export declare function transformToTransferError(error: unknown, pids?: {
+    consumerPid?: string;
+    providerPid?: string;
+}): IDataspaceProtocolTransferError;
+/**
+ * Transform the DS Protocol result to an HTTP status code.
+ * Used by the routes layer to derive HTTP status from TransferError.
+ *
+ * @param result The result to transform.
+ * @returns The transformed status code or undefined if no transformation was found or not an error.
+ */
+export declare function transformErrorToStatusCode(result: unknown): HttpStatusCode | undefined;
+/**
+ * Check if a CatalogError contains a specific error name in its code.
+ * @param error The CatalogError to check.
+ * @param errorName The error name to check for (e.g., NotFoundError.CLASS_NAME).
+ * @returns True if the error code contains the specified error name.
+ */
+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.
+ */
+export declare function isCatalogError(error: unknown): error is IDataspaceProtocolCatalogError;

package/docs/API.md

@@ -0,0 +1,341 @@
+# Dataspace Control Plane API Documentation
+
+REST API endpoints for the Eclipse Dataspace Protocol (DSP) Contract Negotiation and Transfer Process protocols.
+
+## Table of Contents
+
+- [Authentication](#authentication)
+- [Contract Negotiation Protocol](#contract-negotiation-protocol)
+  - [POST /negotiations](#post-negotiations)
+  - [GET /negotiations/:negotiationId](#get-negotiationsnegotiationid)
+- [Transfer Process Protocol](#transfer-process-protocol)
+  - [POST /transfers/request](#post-transfersrequest)
+  - [GET /transfers/:pid](#get-transferspid)
+  - [POST /transfers/:pid/start](#post-transferspidstart)
+  - [POST /transfers/:pid/complete](#post-transferspidcomplete)
+  - [POST /transfers/:pid/suspend](#post-transferspidsuspend)
+  - [POST /transfers/:pid/terminate](#post-transferspidterminate)
+- [Error Handling](#error-handling)
+
+## Authentication
+
+All API endpoints require authentication via Bearer token in the `Authorization` header:
+
+```http
+Authorization: Bearer <trust-token>
+```
+
+## Contract Negotiation Protocol
+
+Implements the DSP Contract Negotiation Protocol for negotiating agreements with data providers.
+
+**Base Path:** `/control-plane/negotiations`
+
+**Specification:** [Eclipse DSP 2025-1 - Contract Negotiation](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol)
+
+### POST /negotiations
+
+Initiate a contract negotiation with a provider.
+
+**Request:**
+
+```http
+POST /control-plane/negotiations
+Authorization: Bearer <trust-token>
+Content-Type: application/json
+
+{
+  "offerId": "offer-123",
+  "providerEndpoint": "https://provider.example.com/negotiations",
+  "publicOrigin": "https://consumer.example.com"  // Optional
+}
+```
+
+**Request Body:**
+
+| Field              | Type   | Required | Description                                                                         |
+| ------------------ | ------ | -------- | ----------------------------------------------------------------------------------- |
+| `offerId`          | string | Yes      | The offer ID from the provider's catalog                                            |
+| `providerEndpoint` | string | Yes      | The provider's contract negotiation endpoint URL                                    |
+| `publicOrigin`     | string | No       | The public origin URL for callbacks (defaults to hosting component's public origin) |
+
+**Response (200 OK):**
+
+```json
+{
+  "agreement": {
+    "@context": "http://www.w3.org/ns/odrl.jsonld",
+    "@type": "Agreement",
+    "uid": "agreement-456",
+    "assigner": "did:iota:provider-xyz",
+    "assignee": "did:iota:consumer-abc",
+    "target": "urn:uuid:dataset-789",
+    "permission": [{ "action": "read" }]
+  },
+  "agreementId": "agreement-456",
+  "negotiationId": "negotiation-123",
+  "consumerPid": "consumer-pid-123",
+  "providerPid": "provider-pid-456"
+}
+```
+
+**Response Body:**
+
+| Field           | Type        | Description                              |
+| --------------- | ----------- | ---------------------------------------- |
+| `agreement`     | IOdrlPolicy | The negotiated ODRL agreement            |
+| `agreementId`   | string      | The unique identifier of the agreement   |
+| `negotiationId` | string      | The unique identifier of the negotiation |
+| `consumerPid`   | string      | The consumer process ID                  |
+| `providerPid`   | string      | The provider process ID                  |
+
+**Error Responses:**
+
+| Status Code | Description                                   |
+| ----------- | --------------------------------------------- |
+| 400         | Invalid request (missing required fields)     |
+| 401         | Unauthorized (invalid or missing trust token) |
+| 404         | Offer not found                               |
+| 500         | Internal server error during negotiation      |
+| 504         | Negotiation timeout                           |
+
+**Example:**
+
+```bash
+curl -X POST https://consumer.example.com/control-plane/negotiations \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "offerId": "offer-from-catalog",
+    "providerEndpoint": "https://provider.example.com/negotiations"
+  }'
+```
+
+### GET /negotiations/:negotiationId {#get-negotiationsnegotiationid}
+
+Get the current state of a contract negotiation.
+
+**Request:**
+
+```http
+GET /control-plane/negotiations/{negotiationId}
+Authorization: Bearer <trust-token>
+```
+
+**Path Parameters:**
+
+| Parameter       | Type   | Description                              |
+| --------------- | ------ | ---------------------------------------- |
+| `negotiationId` | string | The unique identifier of the negotiation |
+
+**Response (200 OK):**
+
+```json
+{
+  "negotiationId": "negotiation-123",
+  "state": "FINALIZED",
+  "consumerPid": "consumer-pid-123",
+  "providerPid": "provider-pid-456",
+  "agreementId": "agreement-456"
+}
+```
+
+**Response Body:**
+
+| Field           | Type   | Description                                                                             |
+| --------------- | ------ | --------------------------------------------------------------------------------------- |
+| `negotiationId` | string | The unique identifier of the negotiation                                                |
+| `state`         | string | Current negotiation state (REQUESTED, OFFERED, AGREED, VERIFIED, FINALIZED, TERMINATED) |
+| `consumerPid`   | string | The consumer process ID                                                                 |
+| `providerPid`   | string | The provider process ID                                                                 |
+| `agreementId`   | string | The agreement ID (only present if state is FINALIZED)                                   |
+| `errorDetail`   | string | Error details (only present if state is TERMINATED)                                     |
+
+**Negotiation States:**
+
+| State        | Description                                   |
+| ------------ | --------------------------------------------- |
+| `REQUESTED`  | Initial request sent to provider              |
+| `OFFERED`    | Provider sent counter-offer                   |
+| `AGREED`     | Agreement reached                             |
+| `VERIFIED`   | Agreement verified                            |
+| `FINALIZED`  | Negotiation complete, agreement ready for use |
+| `TERMINATED` | Negotiation failed or was cancelled           |
+
+**Error Responses:**
+
+| Status Code | Description                                   |
+| ----------- | --------------------------------------------- |
+| 401         | Unauthorized (invalid or missing trust token) |
+| 404         | Negotiation not found                         |
+| 500         | Internal server error                         |
+
+**Example:**
+
+```bash
+curl -X GET https://consumer.example.com/control-plane/negotiations/negotiation-123 \
+  -H "Authorization: Bearer ${TOKEN}"
+```
+
+## Transfer Process Protocol
+
+Implements the DSP Transfer Process Protocol for managing data transfers.
+
+**Base Path:** `/control-plane/transfers`
+
+**Specification:** [Eclipse DSP 2025-1 - Transfer Process](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#transfer-process-protocol)
+
+### POST /transfers/request
+
+Initiate a transfer request using a previously negotiated agreement.
+
+**Request:**
+
+```http
+POST /control-plane/transfers/request
+Authorization: Bearer <trust-token>
+Content-Type: application/json
+
+{
+  "@context": ["https://w3id.org/dspace/2025/1/context.jsonld"],
+  "@type": "TransferRequestMessage",
+  "consumerPid": "consumer-pid-123",
+  "agreementId": "agreement-456",
+  "callbackAddress": "https://consumer.example.com/callbacks",
+  "format": "application/json"
+}
+```
+
+_See [Eclipse DSP Transfer Request specification](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#transfer-process-protocol) for complete request schema._
+
+### GET /transfers/:pid {#get-transferspid}
+
+Get the current state of a transfer process.
+
+**Request:**
+
+```http
+GET /control-plane/transfers/{pid}
+Authorization: Bearer <trust-token>
+```
+
+_Returns the DSP TransferProcess object with current state and metadata._
+
+### POST /transfers/:pid/start {#post-transferspidstart}
+
+Start an approved transfer.
+
+### POST /transfers/:pid/complete {#post-transferspidcomplete}
+
+Mark a transfer as complete.
+
+### POST /transfers/:pid/suspend {#post-transferspidsuspend}
+
+Suspend a running transfer.
+
+### POST /transfers/:pid/terminate {#post-transferspidterminate}
+
+Terminate a transfer.
+
+_See the main [README.md](../README.md) and [DSP specification](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/) for detailed Transfer Process Protocol documentation._
+
+## Error Handling
+
+All endpoints return errors in the DSP error format when applicable:
+
+**Contract Negotiation Error:**
+
+```json
+{
+  "@context": ["https://w3id.org/dspace/2025/1/context.jsonld"],
+  "@type": "dspace:ContractNegotiationError",
+  "providerPid": "provider-pid-456",
+  "consumerPid": "consumer-pid-123",
+  "code": "ErrorCode:description",
+  "reason": [{ "message": "Human-readable error message", "language": "en" }]
+}
+```
+
+**Transfer Process Error:**
+
+```json
+{
+  "@context": ["https://w3id.org/dspace/2025/1/context.jsonld"],
+  "@type": "dspace:TransferError",
+  "providerPid": "provider-pid-456",
+  "consumerPid": "consumer-pid-123",
+  "code": "ErrorCode:description",
+  "reason": [{ "message": "Human-readable error message", "language": "en" }]
+}
+```
+
+**HTTP Status Codes:**
+
+| Status Code | Description                                      |
+| ----------- | ------------------------------------------------ |
+| 200         | Success                                          |
+| 400         | Bad Request (invalid input)                      |
+| 401         | Unauthorized (missing or invalid authentication) |
+| 404         | Not Found (resource doesn't exist)               |
+| 409         | Conflict (invalid state transition)              |
+| 500         | Internal Server Error                            |
+| 504         | Gateway Timeout (negotiation timeout)            |
+
+## Full Example Workflow
+
+```bash
+#!/bin/bash
+
+# 1. Query provider catalog (not part of Control Plane API)
+CATALOG_RESPONSE=$(curl -X GET https://provider.example.com/catalog \
+  -H "Authorization: Bearer ${TOKEN}")
+OFFER_ID=$(echo $CATALOG_RESPONSE | jq -r '.offers[0].uid')
+
+# 2. Initiate contract negotiation
+NEGOTIATION_RESPONSE=$(curl -X POST https://consumer.example.com/control-plane/negotiations \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"offerId\": \"${OFFER_ID}\",
+    \"providerEndpoint\": \"https://provider.example.com/negotiations\"
+  }")
+
+AGREEMENT_ID=$(echo $NEGOTIATION_RESPONSE | jq -r '.agreementId')
+NEGOTIATION_ID=$(echo $NEGOTIATION_RESPONSE | jq -r '.negotiationId')
+
+echo "Agreement ID: ${AGREEMENT_ID}"
+echo "Negotiation ID: ${NEGOTIATION_ID}"
+
+# 3. (Optional) Check negotiation status
+NEGOTIATION_STATUS=$(curl -X GET \
+  "https://consumer.example.com/control-plane/negotiations/${NEGOTIATION_ID}" \
+  -H "Authorization: Bearer ${TOKEN}")
+
+echo "Negotiation Status: $(echo $NEGOTIATION_STATUS | jq -r '.state')"
+
+# 4. Request transfer using the agreement
+TRANSFER_RESPONSE=$(curl -X POST https://consumer.example.com/control-plane/transfers/request \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"@context\": [\"https://w3id.org/dspace/2025/1/context.jsonld\"],
+    \"@type\": \"TransferRequestMessage\",
+    \"consumerPid\": \"my-consumer-pid-001\",
+    \"agreementId\": \"${AGREEMENT_ID}\",
+    \"callbackAddress\": \"https://consumer.example.com/callbacks\",
+    \"format\": \"application/json\"
+  }")
+
+CONSUMER_PID=$(echo $TRANSFER_RESPONSE | jq -r '.consumerPid')
+echo "Transfer Process ID: ${CONSUMER_PID}"
+
+# 5. Get transfer status
+curl -X GET "https://consumer.example.com/control-plane/transfers/${CONSUMER_PID}" \
+  -H "Authorization: Bearer ${TOKEN}"
+```
+
+## See Also
+
+- [Eclipse Dataspace Protocol Specification](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/)
+- [ODRL (Open Digital Rights Language)](https://www.w3.org/TR/odrl-model/)
+- [Rights Management Contract Negotiation Documentation](../../../../.cursor/docs/dataspace-connector/contract-negotiation/README.md)