@twin.org/rights-management-service 0.0.1-next.3

package/dist/esm/index.mjs

@@ -0,0 +1,420 @@
+import { HttpParameterHelper } from '@twin.org/api-models';
+import { Guards, ComponentFactory, Coerce, GeneralError, Is } from '@twin.org/core';
+import { HttpStatusCode, HeaderTypes } from '@twin.org/web';
+import { PolicyAdministrationPointComponentEntityStorage } from '@twin.org/rights-management-pap-entity-storage';
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The source used when communicating about these routes.
+ */
+const ROUTES_SOURCE = "rightsManagementRoutes";
+/**
+ * The tag to associate with the routes.
+ */
+const tags = [
+    {
+        name: "Policy Administration Point",
+        description: "Endpoints for managing ODRL policies in the Policy Administration Point"
+    }
+];
+/**
+ * The REST routes for the Rights Management.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+function generateRestRoutes(baseRouteName, componentName) {
+    const storeRoute = {
+        operationId: "papStore",
+        summary: "Store a policy",
+        tag: tags[0].name,
+        method: "POST",
+        path: `${baseRouteName}/pap/`,
+        handler: async (httpRequestContext, request) => papStore(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IPapStoreRequest",
+            examples: [
+                {
+                    id: "papStoreExample",
+                    request: {
+                        body: {
+                            policy: {
+                                "@context": "https://www.w3.org/ns/odrl.jsonld",
+                                "@type": "Set",
+                                uid: "http://example.com/policy/1",
+                                permission: [
+                                    {
+                                        target: "http://example.com/asset/1",
+                                        action: "use"
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "ICreatedResponse",
+                examples: [
+                    {
+                        id: "papStoreResponseExample",
+                        response: {
+                            statusCode: HttpStatusCode.created,
+                            headers: {
+                                [HeaderTypes.Location]: "http://example.com/policy/1"
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    const retrieveRoute = {
+        operationId: "papRetrieve",
+        summary: "Retrieve a policy",
+        tag: tags[0].name,
+        method: "GET",
+        path: `${baseRouteName}/pap/:id`,
+        handler: async (httpRequestContext, request) => papRetrieve(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IPapRetrieveRequest",
+            examples: [
+                {
+                    id: "papRetrieveExample",
+                    request: {
+                        pathParams: {
+                            id: "http://example.com/policy/1"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IPapRetrieveResponse",
+                examples: [
+                    {
+                        id: "papRetrieveResponseExample",
+                        response: {
+                            body: {
+                                "@context": "https://www.w3.org/ns/odrl.jsonld",
+                                "@type": "Set",
+                                uid: "http://example.com/policy/1",
+                                permission: [
+                                    {
+                                        target: "http://example.com/asset/1",
+                                        action: "use"
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    const removeRoute = {
+        operationId: "papRemove",
+        summary: "Remove a policy",
+        tag: tags[0].name,
+        method: "DELETE",
+        path: `${baseRouteName}/pap/:id`,
+        handler: async (httpRequestContext, request) => papRemove(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IPapRemoveRequest",
+            examples: [
+                {
+                    id: "papRemoveExample",
+                    request: {
+                        pathParams: {
+                            id: "http://example.com/policy/1"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ]
+    };
+    const queryRoute = {
+        operationId: "papQuery",
+        summary: "Query policies",
+        tag: tags[0].name,
+        method: "POST",
+        path: `${baseRouteName}/pap/query`,
+        handler: async (httpRequestContext, request) => papQuery(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IPapQueryRequest",
+            examples: [
+                {
+                    id: "papQueryExample",
+                    request: {
+                        query: {
+                            cursor: "optional-pagination-cursor"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IPapQueryResponse",
+                examples: [
+                    {
+                        id: "papQueryResponseExample",
+                        response: {
+                            body: {
+                                cursor: "next-page-cursor",
+                                policies: [
+                                    {
+                                        "@context": "https://www.w3.org/ns/odrl.jsonld",
+                                        "@type": "Set",
+                                        uid: "http://example.com/policy/1",
+                                        permission: [
+                                            {
+                                                target: "http://example.com/asset/1",
+                                                action: "use"
+                                            }
+                                        ]
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    return [storeRoute, retrieveRoute, removeRoute, queryRoute];
+}
+/**
+ * PAP: Store a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function papStore(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.body", request.body);
+    Guards.object(ROUTES_SOURCE, "request.body.policy", request.body.policy);
+    Guards.stringValue(ROUTES_SOURCE, "httpRequestContext.nodeIdentity", httpRequestContext.nodeIdentity);
+    const component = ComponentFactory.get(componentName);
+    const policy = request.body.policy;
+    await component.papStore(policy, httpRequestContext.userIdentity, httpRequestContext.nodeIdentity);
+    return {
+        statusCode: HttpStatusCode.created,
+        headers: {
+            [HeaderTypes.Location]: policy.uid ?? ""
+        }
+    };
+}
+/**
+ * PAP: Retrieve a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function papRetrieve(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
+    Guards.stringValue(ROUTES_SOURCE, "httpRequestContext.nodeIdentity", httpRequestContext.nodeIdentity);
+    const component = ComponentFactory.get(componentName);
+    const policy = await component.papRetrieve(request.pathParams.id, httpRequestContext.userIdentity, httpRequestContext.nodeIdentity);
+    return {
+        body: policy
+    };
+}
+/**
+ * PAP: Remove a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function papRemove(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
+    Guards.stringValue(ROUTES_SOURCE, "httpRequestContext.nodeIdentity", httpRequestContext.nodeIdentity);
+    const component = ComponentFactory.get(componentName);
+    await component.papRemove(request.pathParams.id, httpRequestContext.userIdentity, httpRequestContext.nodeIdentity);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * PAP: Query policies.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function papQuery(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.stringValue(ROUTES_SOURCE, "httpRequestContext.nodeIdentity", httpRequestContext.nodeIdentity);
+    const queryParams = request.query || {};
+    const cursor = queryParams.cursor;
+    const pageSize = Coerce.number(queryParams.pageSize);
+    const component = ComponentFactory.get(componentName);
+    const result = await component.papQuery(HttpParameterHelper.objectFromString(request.query?.conditions), cursor, pageSize, httpRequestContext.userIdentity, httpRequestContext.nodeIdentity);
+    return {
+        body: {
+            cursor: result.cursor,
+            policies: result.policies
+        }
+    };
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Service for performing Rights Management operations.
+ * This is a unified service that provides access to all Rights Management components.
+ */
+class RightsManagementService {
+    /**
+     * The namespace supported by the Rights Management service.
+     */
+    static NAMESPACE = "rights-management";
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "RightsManagementService";
+    /**
+     * The PAP component implementation.
+     * @internal
+     */
+    _papComponent;
+    /**
+     * Create a new instance of RightsManagementService.
+     * @param options The options for the service.
+     */
+    constructor(options) {
+        // Initialize PAP component
+        const papNamespace = options?.config?.papNamespace ?? PolicyAdministrationPointComponentEntityStorage.NAMESPACE;
+        // Get the component from the factory
+        this._papComponent = ComponentFactory.get(papNamespace);
+    }
+    /**
+     * PAP: Store a policy.
+     * @param policy The policy to store.
+     * @param userIdentity The identity of the user performing the operation.
+     * @param nodeIdentity The identity of the node the operation is performed on.
+     * @returns Nothing.
+     */
+    async papStore(policy, userIdentity, nodeIdentity) {
+        try {
+            Guards.object(this.CLASS_NAME, "policy", policy);
+            Guards.stringValue(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
+            if (userIdentity !== undefined) {
+                Guards.stringValue(this.CLASS_NAME, "userIdentity", userIdentity);
+            }
+            await this._papComponent.store(policy, userIdentity, nodeIdentity);
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "papStoreFailed", undefined, error);
+        }
+    }
+    /**
+     * PAP: Retrieve a policy.
+     * @param policyId The id of the policy to retrieve.
+     * @param userIdentity The identity of the user performing the operation.
+     * @param nodeIdentity The identity of the node the operation is performed on.
+     * @returns The policy.
+     */
+    async papRetrieve(policyId, userIdentity, nodeIdentity) {
+        try {
+            Guards.stringValue(this.CLASS_NAME, "policyId", policyId);
+            Guards.stringValue(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
+            if (userIdentity !== undefined) {
+                Guards.stringValue(this.CLASS_NAME, "userIdentity", userIdentity);
+            }
+            const policy = await this._papComponent.retrieve(policyId, userIdentity, nodeIdentity);
+            return policy;
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "papRetrieveFailed", undefined, error);
+        }
+    }
+    /**
+     * PAP: Remove a policy.
+     * @param policyId The id of the policy to remove.
+     * @param userIdentity The identity of the user performing the operation.
+     * @param nodeIdentity The identity of the node the operation is performed on.
+     * @returns Nothing.
+     */
+    async papRemove(policyId, userIdentity, nodeIdentity) {
+        try {
+            Guards.stringValue(this.CLASS_NAME, "policyId", policyId);
+            Guards.stringValue(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
+            if (userIdentity !== undefined) {
+                Guards.stringValue(this.CLASS_NAME, "userIdentity", userIdentity);
+            }
+            await this._papComponent.remove(policyId, userIdentity, nodeIdentity);
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "papRemoveFailed", undefined, error);
+        }
+    }
+    /**
+     * PAP: Query the policies using the specified conditions.
+     * @param conditions The conditions to use for the query.
+     * @param cursor The cursor to use for pagination.
+     * @param pageSize The number of results to return per page.
+     * @param userIdentity The identity of the user performing the operation.
+     * @param nodeIdentity The identity of the node the operation is performed on.
+     * @returns Cursor for next page of results and the policies matching the query.
+     */
+    async papQuery(conditions, cursor, pageSize, userIdentity, nodeIdentity) {
+        try {
+            Guards.stringValue(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
+            if (conditions !== undefined) {
+                Guards.stringValue(this.CLASS_NAME, "conditions", conditions);
+            }
+            if (cursor !== undefined) {
+                Guards.stringValue(this.CLASS_NAME, "cursor", cursor);
+            }
+            if (pageSize !== undefined) {
+                Guards.number(this.CLASS_NAME, "pageSize", pageSize);
+            }
+            if (userIdentity !== undefined) {
+                Guards.stringValue(this.CLASS_NAME, "userIdentity", userIdentity);
+            }
+            let conditionsObj;
+            if (conditions) {
+                conditionsObj = HttpParameterHelper.objectFromString(conditions);
+                if (Is.object(conditionsObj)) {
+                    conditionsObj = conditionsObj;
+                }
+            }
+            const result = await this._papComponent.query(conditionsObj, cursor, pageSize, userIdentity, nodeIdentity);
+            return result;
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "papQueryFailed", undefined, error);
+        }
+    }
+}
+
+/**
+ * Entry points for the REST API.
+ */
+const restEntryPoints = [
+    {
+        name: "rights-management",
+        defaultBaseRoute: "rights-management",
+        tags,
+        generateRoutes: generateRestRoutes
+    }
+];
+
+export { RightsManagementService, generateRestRoutes, papQuery, papRemove, papRetrieve, papStore, restEntryPoints, tags };

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./models/IRightsManagementServiceConfig";
+export * from "./models/IRightsManagementServiceConstructorOptions";
+export * from "./rightsManagementRoutes";
+export * from "./rightsManagementService";
+export * from "./restEntryPoints";

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

@@ -0,0 +1,25 @@
+/**
+ * The configuration for the RightsManagementService.
+ */
+export interface IRightsManagementServiceConfig {
+    /**
+     * The namespace for the PAP component.
+     */
+    papNamespace?: string;
+    /**
+     * The default entity storage type.
+     */
+    defaultEntityStorageType?: string;
+    /**
+     * Should the user identity be included in entity storage operations.
+     */
+    includeUserIdentity?: boolean;
+    /**
+     * Should the node identity be included in entity storage operations.
+     */
+    includeNodeIdentity?: boolean;
+    /**
+     * The maximum number of results to return in a query.
+     */
+    maxQueryResults?: number;
+}

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

@@ -0,0 +1,10 @@
+import type { IRightsManagementServiceConfig } from "./IRightsManagementServiceConfig";
+/**
+ * The constructor options for the RightsManagementService.
+ */
+export interface IRightsManagementServiceConstructorOptions {
+    /**
+     * The configuration for the service.
+     */
+    config?: IRightsManagementServiceConfig;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,5 @@
+import type { IRestRouteEntryPoint } from "@twin.org/api-models";
+/**
+ * Entry points for the REST API.
+ */
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/dist/types/rightsManagementRoutes.d.ts

@@ -0,0 +1,45 @@
+import { type ICreatedResponse, type IHttpRequestContext, type INoContentResponse, type IRestRoute, type ITag } from "@twin.org/api-models";
+import type { IPapQueryRequest, IPapQueryResponse, IPapRemoveRequest, IPapRetrieveRequest, IPapRetrieveResponse, IPapStoreRequest } from "@twin.org/rights-management-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tags: ITag[];
+/**
+ * The REST routes for the Rights Management.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutes(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * PAP: Store a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function papStore(httpRequestContext: IHttpRequestContext, componentName: string, request: IPapStoreRequest): Promise<ICreatedResponse>;
+/**
+ * PAP: Retrieve a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function papRetrieve(httpRequestContext: IHttpRequestContext, componentName: string, request: IPapRetrieveRequest): Promise<IPapRetrieveResponse>;
+/**
+ * PAP: Remove a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function papRemove(httpRequestContext: IHttpRequestContext, componentName: string, request: IPapRemoveRequest): Promise<INoContentResponse>;
+/**
+ * PAP: Query policies.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function papQuery(httpRequestContext: IHttpRequestContext, componentName: string, request: IPapQueryRequest): Promise<IPapQueryResponse>;

package/dist/types/rightsManagementService.d.ts

@@ -0,0 +1,60 @@
+import type { EntityCondition } from "@twin.org/entity";
+import type { IRightsManagementComponent } from "@twin.org/rights-management-models";
+import type { IOdrlPolicy } from "@twin.org/standards-w3c-odrl";
+import type { IRightsManagementServiceConstructorOptions } from "./models/IRightsManagementServiceConstructorOptions";
+/**
+ * Service for performing Rights Management operations.
+ * This is a unified service that provides access to all Rights Management components.
+ */
+export declare class RightsManagementService implements IRightsManagementComponent {
+    /**
+     * The namespace supported by the Rights Management service.
+     */
+    static readonly NAMESPACE: string;
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of RightsManagementService.
+     * @param options The options for the service.
+     */
+    constructor(options?: IRightsManagementServiceConstructorOptions);
+    /**
+     * PAP: Store a policy.
+     * @param policy The policy to store.
+     * @param userIdentity The identity of the user performing the operation.
+     * @param nodeIdentity The identity of the node the operation is performed on.
+     * @returns Nothing.
+     */
+    papStore(policy: IOdrlPolicy, userIdentity: string | undefined, nodeIdentity: string): Promise<void>;
+    /**
+     * PAP: Retrieve a policy.
+     * @param policyId The id of the policy to retrieve.
+     * @param userIdentity The identity of the user performing the operation.
+     * @param nodeIdentity The identity of the node the operation is performed on.
+     * @returns The policy.
+     */
+    papRetrieve(policyId: string, userIdentity: string | undefined, nodeIdentity: string): Promise<IOdrlPolicy>;
+    /**
+     * PAP: Remove a policy.
+     * @param policyId The id of the policy to remove.
+     * @param userIdentity The identity of the user performing the operation.
+     * @param nodeIdentity The identity of the node the operation is performed on.
+     * @returns Nothing.
+     */
+    papRemove(policyId: string, userIdentity: string | undefined, nodeIdentity: string): Promise<void>;
+    /**
+     * PAP: Query the policies using the specified conditions.
+     * @param conditions The conditions to use for the query.
+     * @param cursor The cursor to use for pagination.
+     * @param pageSize The number of results to return per page.
+     * @param userIdentity The identity of the user performing the operation.
+     * @param nodeIdentity The identity of the node the operation is performed on.
+     * @returns Cursor for next page of results and the policies matching the query.
+     */
+    papQuery(conditions?: EntityCondition<IOdrlPolicy>, cursor?: string, pageSize?: number, userIdentity?: string, nodeIdentity?: string): Promise<{
+        cursor?: string;
+        policies: IOdrlPolicy[];
+    }>;
+}

package/docs/changelog.md

@@ -0,0 +1,20 @@
+# @twin.org/rights-management-pap-service - Changelog
+
+## [0.0.1-next.3](https://github.com/twinfoundation/rights-management/compare/rights-management-service-v0.0.1-next.2...rights-management-service-v0.0.1-next.3) (2025-05-28)
+
+
+### Features
+
+* rights management pap ([#4](https://github.com/twinfoundation/rights-management/issues/4)) ([d1165a9](https://github.com/twinfoundation/rights-management/commit/d1165a92f57128731cfb308d977832e28cf33493))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/rights-management-models bumped from 0.0.1-next.2 to 0.0.1-next.3
+    * @twin.org/rights-management-pap-entity-storage bumped from 0.0.1-next.2 to 0.0.1-next.3
+
+## 0.0.1-next.1
+
+- Initial release.

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/rights-management-pap-service - Examples