@twin.org/rights-management-models 0.0.2-next.1 → 0.0.2-next.10

package/dist/cjs/index.cjs

@@ -1,5 +1,26 @@
 'use strict';
 
+var core = require('@twin.org/core');
+var identityModels = require('@twin.org/identity-models');
+var standardsW3cDid = require('@twin.org/standards-w3c-did');
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The type of decision from a Policy Decision Point (PDP).
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const PolicyDecision = {
+    /**
+     * Granted.
+     */
+    Granted: "Granted",
+    /**
+     * Denied.
+     */
+    Denied: "Denied"
+};
+
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
@@ -17,4 +38,369 @@ const PolicyDecisionStage = {
     After: "after"
 };
 
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The mode that can be used to retrieve information from PIP sources.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const PolicyInformationAccessMode = {
+    /**
+     * Public.
+     */
+    Public: "public",
+    /**
+     * Private.
+     */
+    Private: "private",
+    /**
+     * Any.
+     */
+    Any: "any"
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The LD Contexts concerning Rights Management.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const RightsManagementContexts = {
+    /**
+     * The Rights Management LD Context.
+     */
+    ContextRoot: "https://schema.twindev.org/rights-management"
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The namespaces for rights management.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const RightsManagementNamespaces = {
+    /**
+     * Policy.
+     */
+    Policy: "policy",
+    /**
+     * Contract Negotiation.
+     */
+    ContractNegotiation: "contract-negotiation"
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The types of Rights Management data.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const RightsManagementTypes = {
+    /**
+     * Represents policy request.
+     */
+    PolicyRequest: "PolicyRequest",
+    /**
+     * Represents data access request.
+     */
+    DataAccessRequest: "DataAccessRequest",
+    /**
+     * Represents data access request with object.
+     */
+    DataAccessRequestWithObject: "DataAccessRequestWithObject",
+    /**
+     * Represents data access request query.
+     */
+    DataAccessQuery: "DataAccessQuery",
+    /**
+     * Represents data access request query response.
+     */
+    DataAccessQueryResponse: "DataAccessQueryResponse"
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Helper methods for Locator.
+ */
+class LocatorHelper {
+    /**
+     * Converts to a readable string.
+     * @param locator The policy locator.
+     * @returns The details of the locator as a string.
+     */
+    static toString(locator) {
+        const parts = [];
+        if (core.Is.stringValue(locator.assignee)) {
+            parts.push(`Assignee: ${locator.assignee}`);
+        }
+        if (core.Is.stringValue(locator.action)) {
+            parts.push(`Action: ${locator.action}`);
+        }
+        if (core.Is.stringValue(locator.assetType)) {
+            parts.push(`Asset Type: ${locator.assetType}`);
+        }
+        if (core.Is.stringValue(locator.resourceId)) {
+            parts.push(`Resource ID: ${locator.resourceId}`);
+        }
+        return parts.join(", ");
+    }
+    /**
+     * Compares locators to see if they match.
+     * @param locator1 The first policy locator.
+     * @param locator2 The second policy locator.
+     * @returns True if the locators match, false otherwise.
+     */
+    static matches(locator1, locator2) {
+        return (
+        // The type assertions return boolean so don't want to use nullish coalescing
+        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+        (core.Is.empty(locator1.assetType) || locator1.assetType === locator2.assetType) &&
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+            (core.Is.empty(locator1.action) || locator1.action === locator2.action) &&
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+            (core.Is.empty(locator1.assignee) || locator1.assignee === locator2.assignee) &&
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+            (core.Is.empty(locator1.resourceId) || locator1.resourceId === locator2.resourceId));
+    }
+    /**
+     * Finds a matching locator from a list of locators.
+     * @param locators The list of policy locators.
+     * @param targetLocator The target policy locator to find.
+     * @returns The matching locator if found, undefined otherwise.
+     */
+    static findMatchingLocator(locators, targetLocator) {
+        if (!core.Is.arrayValue(locators)) {
+            return undefined;
+        }
+        return locators.find(locator => this.matches(locator, targetLocator));
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Helper methods for Odrl Policies.
+ */
+class OdrlPolicyHelper {
+    /**
+     * Find the expiration date of the policy.
+     * @param policy The policy to check.
+     * @param assetType The type of the asset, if undefined will match any asset type.
+     * @param action The action to check, if undefined will match any action.
+     * @returns The expiration date of the policy, or undefined if not found.
+     */
+    static findExpirationDate(policy, assetType, action) {
+        if (core.Is.arrayValue(policy.permission)) {
+            for (const permission of policy.permission) {
+                const matchesPermission = OdrlPolicyHelper.matchTargetAndAction(permission.target, permission.action, {
+                    assetType,
+                    action
+                });
+                if (matchesPermission && core.Is.arrayValue(permission.constraint)) {
+                    for (const constraint of permission.constraint) {
+                        if (constraint.leftOperand === "dateTime" &&
+                            constraint.operator === "lteq" &&
+                            core.Is.dateTimeString(constraint.rightOperand)) {
+                            return constraint.rightOperand;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Match the target to the requested asset type.
+     * @param target The target to match.
+     * @param matchAssetType The asset type to match.
+     * @param matchResourceId The resource id to match.
+     * @returns True if the target is empty, the target matches the requested asset, false otherwise.
+     */
+    static matchAsset(target, matchAssetType, matchResourceId) {
+        if (core.Is.empty(target) || core.Is.empty(matchAssetType)) {
+            return true;
+        }
+        if (core.Is.arrayValue(target)) {
+            return target.some(t => OdrlPolicyHelper.matchAsset(t, matchAssetType));
+        }
+        if (core.Is.stringValue(target)) {
+            return target === matchAssetType;
+        }
+        // TODO: This currently only handles the simple case of matching a single asset type.
+        // we need further processing if the target is more complex.
+        // we also need to support the resource id matching.
+        return false;
+    }
+    /**
+     * Match the action to the asset type.
+     * @param action The action to match.
+     * @param matchAction The action to match.
+     * @returns True if the action is empty, the action matches the asset type, false otherwise.
+     */
+    static matchAction(action, matchAction) {
+        if (core.Is.empty(action) || core.Is.empty(matchAction)) {
+            return true;
+        }
+        if (core.Is.arrayValue(action)) {
+            return action.some(a => OdrlPolicyHelper.matchAction(a, matchAction));
+        }
+        if (core.Is.stringValue(action)) {
+            return action === matchAction;
+        }
+        // TODO: This currently only handles the simple case of matching a single action type.
+        // we need further processing if the action is more complex.
+        return false;
+    }
+    /**
+     * Match the assignee.
+     * @param assignee The assignee to match.
+     * @param matchAssignee The assignee to match.
+     * @returns True if the assignee is empty, the assignee matches the asset type, false otherwise.
+     */
+    static matchAssignee(assignee, matchAssignee) {
+        if (core.Is.empty(assignee) || core.Is.empty(matchAssignee)) {
+            return true;
+        }
+        if (core.Is.stringValue(assignee)) {
+            return assignee === matchAssignee;
+        }
+        // TODO: This currently only handles the simple case of matching a single assignee.
+        // we need further processing if the assignee is more complex.
+        return false;
+    }
+    /**
+     * Match the target and action to the requested asset type and action.
+     * @param target The target to match.
+     * @param action The action to match.
+     * @param locator The locator to match resource id if provided.
+     * @returns True if the target and action match the requested asset type and action, false otherwise.
+     */
+    static matchTargetAndAction(target, action, locator) {
+        const assetTypeMatch = OdrlPolicyHelper.matchAsset(target, locator?.assetType, locator?.resourceId);
+        const actionMatch = OdrlPolicyHelper.matchAction(action, locator?.action);
+        return assetTypeMatch && actionMatch;
+    }
+    /**
+     * Match the complete locator.
+     * @param assignee The assignee to match.
+     * @param target The target to match.
+     * @param action The action to match.
+     * @param locator The locator to match resource id if provided.
+     * @returns True if the complete locator matches, false otherwise.
+     */
+    static matchLocator(assignee, target, action, locator) {
+        const assetTypeMatch = OdrlPolicyHelper.matchAsset(target, locator?.assetType, locator?.resourceId);
+        const assigneeMatch = OdrlPolicyHelper.matchAssignee(assignee, locator?.assignee);
+        const actionMatch = OdrlPolicyHelper.matchAction(action, locator?.action);
+        return assetTypeMatch && assigneeMatch && actionMatch;
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Helper methods for creating and verifying rights managements requests.
+ */
+class RightsManagementTokenHelper {
+    /**
+     * The class name of the Rights Management Token Helper.
+     */
+    static CLASS_NAME = "RightsManagementTokenHelper";
+    /**
+     * Create the token for an object.
+     * @param identityConnector The identity connector to use for creating the token.
+     * @param verificationMethodId The verification method id to use for creating the token.
+     * @param item The item to create the token for.
+     * @param tokenTtlInSeconds The time-to-live (TTL) for the token in seconds.
+     * @returns The token.
+     * @throws GeneralError is the token creation fails.
+     */
+    static async createToken(identityConnector, verificationMethodId, item, tokenTtlInSeconds) {
+        core.Guards.object(RightsManagementTokenHelper.CLASS_NAME, "identityConnector", identityConnector);
+        core.Guards.stringValue(RightsManagementTokenHelper.CLASS_NAME, "verificationMethodId", verificationMethodId);
+        core.Guards.integer(RightsManagementTokenHelper.CLASS_NAME, "tokenTtlInSeconds", tokenTtlInSeconds);
+        const ttlMs = tokenTtlInSeconds * 1000;
+        const parts = identityModels.DocumentHelper.parseId(verificationMethodId);
+        const credential = await identityConnector.createVerifiableCredential(parts.id, verificationMethodId, undefined, item, {
+            expirationDate: new Date(Date.now() + ttlMs)
+        });
+        return credential.jwt;
+    }
+    /**
+     * Verify the token.
+     * @param identityConnector The identity connector to use for verifying the token.
+     * @param checkProperties Properties to compare against the subject to see if they match.
+     * @param token The token containing the necessary information.
+     * @param tokenTtlInSeconds The time-to-live (TTL) for the token in seconds.
+     * @returns The verifiable credential if the token is valid.
+     * @throws GeneralError is the token verification fails.
+     */
+    static async verifyToken(identityConnector, checkProperties, token, tokenTtlInSeconds) {
+        core.Guards.object(RightsManagementTokenHelper.CLASS_NAME, "identityConnector", identityConnector);
+        core.Guards.stringValue(RightsManagementTokenHelper.CLASS_NAME, "token", token);
+        try {
+            const result = await identityConnector.checkVerifiableCredential(token);
+            const verifiableCredential = result.verifiableCredential;
+            if (core.Is.empty(verifiableCredential)) {
+                throw new core.GeneralError(RightsManagementTokenHelper.CLASS_NAME, "tokenNoCredential");
+            }
+            const issuer = core.Is.stringValue(verifiableCredential.issuer)
+                ? verifiableCredential.issuer
+                : undefined;
+            if (core.Is.empty(issuer)) {
+                throw new core.GeneralError(RightsManagementTokenHelper.CLASS_NAME, "tokenNoIssuer");
+            }
+            for (const checkProperty of Object.keys(checkProperties)) {
+                if (core.ObjectHelper.propertyGet(checkProperties, checkProperty) !==
+                    core.ObjectHelper.propertyGet(verifiableCredential.credentialSubject, checkProperty)) {
+                    throw new core.GeneralError(RightsManagementTokenHelper.CLASS_NAME, "tokenItemMismatch", {
+                        property: checkProperty
+                    });
+                }
+            }
+            await RightsManagementTokenHelper.verifyIssuanceDate(standardsW3cDid.VerifiableCredentialHelper.getValidFrom(verifiableCredential), issuer, tokenTtlInSeconds);
+            return {
+                ...verifiableCredential,
+                issuer
+            };
+        }
+        catch (err) {
+            throw new core.GeneralError(RightsManagementTokenHelper.CLASS_NAME, "tokenFailed", undefined, err);
+        }
+    }
+    /**
+     * Verify that the token has an issuance date and that it is within the allowed time-to-live (TTL).
+     * @param issuanceDate The issuance date from the token.
+     * @param assignee The identity of the node performing the action.
+     * @param tokenTtlInSeconds The time-to-live (TTL) for the token in seconds.
+     * @throws GeneralError if the token is missing the issuance date or if it has expired.
+     */
+    static async verifyIssuanceDate(issuanceDate, assignee, tokenTtlInSeconds) {
+        core.Guards.stringValue(RightsManagementTokenHelper.CLASS_NAME, "assignee", assignee);
+        core.Guards.number(RightsManagementTokenHelper.CLASS_NAME, "tokenTtlInSeconds", tokenTtlInSeconds);
+        if (core.Is.empty(issuanceDate)) {
+            throw new core.GeneralError(RightsManagementTokenHelper.CLASS_NAME, "tokenMissingIssuanceDate", {
+                assignee
+            });
+        }
+        const tokenCreated = new Date(issuanceDate);
+        const now = Date.now();
+        const tokenTtlInMs = tokenTtlInSeconds * 1000;
+        // If the token has expired then we should reject it
+        if (tokenCreated.getTime() + tokenTtlInMs < now) {
+            throw new core.GeneralError(RightsManagementTokenHelper.CLASS_NAME, "tokenExpired", {
+                assignee
+            });
+        }
+    }
+}
+
+exports.LocatorHelper = LocatorHelper;
+exports.OdrlPolicyHelper = OdrlPolicyHelper;
+exports.PolicyDecision = PolicyDecision;
 exports.PolicyDecisionStage = PolicyDecisionStage;
+exports.PolicyInformationAccessMode = PolicyInformationAccessMode;
+exports.RightsManagementContexts = RightsManagementContexts;
+exports.RightsManagementNamespaces = RightsManagementNamespaces;
+exports.RightsManagementTokenHelper = RightsManagementTokenHelper;
+exports.RightsManagementTypes = RightsManagementTypes;