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

package/dist/es/dataspaceDataPlaneService.js

@@ -0,0 +1,1077 @@
+// Copyright 2025 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { TaskStatus } from "@twin.org/background-task-models";
+import { ContextIdKeys, ContextIdStore } from "@twin.org/context";
+import { ArrayHelper, ComponentFactory, ConflictError, Converter, GeneralError, GuardError, Guards, Is, NotFoundError, RandomHelper, UnprocessableError, Validation } from "@twin.org/core";
+import { Blake2b } from "@twin.org/crypto";
+import { JsonLdDataTypes, JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
+import { ActivityProcessingStatus, DataRequestType, DataspaceAppFactory } from "@twin.org/dataspace-models";
+import { EngineCoreFactory } from "@twin.org/engine-models";
+import { ComparisonOperator, LogicalOperator } from "@twin.org/entity";
+import { EntityStorageConnectorFactory } from "@twin.org/entity-storage-models";
+import { DataspaceProtocolDataTypes, DataspaceProtocolTransferProcessStateType } from "@twin.org/standards-dataspace-protocol";
+import { SchemaOrgContexts, SchemaOrgDataTypes, SchemaOrgTypes } from "@twin.org/standards-schema-org";
+import { ActivityStreamsDataTypes } from "@twin.org/standards-w3c-activity-streams";
+import { TrustHelper } from "@twin.org/trust-models";
+/**
+ * Dataspace Data Plane Service.
+ */
+export class DataspaceDataPlaneService {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "DataspaceDataPlaneService";
+    /**
+     * Milliseconds per minute (60 * 1000).
+     * @internal
+     */
+    static _MS_PER_MINUTE = 60 * 1000;
+    /**
+     * Minutes per day (24 * 60 = 1440).
+     * @internal
+     */
+    static _MINUTES_PER_DAY = 24 * 60;
+    /**
+     * Milliseconds per day (24 hours).
+     * @internal
+     */
+    static _MS_PER_DAY = 24 * 60 * 60 * 1000;
+    /**
+     * The default cleanup interval in minutes. (1 hour)
+     * @internal
+     */
+    static _DEFAULT_CLEANUP_INTERVAL = 60;
+    /**
+     * The default retain interval in minutes. (10 minutes)
+     * @internal
+     */
+    static _DEFAULT_RETAIN_INTERVAL = 10;
+    /**
+     * Logging service type.
+     * @internal
+     */
+    _loggingComponentType;
+    /**
+     * Logging service.
+     * @internal
+     */
+    _logging;
+    /**
+     * Storage service for activity logging.
+     * @internal
+     */
+    _entityStorageActivityLogs;
+    /**
+     * Storage service for activity tasks.
+     * @internal
+     */
+    _entityStorageActivityTasks;
+    /**
+     * Background Task Component.
+     * @internal
+     */
+    _backgroundTaskComponent;
+    /**
+     * Activity Log Status callbacks.
+     * @internal
+     */
+    _activityLogStatusCallbacks;
+    /**
+     * Task retention. -1 retain forever.
+     * @internal
+     */
+    _retainTasksFor;
+    /**
+     * Activity Log Entry retention. -1 retain forever.
+     * @internal
+     */
+    _retainActivityLogsFor;
+    /**
+     * Clean up interval for activity logs.
+     * @internal
+     */
+    _activityLogCleanUpInterval;
+    /**
+     * Whether there is an ongoing clean up process.
+     * @internal
+     */
+    _cleanUpProcessOngoing;
+    /**
+     * The task scheduler used to clean up activity logs.
+     * @internal
+     */
+    _taskScheduler;
+    /**
+     * The keys to use from the context ids to create partitions.
+     * @internal
+     */
+    _partitionContextIds;
+    /**
+     * The trust component.
+     * @internal
+     */
+    _trustComponent;
+    /**
+     * The policy enforcement point for ODRL policy enforcement.
+     * @internal
+     */
+    _policyEnforcementPoint;
+    /**
+     * Entity storage for Transfer Process entities.
+     * Used to read transfer state from shared storage (written by Control Plane).
+     * @internal
+     */
+    _transferProcessStorage;
+    /**
+     * The list of active tenants required for task cleanup.
+     * @internal
+     */
+    _activeTenants;
+    /**
+     * Create a new instance of DataspaceDataPlane.
+     * @param options The options for the data plane.
+     */
+    constructor(options) {
+        this._loggingComponentType = options?.loggingComponentType ?? "logging";
+        this._logging = ComponentFactory.getIfExists(this._loggingComponentType);
+        this._entityStorageActivityLogs = EntityStorageConnectorFactory.get(options?.activityLogEntityStorageType ?? "activity-log-details");
+        this._entityStorageActivityTasks = EntityStorageConnectorFactory.get(options?.activityTaskEntityStorageType ?? "activity-task");
+        this._backgroundTaskComponent = ComponentFactory.get(options?.backgroundTaskComponentType ?? "background-task");
+        this._taskScheduler = ComponentFactory.get(options?.taskSchedulerComponentType ?? "task-scheduler");
+        this._trustComponent = ComponentFactory.get(options?.trustComponentType ?? "trust");
+        this._policyEnforcementPoint = ComponentFactory.getIfExists(options?.pepComponentType ?? "policy-enforcement-point-service");
+        // Entity storage for Transfer Process state lookup
+        // Used to read transfer state from shared storage (written by Control Plane)
+        this._transferProcessStorage = EntityStorageConnectorFactory.get(options?.transferProcessEntityStorageType ?? "transfer-process");
+        JsonLdDataTypes.registerTypes();
+        ActivityStreamsDataTypes.registerTypes();
+        SchemaOrgDataTypes.registerRedirects();
+        DataspaceProtocolDataTypes.registerRedirects();
+        DataspaceProtocolDataTypes.registerTypes();
+        this._activityLogStatusCallbacks = {};
+        this._activeTenants = [];
+        this._partitionContextIds = options?.partitionContextIds;
+        this._retainTasksFor =
+            DataspaceDataPlaneService._DEFAULT_RETAIN_INTERVAL * DataspaceDataPlaneService._MS_PER_MINUTE;
+        this._retainActivityLogsFor =
+            DataspaceDataPlaneService._DEFAULT_RETAIN_INTERVAL * DataspaceDataPlaneService._MS_PER_MINUTE;
+        this._activityLogCleanUpInterval = DataspaceDataPlaneService._DEFAULT_CLEANUP_INTERVAL;
+        this._cleanUpProcessOngoing = false;
+        const validationErrors = [];
+        if (!Is.empty(options?.config?.retainActivityLogsFor)) {
+            Guards.integer(DataspaceDataPlaneService.CLASS_NAME, "options.config.retainActivityLogsFor", options.config.retainActivityLogsFor);
+            if (options.config.retainActivityLogsFor === -1) {
+                this._retainTasksFor = -1;
+                this._retainActivityLogsFor = -1;
+            }
+            else {
+                Validation.integer("options.config.retainActivityLogsFor", options.config.retainActivityLogsFor, validationErrors, undefined, { minValue: 1 });
+                // Retention of internal tasks launched
+                // 5 minutes of margin with respect to the Activity Log Entry to ensure proper removal
+                this._retainTasksFor =
+                    (options.config.retainActivityLogsFor + 5) * DataspaceDataPlaneService._MS_PER_MINUTE;
+                this._retainActivityLogsFor =
+                    options.config.retainActivityLogsFor * DataspaceDataPlaneService._MS_PER_MINUTE;
+            }
+        }
+        if (!Is.empty(options?.config?.activityLogsCleanUpInterval)) {
+            Guards.integer(DataspaceDataPlaneService.CLASS_NAME, "options.config.activityLogsCleanUpInterval", options.config.activityLogsCleanUpInterval);
+            Validation.integer("options.config.activityLogsCleanUpInterval", options.config.activityLogsCleanUpInterval, validationErrors, undefined, { minValue: 1 });
+            this._activityLogCleanUpInterval = options.config.activityLogsCleanUpInterval;
+        }
+        Validation.asValidationError(DataspaceDataPlaneService.CLASS_NAME, "options.config", validationErrors);
+    }
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className() {
+        return DataspaceDataPlaneService.CLASS_NAME;
+    }
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeLoggingComponentType The node logging component type.
+     */
+    async start(nodeLoggingComponentType) {
+        const engine = EngineCoreFactory.getIfExists("engine");
+        if (Is.empty(engine) || engine.isClone()) {
+            await this._logging?.log({
+                level: "debug",
+                source: DataspaceDataPlaneService.CLASS_NAME,
+                message: "engineCloneStart"
+            });
+            return;
+        }
+        // Only we have a task scheduler if there is a retention different than -1
+        if (this._retainActivityLogsFor !== -1) {
+            const taskTime = [
+                {
+                    nextTriggerTime: Date.now() + 5000,
+                    ...this.calculateCleaningTaskSchedule(this._activityLogCleanUpInterval)
+                }
+            ];
+            await this._taskScheduler.addTask("dataspace-cleanup", taskTime, async () => {
+                await this._logging?.log({
+                    level: "debug",
+                    source: DataspaceDataPlaneService.CLASS_NAME,
+                    message: "scheduledCleanUpTask"
+                });
+                await this.cleanupActivityLog();
+            });
+            await this._logging?.log({
+                level: "debug",
+                source: DataspaceDataPlaneService.CLASS_NAME,
+                message: "taskSchedulerStarted",
+                data: {
+                    taskTime
+                }
+            });
+        }
+    }
+    /**
+     * Notify an Activity.
+     * @param activity The Activity notified.
+     * @returns The Activity's Log Entry identifier.
+     */
+    async notifyActivity(activity) {
+        Guards.object(DataspaceDataPlaneService.CLASS_NAME, "activity", activity);
+        await this.updateActiveTenants();
+        await this._logging?.log({
+            level: "debug",
+            source: DataspaceDataPlaneService.CLASS_NAME,
+            message: "newActivity",
+            data: {
+                activityType: activity.type,
+                generator: this.calculateActivityGeneratorIdentity(activity)
+            }
+        });
+        // Validate that the Activity notified is encoded using the representation format expected
+        const validationFailures = [];
+        await JsonLdHelper.validate(activity, validationFailures, { failOnMissingType: true });
+        Validation.asValidationError(DataspaceDataPlaneService.CLASS_NAME, "activity", validationFailures);
+        // Avoid using terms not defined in any Ld Context
+        const compactedObj = await JsonLdProcessor.compact(activity, activity["@context"]);
+        // Calculate Activity Log Entry Id
+        const canonical = await JsonLdProcessor.canonize(compactedObj);
+        const canonicalBytes = Converter.utf8ToBytes(canonical);
+        const activityLogId = Converter.bytesToHex(Blake2b.sum256(canonicalBytes));
+        const activityLogEntryId = `urn:x-activity-log:${activityLogId}`;
+        // Check if entry already exists
+        const existingLogEntry = await this._entityStorageActivityLogs.get(activityLogEntryId);
+        let existingSuccessfulApps = [];
+        let isRetry = false;
+        if (!Is.undefined(existingLogEntry)) {
+            // Check if there are failed tasks that can be retried
+            const existingEntry = await this.getActivityLogEntry(activityLogEntryId);
+            // If all tasks completed successfully, this is a duplicate
+            if (existingEntry.status === ActivityProcessingStatus.Completed) {
+                throw new ConflictError(DataspaceDataPlaneService.CLASS_NAME, "activityAlreadyNotified", activityLogEntryId);
+            }
+            // If still processing then reject to avoid race conditions
+            if (existingEntry.status === ActivityProcessingStatus.Pending ||
+                existingEntry.status === ActivityProcessingStatus.Running ||
+                existingEntry.status === ActivityProcessingStatus.Registering) {
+                throw new ConflictError(DataspaceDataPlaneService.CLASS_NAME, "activityStillProcessing", activityLogEntryId);
+            }
+            // Status is Error - prepare for retry
+            existingSuccessfulApps = await this.prepareForRetry(activityLogEntryId, existingEntry);
+            isRetry = true;
+        }
+        else {
+            const logEntry = {
+                id: activityLogEntryId,
+                activityId: Is.string(activity.id) ? activity.id : undefined,
+                generator: this.calculateActivityGeneratorIdentity(activity),
+                dateCreated: new Date().toISOString(),
+                dateModified: new Date().toISOString()
+            };
+            await this._entityStorageActivityLogs.set(logEntry);
+        }
+        const activityQuerySet = await this.calculateActivityQuerySet(compactedObj);
+        const tasksScheduled = [];
+        for (const query of activityQuerySet) {
+            const dataspaceAppIds = this.getAppForActivityQuery(query);
+            for (const dataspaceAppId of dataspaceAppIds) {
+                // Only process apps that haven't already completed successfully
+                if (!existingSuccessfulApps.includes(dataspaceAppId)) {
+                    const payload = {
+                        activityLogEntryId,
+                        activity: compactedObj,
+                        executorApp: dataspaceAppId
+                    };
+                    const taskType = Converter.bytesToHex(RandomHelper.generate(16));
+                    const taskId = await this._backgroundTaskComponent.create(taskType, payload, {
+                        retainFor: this._retainTasksFor
+                    });
+                    await this._backgroundTaskComponent.registerHandler(taskType, "@twin.org/dataspace-app-runner", "appRunner", async (task) => {
+                        await this.finaliseTask(task);
+                    }, {
+                        initialiseMethod: "appRunnerStart",
+                        shutdownMethod: "appRunnerEnd"
+                    });
+                    tasksScheduled.push({
+                        taskId,
+                        dataspaceAppId
+                    });
+                    await this._logging?.log({
+                        level: "info",
+                        source: DataspaceDataPlaneService.CLASS_NAME,
+                        message: "scheduledTask",
+                        data: {
+                            taskId,
+                            dataspaceAppId,
+                            isRetry
+                        }
+                    });
+                }
+            }
+        }
+        const existingActivityTasks = isRetry
+            ? await this._entityStorageActivityTasks.get(activityLogEntryId)
+            : undefined;
+        const existingTasksToKeep = existingActivityTasks?.associatedTasks.filter(t => existingSuccessfulApps.includes(t.dataspaceAppId)) ?? [];
+        await this._entityStorageActivityTasks.set({
+            activityLogEntryId,
+            associatedTasks: [...existingTasksToKeep, ...tasksScheduled]
+        });
+        return activityLogEntryId;
+    }
+    /**
+     * Subscribes to the activity log.
+     * @param callback The callback to be called when Activity Log is called.
+     * @param subscriptionId The Subscription Id.
+     * @returns The subscription Id.
+     */
+    async subscribeToActivityLog(callback, subscriptionId) {
+        Guards.function(DataspaceDataPlaneService.CLASS_NAME, "callback", callback);
+        const theSubscriptionId = Is.stringValue(subscriptionId)
+            ? subscriptionId
+            : Converter.bytesToHex(RandomHelper.generate(16));
+        this._activityLogStatusCallbacks[theSubscriptionId] = callback;
+        return theSubscriptionId;
+    }
+    /**
+     * Subscribes to the activity log.
+     * @param subscriptionId The Subscription Id.
+     */
+    async unSubscribeToActivityLog(subscriptionId) {
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "subscriptionId", subscriptionId);
+        delete this._activityLogStatusCallbacks[subscriptionId];
+    }
+    /**
+     * Returns the activity processing details of an activity.
+     * @param logEntryId The Id of the Activity Log Entry (a URI).
+     * @returns the Activity Log Entry with the processing details.
+     * @throws NotFoundError if activity log entry is not known.
+     */
+    async getActivityLogEntry(logEntryId) {
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "logEntryId", logEntryId);
+        const result = await this._entityStorageActivityLogs.get(logEntryId);
+        if (Is.undefined(result)) {
+            throw new NotFoundError(DataspaceDataPlaneService.CLASS_NAME, "activityLogEntryNotFound", logEntryId);
+        }
+        let pendingTasks;
+        let runningTasks;
+        let finalizedTasks;
+        let inErrorTasks;
+        // For calculating the processing status. `Registering` if we cannot determine the activity tasks yet
+        let status = ActivityProcessingStatus.Registering;
+        // Now query the associated tasks
+        const activityTasks = await this._entityStorageActivityTasks.get(logEntryId);
+        // If activity tasks is undefined it is because the corresponding store has not been persisted yet
+        if (!Is.undefined(activityTasks)) {
+            pendingTasks = [];
+            runningTasks = [];
+            finalizedTasks = [];
+            inErrorTasks = [];
+            for (const entity of activityTasks.associatedTasks) {
+                const taskDetails = await this._backgroundTaskComponent.get(entity.taskId);
+                if (Is.object(taskDetails)) {
+                    switch (taskDetails.status) {
+                        case TaskStatus.Success:
+                            finalizedTasks.push({
+                                ...entity,
+                                result: JSON.stringify(taskDetails.result),
+                                startDate: taskDetails?.dateCreated,
+                                endDate: taskDetails?.dateCompleted
+                            });
+                            break;
+                        case TaskStatus.Pending:
+                            pendingTasks.push(entity);
+                            break;
+                        case TaskStatus.Processing:
+                            runningTasks.push({ ...entity, startDate: taskDetails.dateCreated });
+                            break;
+                        case TaskStatus.Failed:
+                            inErrorTasks.push({
+                                ...entity,
+                                error: taskDetails.error
+                            });
+                            break;
+                        case TaskStatus.Cancelled:
+                            // Nothing to do for cancelled tasks
+                            break;
+                    }
+                }
+            }
+            if (Is.arrayValue(inErrorTasks)) {
+                status = ActivityProcessingStatus.Error;
+            }
+            else if (Is.arrayValue(runningTasks)) {
+                status = ActivityProcessingStatus.Running;
+            }
+            else if (Is.arrayValue(pendingTasks)) {
+                status = ActivityProcessingStatus.Pending;
+            }
+            else {
+                status = ActivityProcessingStatus.Completed;
+            }
+        }
+        return { ...result, status, pendingTasks, runningTasks, finalizedTasks, inErrorTasks };
+    }
+    /**
+     * Get Data Asset entities. Allows to retrieve entities by their type or id.
+     * @param entitySet The set of entities to be retrieved.
+     * @param entitySet.jsonLdContext The JSON-LD Context to be used to expand the referred entityType.
+     * @param consumerPid The consumer Process ID from the DSP Transfer Process.
+     * Used to resolve datasetId from the Transfer Process.
+     * @param cursor Pagination details - cursor.
+     * @param limit Pagination details - max number of entities.
+     * @param trustPayload Trust payload to verify the requesters identity.
+     * @returns The entities requested as a JSON-LD Document.
+     */
+    async getDataAssetEntities(entitySet, consumerPid, cursor, limit, trustPayload) {
+        Guards.object(DataspaceDataPlaneService.CLASS_NAME, "entitySet", entitySet);
+        Guards.string(DataspaceDataPlaneService.CLASS_NAME, "entitySet.entityType", entitySet.entityType);
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "consumerPid", consumerPid);
+        const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "getDataAssetEntities");
+        const dataConsumerIdentity = trustInfo.identity;
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "dataConsumerIdentity", dataConsumerIdentity);
+        // Use consumerPid to resolve datasetId via Transfer Process
+        // This validates the transfer token, state, and extracts datasetId
+        const transferContext = await this.validateTransfer(consumerPid, trustPayload);
+        const resolvedDatasetId = transferContext.datasetId;
+        const serviceDataset = await this.getDatasetFromApps(resolvedDatasetId);
+        // Expand entity type if LD context provided
+        let finalType = entitySet.entityType;
+        if (!Is.undefined(entitySet.jsonLdContext)) {
+            const auxiliaryObj = {
+                "@context": entitySet.jsonLdContext,
+                "@type": entitySet.entityType
+            };
+            const expanded = (await JsonLdProcessor.expand(auxiliaryObj))[0];
+            finalType = expanded["@type"]?.[0];
+        }
+        if (Is.undefined(finalType)) {
+            throw new GuardError(DataspaceDataPlaneService.CLASS_NAME, "notExpandableType", "entitySet.entityType", entitySet.entityType);
+        }
+        const datasetId = serviceDataset["@id"];
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "datasetId", datasetId);
+        const appId = await this.getAppForDataAssetQuery({ datasetId });
+        // getAppForDataAssetQuery already validates app exists
+        const app = DataspaceAppFactory.get(appId);
+        const handleDataRequest = app.handleDataRequest?.bind(app);
+        Guards.function(DataspaceDataPlaneService.CLASS_NAME, "handleDataRequest", handleDataRequest);
+        const dataRequest = {
+            type: DataRequestType.DataAssetEntities,
+            dataAsset: serviceDataset,
+            entitySet: {
+                entityType: finalType,
+                entityId: entitySet.entityId
+            }
+        };
+        const { data, cursor: cursorResult } = await handleDataRequest(dataRequest, cursor, limit);
+        let finalData;
+        if (Is.array(data)) {
+            finalData = data;
+        }
+        else {
+            finalData = [data];
+        }
+        const itemList = {
+            "@context": SchemaOrgContexts.Context,
+            type: SchemaOrgTypes.ItemList,
+            itemListElement: finalData
+        };
+        let result = {
+            itemList,
+            cursor: cursorResult
+        };
+        // Apply policy filters from Agreement
+        if (transferContext?.agreement) {
+            const filtered = await this.applyPolicyFilters(result, transferContext.agreement);
+            if (filtered.itemList) {
+                result = filtered;
+            }
+            else {
+                result.itemList[SchemaOrgTypes.ItemListElement] = [];
+            }
+        }
+        return result;
+    }
+    /**
+     * Queries a data asset controlled by this Dataspace App.
+     * @param consumerPid The consumer Process ID from the DSP Transfer Process.
+     * Used to resolve datasetId from the Transfer Process.
+     * @param query The filtering query.
+     * @param cursor Pagination details - cursor.
+     * @param limit Pagination details - max number of entities.
+     * @param trustPayload Trust payload to verify the requesters identity.
+     * @returns The item list and optional cursor for pagination via Link headers.
+     */
+    async queryDataAsset(consumerPid, query, cursor, limit, trustPayload) {
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "consumerPid", consumerPid);
+        Guards.object(DataspaceDataPlaneService.CLASS_NAME, "query", query);
+        Guards.string(DataspaceDataPlaneService.CLASS_NAME, "query.type", query.type);
+        const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "queryDataAsset");
+        const dataConsumerIdentity = trustInfo.identity;
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "dataConsumerIdentity", dataConsumerIdentity);
+        // Use consumerPid to resolve datasetId via Transfer Process
+        // This validates the transfer token, state, and extracts datasetId
+        const transferContext = await this.validateTransfer(consumerPid, trustPayload);
+        const resolvedDatasetId = transferContext.datasetId;
+        const serviceDataset = await this.getDatasetFromApps(resolvedDatasetId);
+        const datasetId = serviceDataset["@id"];
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "datasetId", datasetId);
+        const appId = await this.getAppForDataAssetQuery({ datasetId });
+        const app = DataspaceAppFactory.get(appId);
+        if (!app.supportedQueryTypes().includes(query.type)) {
+            throw new UnprocessableError(DataspaceDataPlaneService.CLASS_NAME, "queryTypeNotSupported", {
+                queryType: query.type
+            });
+        }
+        const dataRequest = {
+            type: DataRequestType.QueryDataAsset,
+            dataAsset: serviceDataset,
+            query
+        };
+        const handleDataRequest = app.handleDataRequest?.bind(app);
+        Guards.function(DataspaceDataPlaneService.CLASS_NAME, "handleDataRequest", handleDataRequest);
+        const { data, cursor: cursorResult } = await handleDataRequest(dataRequest, cursor, limit);
+        let finalData;
+        if (Is.array(data)) {
+            finalData = data;
+        }
+        else {
+            finalData = [data];
+        }
+        const itemList = {
+            "@context": SchemaOrgContexts.Context,
+            type: SchemaOrgTypes.ItemList,
+            itemListElement: finalData
+        };
+        let result = {
+            itemList,
+            cursor: cursorResult
+        };
+        // Apply policy filters from Agreement if using consumerPid flow
+        if (transferContext?.agreement) {
+            const filtered = await this.applyPolicyFilters(result, transferContext.agreement);
+            if (filtered.itemList) {
+                result = filtered;
+            }
+            else {
+                result.itemList[SchemaOrgTypes.ItemListElement] = [];
+            }
+        }
+        return result;
+    }
+    /**
+     * Validate transfer authorization for data requests.
+     * Reads directly from shared TransferProcess entity storage.
+     * @param consumerPid The consumer process ID from the transfer request.
+     * @param trustPayload The trust payload for verification (validates signature and expiry).
+     * @returns The transfer context containing datasetId, agreement, and other transfer details.
+     * @throws GeneralError if transfer process storage is not configured.
+     * @throws NotFoundError if transfer process is not found.
+     * @throws UnauthorizedError if trust verification fails.
+     * @throws GeneralError if transfer is not in STARTED state.
+     */
+    async validateTransfer(consumerPid, trustPayload) {
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "consumerPid", consumerPid);
+        // Verify trust payload (validates JWT signature, expiry, and returns verification info)
+        // The trust verifier handles all token validation including expiry
+        await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "validateTransfer");
+        // Direct lookup from shared entity storage by consumerPid (which is the primary key)
+        const transferProcess = await this._transferProcessStorage.get(consumerPid);
+        if (!transferProcess) {
+            throw new NotFoundError(DataspaceDataPlaneService.CLASS_NAME, "transferProcessNotFound", consumerPid);
+        }
+        // Validate state: must be STARTED
+        if (transferProcess.state !== DataspaceProtocolTransferProcessStateType.STARTED) {
+            throw new GeneralError(DataspaceDataPlaneService.CLASS_NAME, "transferNotInStartedState", {
+                currentState: transferProcess.state
+            });
+        }
+        // Validate datasetId is present
+        if (!Is.stringValue(transferProcess.datasetId)) {
+            throw new GeneralError(DataspaceDataPlaneService.CLASS_NAME, "transferMissingDatasetId");
+        }
+        return this.buildTransferContext(transferProcess);
+    }
+    // ============================================================================
+    // PRIVATE HELPER METHODS
+    // ============================================================================
+    /**
+     * Calculates the activity generator from the generator or actor fields.
+     * @param activity The activity.
+     * @returns The generator's identity.
+     * @throws General Error if no identity is found.
+     * @internal
+     */
+    calculateActivityGeneratorIdentity(activity) {
+        if (Is.stringValue(activity.generator)) {
+            return activity.generator;
+        }
+        if (Is.object(activity.generator) && Is.stringValue(activity.generator.id)) {
+            return activity.generator.id;
+        }
+        if (Is.stringValue(activity.actor)) {
+            return activity.actor;
+        }
+        if (Is.object(activity.actor) && Is.stringValue(activity.actor.id)) {
+            return activity.actor.id;
+        }
+        throw new GuardError(DataspaceDataPlaneService.CLASS_NAME, "invalidActivityGeneratorIdentity", "activity.generator", {
+            generator: activity.generator,
+            actor: activity.actor
+        });
+    }
+    /**
+     * Process activity task finalization.
+     * @param proofEntity The proof entity to process.
+     * @internal
+     */
+    async finaliseTask(task) {
+        const payload = task.payload;
+        if (Is.empty(payload)) {
+            return;
+        }
+        const activityLogEntry = await this._entityStorageActivityLogs.get(payload.activityLogEntryId);
+        if (Is.undefined(activityLogEntry)) {
+            await this._logging?.log({
+                level: "error",
+                source: DataspaceDataPlaneService.CLASS_NAME,
+                message: "unknownActivityLogEntryId",
+                data: {
+                    activityLogEntryId: payload.activityLogEntryId
+                }
+            });
+        }
+        if (task.status === TaskStatus.Success || task.status === TaskStatus.Failed) {
+            for (const callback of Object.values(this._activityLogStatusCallbacks)) {
+                await callback({
+                    activityLogEntryId: payload.activityLogEntryId,
+                    activityId: Is.string(payload.activity.id) ? payload.activity.id : undefined,
+                    taskProcessingStatus: {
+                        dataspaceAppId: payload.executorApp,
+                        taskId: task.id,
+                        taskStatus: task.status
+                    }
+                });
+            }
+            // Now let's see if the full activity processing has completed, if so the entry must be marked for retention
+            if (this._retainActivityLogsFor !== -1) {
+                const entry = await this.getActivityLogEntry(payload.activityLogEntryId);
+                if (entry.status === ActivityProcessingStatus.Completed ||
+                    entry.status === ActivityProcessingStatus.Error) {
+                    const retainUntil = Date.now() + this._retainActivityLogsFor;
+                    await this._entityStorageActivityLogs.set({
+                        id: entry.id,
+                        activityId: entry.activityId,
+                        generator: entry.generator,
+                        dateCreated: entry.dateCreated,
+                        dateModified: entry.dateModified,
+                        retainUntil,
+                        retryCount: entry.retryCount
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Updates the list of active tenants for cleanup tasks.
+     * @internal
+     */
+    async updateActiveTenants() {
+        const contextIds = await ContextIdStore.getContextIds();
+        const tenantId = contextIds?.[ContextIdKeys.Tenant];
+        if (Is.stringValue(tenantId) && !this._activeTenants.includes(tenantId)) {
+            this._activeTenants.push(tenantId);
+        }
+    }
+    /**
+     * Cleans up the activity log by deleting those entries that no longer shall be retained.
+     * @internal
+     */
+    async cleanupActivityLog() {
+        if (this._cleanUpProcessOngoing) {
+            await this._logging?.log({
+                level: "debug",
+                message: "cleanUpOngoing",
+                source: DataspaceDataPlaneService.CLASS_NAME
+            });
+            return;
+        }
+        this._cleanUpProcessOngoing = true;
+        let numRecordsDeleted = 0;
+        if (this._partitionContextIds?.includes(ContextIdKeys.Tenant)) {
+            // The cleanup must be done tenant by tenant
+            // as the data behind the scenes might be partitioned
+            for (const tenantId of this._activeTenants) {
+                const localContextIds = (await ContextIdStore.getContextIds()) ?? {};
+                localContextIds[ContextIdKeys.Tenant] = tenantId;
+                await ContextIdStore.run(localContextIds, async () => {
+                    numRecordsDeleted += await this.cleanupActivityLogPartition();
+                });
+            }
+        }
+        else {
+            numRecordsDeleted += await this.cleanupActivityLogPartition();
+        }
+        await this._logging?.log({
+            level: "debug",
+            message: "activityLogCleanedUp",
+            source: DataspaceDataPlaneService.CLASS_NAME,
+            data: {
+                numRecordsDeleted
+            }
+        });
+        this._cleanUpProcessOngoing = false;
+    }
+    /**
+     * Cleans up the activity log partition for the current context ids.
+     * @returns The number of records deleted in this partition.
+     * @internal
+     */
+    async cleanupActivityLogPartition() {
+        let numRecordsDeleted = 0;
+        try {
+            let cursor;
+            const now = Date.now();
+            do {
+                const result = await this._entityStorageActivityLogs.query({
+                    conditions: [
+                        {
+                            property: "retainUntil",
+                            value: 0,
+                            comparison: ComparisonOperator.GreaterThan
+                        },
+                        {
+                            property: "retainUntil",
+                            value: now,
+                            comparison: ComparisonOperator.LessThan
+                        }
+                    ],
+                    logicalOperator: LogicalOperator.And
+                });
+                cursor = result.cursor;
+                for (const entity of result.entities) {
+                    const logEntryDetails = await this.getActivityLogEntry(entity.id);
+                    if (logEntryDetails.status === ActivityProcessingStatus.Completed ||
+                        logEntryDetails.status === ActivityProcessingStatus.Error) {
+                        await this._entityStorageActivityLogs.remove(entity.id);
+                        await this._entityStorageActivityTasks.remove(entity.id);
+                        numRecordsDeleted++;
+                    }
+                }
+            } while (Is.stringValue(cursor));
+        }
+        catch {
+            // If cleaning up the retained items fail we don't really care, they will get cleaned up on the next sweep.
+        }
+        return numRecordsDeleted;
+    }
+    /**
+     * Calculates the (Activity, Object, Target) query set.
+     * @param compactedObj The compactObj representing the Activity.
+     * @returns the (Activity, Object, Target) query set.
+     * @internal
+     */
+    async calculateActivityQuerySet(compactedObj) {
+        const expanded = await JsonLdProcessor.expand({
+            "@context": compactedObj["@context"],
+            "@type": compactedObj.type
+        });
+        const expandedDoc = expanded[0];
+        const activityTypes = expandedDoc["@type"];
+        if (!Is.arrayValue(activityTypes)) {
+            throw new GuardError(DataspaceDataPlaneService.CLASS_NAME, "invalidActivity", "compactedObj.type", compactedObj.type);
+        }
+        const objects = ArrayHelper.fromObjectOrArray(compactedObj?.object);
+        if (Is.arrayValue(objects)) {
+            for (const obj of objects) {
+                if (Is.object(obj) && Is.empty(obj["@context"])) {
+                    obj["@context"] = compactedObj["@context"];
+                }
+            }
+        }
+        const objectExpanded = await JsonLdProcessor.expand(compactedObj.object);
+        const objectTypes = objectExpanded[0]["@type"];
+        if (!Is.arrayValue(objectTypes)) {
+            throw new GuardError(DataspaceDataPlaneService.CLASS_NAME, "invalidActivity", "objectTypes", compactedObj);
+        }
+        let targetTypes = [""];
+        if (Is.object(compactedObj.target)) {
+            if (Is.undefined(compactedObj.target["@context"])) {
+                compactedObj.target["@context"] = compactedObj["@context"];
+            }
+            const targetExpanded = await JsonLdProcessor.expand(compactedObj.target);
+            targetTypes = targetExpanded[0]["@type"];
+            if (!Is.arrayValue(targetTypes)) {
+                throw new GuardError(DataspaceDataPlaneService.CLASS_NAME, "invalidActivity", "compactedObj.target.type", compactedObj.target?.type);
+            }
+        }
+        const result = [];
+        for (const activityType of activityTypes) {
+            for (const objectType of objectTypes) {
+                for (const targetType of targetTypes) {
+                    const query = {
+                        activityType,
+                        objectType,
+                        targetType: !Is.stringValue(targetType) ? undefined : targetType
+                    };
+                    result.push(query);
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Calculates the cleaning task schedule.
+     * @param minutes The period in minutes.
+     * @returns The cleaning task schedule.
+     * @internal
+     */
+    calculateCleaningTaskSchedule(minutes) {
+        let minutesRemain = minutes;
+        const days = Math.floor(minutesRemain / DataspaceDataPlaneService._MINUTES_PER_DAY);
+        minutesRemain %= DataspaceDataPlaneService._MINUTES_PER_DAY;
+        const hours = Math.floor(minutesRemain / 60);
+        minutesRemain %= 60;
+        return { intervalDays: days, intervalHours: hours, intervalMinutes: minutesRemain };
+    }
+    /**
+     * Returns an App for a (Activity, Object, Target).
+     * @param activityQuery The (Activity, Object, Target) query specified using a FQN.
+     * @returns The Dataspace Data Plane Apps or empty list if nothing is registered.
+     * @internal
+     */
+    getAppForActivityQuery(activityQuery) {
+        const matchingElements = [];
+        const appNames = DataspaceAppFactory.names();
+        for (const appId of appNames) {
+            const app = DataspaceAppFactory.get(appId);
+            const appQueries = app.activitiesHandled();
+            for (const appQuery of appQueries) {
+                if (appQuery.objectType === activityQuery.objectType &&
+                    (Is.undefined(appQuery.activityType) ||
+                        appQuery.activityType === activityQuery.activityType) &&
+                    (Is.undefined(appQuery.targetType) || appQuery.targetType === activityQuery.targetType)) {
+                    matchingElements.push(appId);
+                }
+            }
+        }
+        return matchingElements;
+    }
+    /**
+     * Get a dataset from registered apps by its ID.
+     * @param datasetId The dataset identifier (@id)
+     * @returns The dataset
+     * @throws NotFoundError if no app handles this dataset
+     * @internal
+     */
+    async getDatasetFromApps(datasetId) {
+        Guards.stringValue(DataspaceDataPlaneService.CLASS_NAME, "datasetId", datasetId);
+        const appNames = DataspaceAppFactory.names();
+        for (const appId of appNames) {
+            const app = DataspaceAppFactory.get(appId);
+            const datasets = await app.datasetsHandled();
+            const dataset = datasets.find(d => d["@id"] === datasetId);
+            if (dataset) {
+                return dataset;
+            }
+        }
+        throw new NotFoundError(DataspaceDataPlaneService.CLASS_NAME, "noAppRegistered", datasetId, {
+            datasetId
+        });
+    }
+    /**
+     * Returns an App for a Data Asset query (datasetId, ...).
+     * @param dataAssetQuery The data asset query.
+     * @returns The Dataspace Data Plane App ID.
+     * @internal
+     */
+    async getAppForDataAssetQuery(dataAssetQuery) {
+        const matchingElements = [];
+        const appNames = DataspaceAppFactory.names();
+        for (const appId of appNames) {
+            const app = DataspaceAppFactory.get(appId);
+            const datasets = await app.datasetsHandled();
+            for (const dataset of datasets) {
+                if (dataset["@id"] === dataAssetQuery.datasetId) {
+                    matchingElements.push(appId);
+                }
+            }
+        }
+        if (matchingElements.length > 1) {
+            const error = new ConflictError(DataspaceDataPlaneService.CLASS_NAME, "tooManyAppsRegistered", dataAssetQuery.datasetId, matchingElements, {
+                datasetId: dataAssetQuery.datasetId
+            });
+            await this._logging?.log({
+                source: DataspaceDataPlaneService.CLASS_NAME,
+                level: "error",
+                message: "tooManyAppsRegistered",
+                error,
+                data: {
+                    datasetId: dataAssetQuery.datasetId
+                }
+            });
+            throw error;
+        }
+        if (!Is.arrayValue(matchingElements)) {
+            const error = new NotFoundError(DataspaceDataPlaneService.CLASS_NAME, "noAppRegistered", dataAssetQuery.datasetId, {
+                datasetId: dataAssetQuery.datasetId
+            });
+            await this._logging?.log({
+                source: DataspaceDataPlaneService.CLASS_NAME,
+                level: "error",
+                message: "noAppRegistered",
+                error,
+                data: {
+                    datasetId: dataAssetQuery.datasetId
+                }
+            });
+            throw error;
+        }
+        return matchingElements[0];
+    }
+    /**
+     * Prepare an activity for retry by updating metadata and returning apps to skip.
+     * @param activityLogEntryId The activity log entry ID.
+     * @param existingEntry The existing activity log entry with error status.
+     * @returns Array of app IDs that already succeeded and should be skipped.
+     * @internal
+     */
+    async prepareForRetry(activityLogEntryId, existingEntry) {
+        const appsToRetry = existingEntry.inErrorTasks?.map(t => t.dataspaceAppId) ?? [];
+        if (!Is.arrayValue(appsToRetry)) {
+            throw new NotFoundError(DataspaceDataPlaneService.CLASS_NAME, "noFailedTasksToRetry", activityLogEntryId);
+        }
+        const successfulApps = existingEntry.finalizedTasks?.map(t => t.dataspaceAppId) ?? [];
+        await this._logging?.log({
+            level: "debug",
+            source: DataspaceDataPlaneService.CLASS_NAME,
+            message: "replacingFailedTasks",
+            data: {
+                activityLogEntryId,
+                appsToRetry,
+                successfulApps
+            }
+        });
+        const logEntry = await this._entityStorageActivityLogs.get(activityLogEntryId);
+        if (logEntry) {
+            logEntry.dateModified = new Date().toISOString();
+            // Extend retention to allow retry to complete
+            if (this._retainActivityLogsFor !== -1) {
+                logEntry.retainUntil = Date.now() + this._retainActivityLogsFor;
+            }
+            // Monitoring purposes
+            logEntry.retryCount = (logEntry.retryCount ?? 0) + 1;
+            await this._entityStorageActivityLogs.set(logEntry);
+        }
+        return successfulApps;
+    }
+    /**
+     * Build transfer context from a TransferProcessEntity.
+     * @param transferProcess The transfer process entity.
+     * @returns The transfer context for use by data access methods.
+     * @internal
+     */
+    buildTransferContext(transferProcess) {
+        // Build the IOdrlAgreement from stored data
+        // The entity stores agreementId and policies separately
+        //
+        // NOTE: Currently policies are cached in the TransferProcessEntity at transfer start time.
+        // Eventually, this should fetch fresh policies from Rights Management (PAP) using:
+        //   const freshAgreement = await this._policyAdministrationPoint.get(transferProcess.agreementId);
+        // This would ensure policies are always up-to-date and support dynamic policy updates.
+        const agreement = {
+            "@context": "http://www.w3.org/ns/odrl.jsonld",
+            "@type": "Agreement",
+            uid: transferProcess.agreementId,
+            target: transferProcess.datasetId,
+            // Provider is the assigner, consumer is the assignee
+            assigner: transferProcess.providerIdentity ?? "",
+            assignee: transferProcess.consumerIdentity ?? ""
+        };
+        // Extract policies from the stored Agreement
+        // Extract permission, prohibition, and obligation
+        if (Is.arrayValue(transferProcess.policies)) {
+            const storedAgreement = transferProcess.policies[0];
+            if (storedAgreement) {
+                agreement.permission = storedAgreement.permission;
+                agreement.prohibition = storedAgreement.prohibition;
+                agreement.obligation = storedAgreement.obligation;
+            }
+        }
+        const state = transferProcess.state;
+        const dataAddress = transferProcess.dataAddress;
+        return {
+            consumerPid: transferProcess.consumerPid,
+            providerPid: transferProcess.providerPid,
+            agreement,
+            datasetId: transferProcess.datasetId,
+            offerId: transferProcess.offerId,
+            state,
+            consumerIdentity: transferProcess.consumerIdentity,
+            providerIdentity: transferProcess.providerIdentity,
+            dataAddress
+        };
+    }
+    /**
+     * Apply ODRL policy enforcement to query results.
+     * Delegates to the Policy Enforcement Point (PEP) which coordinates
+     * PDP, arbiters, and enforcement processors.
+     * @param result The data asset item list result to filter.
+     * @param agreement The ODRL Agreement containing policies.
+     * @returns The result with policies applied.
+     * @internal
+     */
+    async applyPolicyFilters(result, agreement) {
+        if (!agreement || !this._policyEnforcementPoint) {
+            return result;
+        }
+        const processed = await this._policyEnforcementPoint.interceptWithPolicy(agreement, result);
+        if (Is.arrayValue(agreement.obligation)) {
+            await this.logObligations(agreement.obligation, agreement.uid);
+        }
+        return processed;
+    }
+    /**
+     * Log ODRL obligations for auditing purposes.
+     * Obligations are duties that must be fulfilled as part of the agreement.
+     * @param obligations The obligation rules from the Agreement.
+     * @param agreementId The agreement ID for reference.
+     * @internal
+     */
+    async logObligations(obligations, agreementId) {
+        if (!Is.arrayValue(obligations)) {
+            return;
+        }
+        for (const obligation of obligations) {
+            await this._logging?.log({
+                level: "info",
+                source: DataspaceDataPlaneService.CLASS_NAME,
+                message: "policyObligationTriggered",
+                data: {
+                    agreementId,
+                    action: obligation.action,
+                    target: obligation.target,
+                    assignee: obligation.assignee
+                }
+            });
+        }
+    }
+}
+//# sourceMappingURL=dataspaceDataPlaneService.js.map