@twin.org/dataspace-control-plane-service 0.0.3-next.26 → 0.0.3-next.27

package/dist/es/dataspaceControlPlaneService.js

@@ -3,6 +3,7 @@ import { ArrayHelper, BaseError, ComponentFactory, Converter, GeneralError, Guar
 import { JsonLdHelper } from "@twin.org/data-json-ld";
 import { DataspaceAppFactory, TransferProcessRole } from "@twin.org/dataspace-models";
 import { EngineCoreFactory } from "@twin.org/engine-models";
+import { ComparisonOperator } from "@twin.org/entity";
 import { EntityStorageConnectorFactory } from "@twin.org/entity-storage-models";
 import { OdrlPolicyHelper, PolicyRequesterFactory } from "@twin.org/rights-management-models";
 import { DataspaceProtocolContexts, DataspaceProtocolContractNegotiationTypes, DataspaceProtocolEndpointType, DataspaceProtocolHelper, DataspaceProtocolTransferProcessStateType, DataspaceProtocolTransferProcessTypes } from "@twin.org/standards-dataspace-protocol";
@@ -69,6 +70,11 @@ export class DataspaceControlPlaneService {
      * @internal
      */
     _transferProcessStorage;
+    /**
+     * Entity storage for tenant-supplied Dataspace App Dataset entities.
+     * @internal
+     */
+    _dataspaceAppDatasetStorage;
     /**
      * The trust component for token verification and generation.
      * @internal
@@ -101,6 +107,11 @@ export class DataspaceControlPlaneService {
      * @internal
      */
     _negotiationCallbacks;
+    /**
+     * The component type name for the hosting component.
+     * @internal
+     */
+    _urlTransformerComponent;
     /**
      * Create a new instance of DataspaceControlPlaneService.
      * @param options The options for the service.
@@ -118,12 +129,14 @@ export class DataspaceControlPlaneService {
         // Retrieve Federated Catalogue component with default
         this._federatedCatalogueComponent = ComponentFactory.get(options?.federatedCatalogueComponentType ?? "federated-catalogue");
         this._transferProcessStorage = EntityStorageConnectorFactory.get(options?.transferProcessEntityStorageType ?? "transfer-process");
+        this._dataspaceAppDatasetStorage = EntityStorageConnectorFactory.get(options?.dataspaceAppDatasetEntityStorageType ?? "dataspace-app-dataset");
         this._trustComponent = ComponentFactory.get(options?.trustComponentType ?? "trust");
         this._overrideTrustGeneratorType = options?.config?.overrideTrustGeneratorType;
         this._dataPlanePath = Is.stringValue(options?.config?.dataPlanePath)
             ? StringHelper.trimLeadingSlashes(options.config.dataPlanePath)
             : undefined;
         this._taskScheduler = ComponentFactory.getIfExists(options?.taskSchedulerComponentType ?? "task-scheduler");
+        this._urlTransformerComponent = ComponentFactory.get(options?.urlTransformerComponentType ?? "url-transformer");
         this._negotiationCallbacks = new Map();
         const internalCallback = {
             onStateChanged: async (negotiationId, state, data) => {
@@ -206,7 +219,9 @@ export class DataspaceControlPlaneService {
     /**
      * 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.
+     * and starts the stalled negotiation cleanup task. Also captures the node
+     * identity from ContextIdStore when tenant-token encryption is configured
+     * (required to derive the vault key name `${nodeId}/${signingKeyName}`).
      * @param nodeLoggingComponentType The node logging component type.
      */
     async start(nodeLoggingComponentType) {
@@ -227,28 +242,20 @@ export class DataspaceControlPlaneService {
             source: DataspaceControlPlaneService.CLASS_NAME,
             message: "populatingFederatedCatalogue"
         });
-        // Get all registered apps
-        const appNames = DataspaceAppFactory.names();
-        await this._loggingComponent?.log({
-            level: "debug",
-            ts: Date.now(),
-            source: DataspaceControlPlaneService.CLASS_NAME,
-            message: "discoveredApps",
-            data: { count: appNames.length, apps: appNames }
-        });
         let registeredCount = 0;
         let errorCount = 0;
-        // Collect and register datasets from each app
-        for (const appName of appNames) {
-            try {
-                const app = DataspaceAppFactory.get(appName);
-                const datasets = await app.datasetsHandled();
-                for (const dataset of datasets) {
+        let totalDatasets = 0;
+        // Walk stored dataspace app datasets one page at a time and publish each in its
+        // owning tenant's context. Memory stays bounded to one page.
+        let cursor;
+        do {
+            const page = await this._dataspaceAppDatasetStorage.query(undefined, undefined, undefined, cursor);
+            if (Is.arrayValue(page.entities)) {
+                for (const entity of page.entities) {
+                    const appDataset = entity;
+                    totalDatasets++;
                     try {
-                        // Ensure publisher is set (required for Federated Catalogue)
-                        const datasetWithPublisher = await this.ensurePublisher(dataset);
-                        // Register with Federated Catalogue
-                        await this._federatedCatalogueComponent.set(datasetWithPublisher);
+                        await this.publishAppDataset(appDataset);
                         registeredCount++;
                         await this._loggingComponent?.log({
                             level: "debug",
@@ -256,8 +263,9 @@ export class DataspaceControlPlaneService {
                             source: DataspaceControlPlaneService.CLASS_NAME,
                             message: "datasetRegistered",
                             data: {
-                                datasetId: getJsonLdId(datasetWithPublisher) ?? "",
-                                appName
+                                datasetId: appDataset.id,
+                                appId: appDataset.appId,
+                                tenantId: appDataset.tenantId
                             }
                         });
                     }
@@ -267,27 +275,19 @@ export class DataspaceControlPlaneService {
                             level: "error",
                             ts: Date.now(),
                             source: DataspaceControlPlaneService.CLASS_NAME,
-                            message: "datasetRegistrationFailed",
+                            message: "datasetPublishFailed",
                             error: BaseError.fromError(error),
                             data: {
-                                datasetId: getJsonLdId(dataset) ?? "",
-                                appName
+                                datasetRecordId: appDataset.id,
+                                appId: appDataset.appId,
+                                tenantId: appDataset.tenantId
                             }
                         });
                     }
                 }
             }
-            catch (error) {
-                await this._loggingComponent?.log({
-                    level: "error",
-                    ts: Date.now(),
-                    source: DataspaceControlPlaneService.CLASS_NAME,
-                    message: "appDatasetsRetrievalFailed",
-                    error: BaseError.fromError(error),
-                    data: { appName }
-                });
-            }
-        }
+            cursor = page.cursor;
+        } while (Is.stringValue(cursor));
         await this._loggingComponent?.log({
             level: "info",
             ts: Date.now(),
@@ -296,7 +296,7 @@ export class DataspaceControlPlaneService {
             data: {
                 registeredCount,
                 errorCount,
-                totalApps: appNames.length
+                totalDatasets
             }
         });
         if (this._taskScheduler) {
@@ -336,7 +336,7 @@ export class DataspaceControlPlaneService {
     async requestTransfer(request, trustPayload) {
         const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "requestTransfer");
         const validationFailures = await DataspaceProtocolHelper.validate(JsonLdHelper.toNodeObject(request));
-        if (validationFailures.length > 0) {
+        if (Is.arrayValue(validationFailures)) {
             await this._loggingComponent?.log({
                 level: "error",
                 source: DataspaceControlPlaneService.CLASS_NAME,
@@ -445,7 +445,7 @@ export class DataspaceControlPlaneService {
     async startTransfer(message, publicOrigin, trustPayload) {
         const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "startTransfer");
         const validationFailures = await DataspaceProtocolHelper.validate(JsonLdHelper.toNodeObject(message));
-        if (validationFailures.length > 0) {
+        if (Is.arrayValue(validationFailures)) {
             await this._loggingComponent?.log({
                 level: "error",
                 source: DataspaceControlPlaneService.CLASS_NAME,
@@ -527,7 +527,12 @@ export class DataspaceControlPlaneService {
                     }
                 });
                 const tokenString = accessToken;
-                const fullEndpoint = `${publicOrigin}/${this._dataPlanePath}`;
+                let fullEndpoint = `${publicOrigin}/${this._dataPlanePath}`;
+                const contextIds = await ContextIdStore.getContextIds();
+                const tenantId = contextIds?.[ContextIdKeys.Tenant];
+                if (Is.stringValue(tenantId)) {
+                    fullEndpoint = await this._urlTransformerComponent.addEncryptedQueryParamToUrl(fullEndpoint, "tenant", tenantId);
+                }
                 response.dataAddress = {
                     "@type": DataspaceProtocolTransferProcessTypes.DataAddress,
                     endpointType: DataspaceProtocolEndpointType.HttpsQueryEndpoint,
@@ -607,7 +612,7 @@ export class DataspaceControlPlaneService {
     async completeTransfer(message, trustPayload) {
         const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "completeTransfer");
         const validationFailures = await DataspaceProtocolHelper.validate(JsonLdHelper.toNodeObject(message));
-        if (validationFailures.length > 0) {
+        if (Is.arrayValue(validationFailures)) {
             await this._loggingComponent?.log({
                 level: "error",
                 source: DataspaceControlPlaneService.CLASS_NAME,
@@ -662,7 +667,7 @@ export class DataspaceControlPlaneService {
     async suspendTransfer(message, trustPayload) {
         const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "suspendTransfer");
         const validationFailures = await DataspaceProtocolHelper.validate(JsonLdHelper.toNodeObject(message));
-        if (validationFailures.length > 0) {
+        if (Is.arrayValue(validationFailures)) {
             await this._loggingComponent?.log({
                 level: "error",
                 source: DataspaceControlPlaneService.CLASS_NAME,
@@ -718,7 +723,7 @@ export class DataspaceControlPlaneService {
     async terminateTransfer(message, trustPayload) {
         const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "terminateTransfer");
         const validationFailures = await DataspaceProtocolHelper.validate(JsonLdHelper.toNodeObject(message));
-        if (validationFailures.length > 0) {
+        if (Is.arrayValue(validationFailures)) {
             await this._loggingComponent?.log({
                 level: "error",
                 source: DataspaceControlPlaneService.CLASS_NAME,
@@ -1115,6 +1120,144 @@ export class DataspaceControlPlaneService {
             dataAddress: entity.dataAddress
         };
     }
+    /**
+     * Register a dataset for a dataspace app, owned by the calling tenant.
+     * @param id Optional explicit id. If omitted, derived from `dataset["@id"]`
+     * or generated.
+     * @param appId The dataspace app this dataset belongs to.
+     * @param dataset The dataset payload.
+     * @returns The resolved dataset id.
+     */
+    async createAppDataset(id, appId, dataset) {
+        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "appId", appId);
+        Guards.object(DataspaceControlPlaneService.CLASS_NAME, "dataset", dataset);
+        const resolvedId = id ??
+            (Is.stringValue(dataset["@id"]) ? dataset["@id"] : RandomHelper.generateUuidV7("compact"));
+        const tenantId = await this.resolveCallingTenantId();
+        const nodeIdentity = await this.resolveNodeIdentity();
+        const existing = await this._dataspaceAppDatasetStorage.get(resolvedId);
+        if (!Is.empty(existing)) {
+            throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "datasetAlreadyExists", {
+                id: resolvedId
+            });
+        }
+        const now = new Date().toISOString();
+        const entity = {
+            id: resolvedId,
+            nodeIdentity,
+            tenantId,
+            appId,
+            dataset: this.stripDatasetId(dataset),
+            dateCreated: now,
+            dateModified: now
+        };
+        // Side effect first, primary storage last
+        await this.publishAppDataset(entity);
+        await this._dataspaceAppDatasetStorage.set(entity);
+        return resolvedId;
+    }
+    /**
+     * Get a dataset record owned by the calling tenant.
+     * @param id The stored dataset id.
+     * @returns The stored dataset record.
+     */
+    async getAppDataset(id) {
+        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "id", id);
+        const tenantId = await this.resolveCallingTenantId();
+        const entity = await this._dataspaceAppDatasetStorage.get(id);
+        if (Is.empty(entity)) {
+            throw new NotFoundError(DataspaceControlPlaneService.CLASS_NAME, "datasetNotFound", id);
+        }
+        if (entity.tenantId !== tenantId) {
+            throw new UnauthorizedError(DataspaceControlPlaneService.CLASS_NAME, "datasetWrongTenant");
+        }
+        return {
+            id: entity.id,
+            appId: entity.appId,
+            dataset: this.restampDatasetId(entity.dataset, entity.id),
+            dateCreated: entity.dateCreated,
+            dateModified: entity.dateModified
+        };
+    }
+    /**
+     * List the dataspace app datasets owned by the calling tenant.
+     * @param cursor Optional pagination cursor.
+     * @param limit Optional maximum number of entries to return.
+     * @returns The stored datasets and the next-page cursor if more exist.
+     */
+    async listAppDatasets(cursor, limit) {
+        const tenantId = await this.resolveCallingTenantId();
+        const page = await this._dataspaceAppDatasetStorage.query(Is.stringValue(tenantId)
+            ? {
+                property: "tenantId",
+                value: tenantId,
+                comparison: ComparisonOperator.Equals
+            }
+            : undefined, undefined, undefined, cursor, limit);
+        const entities = (page.entities ?? []).map(entity => ({
+            id: entity.id ?? "",
+            appId: entity.appId ?? "",
+            dataset: this.restampDatasetId(entity.dataset ?? {}, entity.id ?? ""),
+            dateCreated: entity.dateCreated ?? "",
+            dateModified: entity.dateModified ?? ""
+        }));
+        return {
+            entities,
+            cursor: page.cursor
+        };
+    }
+    /**
+     * Update a dataset record owned by the calling tenant.
+     * @param id The stored dataset id.
+     * @param appId The dataspace app this dataset belongs to.
+     * @param dataset The dataset payload.
+     */
+    async updateAppDataset(id, appId, dataset) {
+        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "id", id);
+        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "appId", appId);
+        Guards.object(DataspaceControlPlaneService.CLASS_NAME, "dataset", dataset);
+        const tenantId = await this.resolveCallingTenantId();
+        const existing = await this._dataspaceAppDatasetStorage.get(id);
+        if (Is.empty(existing)) {
+            throw new NotFoundError(DataspaceControlPlaneService.CLASS_NAME, "datasetNotFound", id);
+        }
+        if (existing.tenantId !== tenantId) {
+            throw new UnauthorizedError(DataspaceControlPlaneService.CLASS_NAME, "datasetWrongTenant");
+        }
+        const updated = {
+            ...existing,
+            appId,
+            dataset: this.stripDatasetId(dataset),
+            dateModified: new Date().toISOString()
+        };
+        // Side effect first, primary storage last
+        await this.publishAppDataset(updated);
+        await this._dataspaceAppDatasetStorage.set(updated);
+    }
+    /**
+     * Delete a dataspace app dataset owned by the calling tenant.
+     * @param id The stored app dataset id.
+     */
+    async deleteAppDataset(id) {
+        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "id", id);
+        const tenantId = await this.resolveCallingTenantId();
+        const existing = await this._dataspaceAppDatasetStorage.get(id);
+        if (Is.empty(existing)) {
+            throw new NotFoundError(DataspaceControlPlaneService.CLASS_NAME, "datasetNotFound", id);
+        }
+        if (existing.tenantId !== tenantId) {
+            throw new UnauthorizedError(DataspaceControlPlaneService.CLASS_NAME, "datasetWrongTenant");
+        }
+        // Side effect first, primary storage last
+        const wrappedContextIds = {
+            ...((await ContextIdStore.getContextIds()) ?? {}),
+            [ContextIdKeys.Tenant]: existing.tenantId
+        };
+        await ContextIdStore.run(wrappedContextIds, async () => {
+            await this._federatedCatalogueComponent.remove(id);
+        });
+        await this._dataspaceAppDatasetStorage.remove(id);
+    }
     // ============================================================================
     // PRIVATE HELPER METHODS
     // ============================================================================
@@ -1155,7 +1298,7 @@ export class DataspaceControlPlaneService {
                 }
             }
         }
-        if (stalled.length > 0) {
+        if (Is.arrayValue(stalled)) {
             await this._loggingComponent?.log({
                 level: "info",
                 source: DataspaceControlPlaneService.CLASS_NAME,
@@ -1283,20 +1426,21 @@ export class DataspaceControlPlaneService {
                 agreementId: OdrlPolicyHelper.getUid(agreement)
             });
         }
-        const targetIds = OdrlPolicyHelper.getTargets(agreement);
-        if (targetIds.length === 0) {
+        // Top-level target identifies the dataset; rule-level targets are constraint
+        // scopes (refinements, JSONPath filters, AssetCollections) and aren't datasets.
+        const datasetTargets = OdrlPolicyHelper.getDatasetTargets(agreement);
+        if (!Is.arrayValue(datasetTargets)) {
             throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "agreementTargetMissingUid", {
                 agreementId: OdrlPolicyHelper.getUid(agreement)
             });
         }
-        // Validate single target, multiple targets are not currently supported
-        if (targetIds.length > 1) {
+        if (datasetTargets.length > 1) {
             throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "agreementMultipleTargetsNotSupported", {
                 agreementId: OdrlPolicyHelper.getUid(agreement),
-                targetCount: targetIds.length
+                targetCount: datasetTargets.length
             });
         }
-        return targetIds[0];
+        return datasetTargets[0];
     }
     /**
      * Validate that the dataset exists in the Federated Catalogue.
@@ -1478,12 +1622,12 @@ export class DataspaceControlPlaneService {
         // the target is implicitly the Dataset. When the catalogue offer has no targets,
         // skip the target comparison entirely (the agreement's target is the dataset itself).
         // Only reject if both have explicit targets that don't overlap.
-        if (offerTargets.length > 0 && agreementTargets.length > 0) {
+        if (Is.arrayValue(offerTargets) && Is.arrayValue(agreementTargets)) {
             if (!agreementTargets.some((agreementTarget) => offerTargets.includes(agreementTarget))) {
                 return false;
             }
         }
-        else if (offerTargets.length > 0 && agreementTargets.length === 0) {
+        else if (Is.arrayValue(offerTargets) && !Is.arrayValue(agreementTargets)) {
             // Offer has targets but agreement doesn't — mismatch
             return false;
         }
@@ -1502,24 +1646,92 @@ export class DataspaceControlPlaneService {
         return true;
     }
     /**
-     * Ensure the dataset has a publisher set.
-     * @param dataset The dataset.
-     * @returns The dataset with publisher set.
+     * Populate the system-controlled fields of a dataset payload.
+     * @param dataset The user-supplied dataset payload.
+     * @returns The populated dataset.
      * @internal
      */
-    async ensurePublisher(dataset) {
+    async populateDefaults(dataset) {
         if (dataset["dcterms:publisher"]) {
             return dataset;
         }
         const contextIds = await ContextIdStore.getContextIds();
         const orgId = contextIds?.[ContextIdKeys.Organization];
         if (orgId) {
-            return {
-                ...dataset,
-                "dcterms:publisher": orgId
-            };
+            return { ...dataset, "dcterms:publisher": orgId };
         }
         return dataset;
     }
+    /**
+     * Strip `@id` from a dataset payload before storing it.
+     * @param dataset The dataset payload.
+     * @returns The dataset payload with `@id` removed.
+     * @internal
+     */
+    stripDatasetId(dataset) {
+        const copy = { ...dataset };
+        delete copy["@id"];
+        return copy;
+    }
+    /**
+     * Re-stamp `@id` onto a stored payload blob using the entity primary key.
+     * @param payload The stored payload blob (without `@id`).
+     * @param id The entity id (becomes the dataset's `@id`).
+     * @returns The dataset payload with `@id` populated.
+     * @internal
+     */
+    restampDatasetId(payload, id) {
+        return { ...payload, "@id": id };
+    }
+    // DATASPACE APP DATASET HANDLERS
+    /**
+     * Publish a single dataspace app dataset to the federated catalogue in its owning tenant's context.
+     * @param appDataset The stored dataspace app dataset entity.
+     * @internal
+     */
+    async publishAppDataset(appDataset) {
+        // Override `Tenant` in the context wrap so federated catalogue captures the
+        // appDataset's owning tenant. On single-tenant nodes the appDataset has no tenantId,
+        // so the assignment writes `Tenant: undefined` — equivalent to no override.
+        const wrappedContextIds = {
+            ...((await ContextIdStore.getContextIds()) ?? {}),
+            [ContextIdKeys.Tenant]: appDataset.tenantId
+        };
+        await ContextIdStore.run(wrappedContextIds, async () => {
+            const app = DataspaceAppFactory.get(appDataset.appId);
+            const datasetPayload = this.restampDatasetId(appDataset.dataset, appDataset.id);
+            const overrideHandler = app.datasetsHandled?.bind(app);
+            const rawDatasets = overrideHandler
+                ? await overrideHandler(datasetPayload, appDataset.tenantId ?? "")
+                : [datasetPayload];
+            const datasets = await Promise.all(rawDatasets.map(async (d) => this.populateDefaults(d)));
+            for (const dataset of datasets) {
+                await this._federatedCatalogueComponent.set(dataset);
+            }
+        });
+    }
+    /**
+     * Resolve the calling tenant from the request context.
+     * @returns The owning tenant id, or undefined for single-tenant nodes.
+     * @internal
+     */
+    async resolveCallingTenantId() {
+        const contextIds = await ContextIdStore.getContextIds();
+        const tenantId = contextIds?.[ContextIdKeys.Tenant];
+        return Is.stringValue(tenantId) ? tenantId : undefined;
+    }
+    /**
+     * Resolve the node identity from the current context, throwing if absent.
+     * @returns The owning node identity.
+     * @internal
+     */
+    async resolveNodeIdentity() {
+        const contextIds = await ContextIdStore.getContextIds();
+        const nodeId = contextIds?.[ContextIdKeys.Node];
+        if (!Is.stringValue(nodeId)) {
+            throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "datasetNodeContextRequired");
+        }
+        return nodeId;
+    }
 }
 //# sourceMappingURL=dataspaceControlPlaneService.js.map