@twin.org/rights-management-plugins 0.0.3-next.9 → 0.9.0

package/docs/examples.md

@@ -1 +1,295 @@
-# @twin.org/rights-management-plugins - Examples
+# Rights Management Plugins Examples
+
+These examples show how to wire default and pass-through plugins so negotiation, information retrieval, enforcement, and execution behaviours stay predictable.
+
+## PassThroughPolicyRequester
+
+```typescript
+import { PassThroughPolicyRequester } from '@twin.org/rights-management-plugins';
+import { PolicyType } from '@twin.org/standards-w3c-odrl';
+
+const requester = new PassThroughPolicyRequester();
+
+const offerAccepted = await requester.offer('neg-1', {
+  '@id': 'urn:rights-management:offer-1',
+  '@type': PolicyType.Offer,
+  assigner: 'did:example:provider'
+});
+
+const agreementAccepted = await requester.agreement('neg-1', {
+  '@id': 'urn:rights-management:agreement-1',
+  '@type': PolicyType.Agreement,
+  assigner: 'did:example:provider',
+  assignee: 'did:example:consumer'
+});
+
+await requester.finalised('neg-1');
+await requester.terminated('neg-1');
+
+console.log(requester.className()); // PassThroughPolicyRequester
+console.log(offerAccepted); // true
+console.log(agreementAccepted); // true
+```
+
+## PassThroughPolicyNegotiator
+
+```typescript
+import { PassThroughPolicyNegotiator } from '@twin.org/rights-management-plugins';
+import { PolicyType } from '@twin.org/standards-w3c-odrl';
+
+const negotiator = new PassThroughPolicyNegotiator();
+
+const offer = {
+  '@id': 'urn:rights-management:offer-1',
+  '@type': PolicyType.Offer,
+  assigner: 'did:example:provider'
+};
+
+const supported = negotiator.supportsOffer(offer);
+const handled = await negotiator.handleOffer(offer, {
+  'did:example:consumer': {
+    '@id': 'did:example:consumer'
+  }
+});
+const agreement = await negotiator.createAgreement(offer, 'did:example:consumer', {
+  'did:example:consumer': {
+    '@id': 'did:example:consumer'
+  }
+});
+
+console.log(negotiator.className()); // PassThroughPolicyNegotiator
+console.log(supported); // true
+console.log(handled.accepted); // true
+console.log(agreement?.['@type']); // Agreement
+```
+
+## LoggingPolicyExecutionAction
+
+```typescript
+import { LoggingPolicyExecutionAction } from '@twin.org/rights-management-plugins';
+import { PolicyDecision, PolicyDecisionStage } from '@twin.org/rights-management-models';
+import { PolicyType } from '@twin.org/standards-w3c-odrl';
+
+const action = new LoggingPolicyExecutionAction({
+  config: {
+    stages: [PolicyDecisionStage.Before, PolicyDecisionStage.After],
+    includeData: true,
+    includePolicy: false,
+    includeDecisions: true
+  }
+});
+
+await action.execute(
+  {
+    '@id': 'urn:rights-management:agreement-1',
+    '@type': PolicyType.Agreement,
+    assigner: 'did:example:provider',
+    assignee: 'did:example:consumer'
+  },
+  [{ target: '$.asset', decision: PolicyDecision.Granted }],
+  { asset: 'dataset-1' },
+  'use',
+  PolicyDecisionStage.Before
+);
+
+console.log(action.className()); // LoggingPolicyExecutionAction
+console.log(action.supportedStages()); // [ 'before', 'after' ]
+```
+
+## StaticPolicyInformationSource
+
+```typescript
+import { PolicyInformationAccessMode } from '@twin.org/rights-management-models';
+import { StaticPolicyInformationSource } from '@twin.org/rights-management-plugins';
+
+const source = new StaticPolicyInformationSource({
+  config: {
+    information: [
+      {
+        accessMode: PolicyInformationAccessMode.Any,
+        objects: {
+          'did:example:consumer': {
+            '@id': 'did:example:consumer'
+          }
+        }
+      }
+    ]
+  }
+});
+
+source.addInformation({
+  accessMode: PolicyInformationAccessMode.Public,
+  objects: {
+    'urn:asset:dataset-1': {
+      '@id': 'urn:asset:dataset-1'
+    }
+  },
+  matchLocators: [
+    {
+      target: 'urn:asset:dataset-1'
+    }
+  ]
+});
+
+const result = await source.retrieve(
+  {
+    '@id': 'urn:rights-management:agreement-1',
+    '@type': 'Agreement',
+    target: 'urn:asset:dataset-1'
+  },
+  PolicyInformationAccessMode.Public,
+  { requestId: 'request-1' },
+  'use'
+);
+
+console.log(source.className()); // StaticPolicyInformationSource
+console.log(Object.keys(result ?? {}).length); // 2
+```
+
+## DefaultPolicyArbiter
+
+```typescript
+import { DefaultPolicyArbiter } from '@twin.org/rights-management-plugins';
+import { PolicyType } from '@twin.org/standards-w3c-odrl';
+
+const arbiter = new DefaultPolicyArbiter();
+
+const decisions = await arbiter.decide(
+  {
+    '@id': 'urn:rights-management:agreement-1',
+    '@type': PolicyType.Agreement,
+    assigner: 'did:example:provider',
+    assignee: 'did:example:consumer',
+    permission: [
+      {
+        target: 'urn:asset:dataset-1',
+        action: 'use'
+      }
+    ]
+  },
+  {},
+  { asset: 'dataset-1' },
+  'use'
+);
+
+console.log(arbiter.className()); // DefaultPolicyArbiter
+console.log(decisions[0].decision); // granted
+```
+
+## PassThroughPolicyArbiter
+
+```typescript
+import { PassThroughPolicyArbiter } from '@twin.org/rights-management-plugins';
+import { PolicyType } from '@twin.org/standards-w3c-odrl';
+
+const arbiter = new PassThroughPolicyArbiter();
+
+const decisions = await arbiter.decide(
+  {
+    '@id': 'urn:rights-management:agreement-2',
+    '@type': PolicyType.Agreement,
+    assigner: 'did:example:provider',
+    assignee: 'did:example:consumer'
+  },
+  {},
+  { asset: 'dataset-2' },
+  'read'
+);
+
+console.log(arbiter.className()); // PassThroughPolicyArbiter
+console.log(decisions[0].decision); // granted
+```
+
+## DefaultPolicyEnforcementProcessor
+
+```typescript
+import { PolicyDecision } from '@twin.org/rights-management-models';
+import { DefaultPolicyEnforcementProcessor } from '@twin.org/rights-management-plugins';
+import { PolicyType } from '@twin.org/standards-w3c-odrl';
+
+const processor = new DefaultPolicyEnforcementProcessor();
+
+const processed = await processor.process(
+  {
+    '@id': 'urn:rights-management:agreement-1',
+    '@type': PolicyType.Agreement
+  },
+  [{ target: '$.asset', decision: PolicyDecision.Granted }],
+  { asset: 'dataset-1', hidden: 'no' },
+  'use'
+);
+
+console.log(processor.className()); // DefaultPolicyEnforcementProcessor
+console.log(processed); // { asset: 'dataset-1' }
+```
+
+## PassThroughPolicyEnforcementProcessor
+
+```typescript
+import { PassThroughPolicyEnforcementProcessor } from '@twin.org/rights-management-plugins';
+import { PolicyType } from '@twin.org/standards-w3c-odrl';
+
+const processor = new PassThroughPolicyEnforcementProcessor();
+
+const result = await processor.process(
+  {
+    '@id': 'urn:rights-management:agreement-1',
+    '@type': PolicyType.Agreement
+  },
+  [],
+  { asset: 'dataset-1' },
+  'use'
+);
+
+console.log(processor.className()); // PassThroughPolicyEnforcementProcessor
+console.log(result); // { asset: 'dataset-1' }
+```
+
+## IdentityPolicyInformationSource
+
+```typescript
+import { PolicyInformationAccessMode } from '@twin.org/rights-management-models';
+import { IdentityPolicyInformationSource } from '@twin.org/rights-management-plugins';
+
+const source = new IdentityPolicyInformationSource();
+
+const info = await source.retrieve(
+  {
+    '@id': 'urn:rights-management:agreement-1',
+    '@type': 'Agreement',
+    assigner: 'did:example:provider',
+    assignee: 'did:example:consumer'
+  },
+  PolicyInformationAccessMode.Any,
+  { requestId: 'request-2' },
+  'use'
+);
+
+console.log(source.className()); // IdentityPolicyInformationSource
+console.log(Object.keys(info ?? {}).length); // 2
+```
+
+## PassThroughPolicyObligationEnforcer
+
+```typescript
+import { PassThroughPolicyObligationEnforcer } from '@twin.org/rights-management-plugins';
+import { PolicyType } from '@twin.org/standards-w3c-odrl';
+
+const enforcer = new PassThroughPolicyObligationEnforcer();
+
+const enforced = await enforcer.enforce(
+  {
+    '@id': 'urn:rights-management:agreement-1',
+    '@type': PolicyType.Agreement
+  },
+  {
+    action: 'use'
+  },
+  {},
+  { requestId: 'request-3' },
+  'use'
+);
+
+console.log(enforcer.className()); // PassThroughPolicyObligationEnforcer
+console.log(enforced); // true
+```

package/docs/reference/classes/AutomationPolicyExecutionAction.md

@@ -0,0 +1,143 @@
+# Class: AutomationPolicyExecutionAction
+
+Automation Policy Execution Action to execute automation policies.
+
+## Implements
+
+- `IPolicyExecutionAction`
+
+## Constructors
+
+### Constructor
+
+> **new AutomationPolicyExecutionAction**(`options?`): `AutomationPolicyExecutionAction`
+
+Create a new instance of AutomationPolicyExecutionAction.
+
+#### Parameters
+
+##### options?
+
+[`IAutomationPolicyExecutionActionConstructorOptions`](../interfaces/IAutomationPolicyExecutionActionConstructorOptions.md)
+
+The options for the automation policy execution action.
+
+#### Returns
+
+`AutomationPolicyExecutionAction`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+The class name of the Automation Policy Execution Action.
+
+***
+
+### BEFORE\_TRIGGER\_NAME {#before_trigger_name}
+
+> `readonly` `static` **BEFORE\_TRIGGER\_NAME**: `string` = `"rights-management:pxp:before"`
+
+The before automation trigger name.
+
+***
+
+### AFTER\_TRIGGER\_NAME {#after_trigger_name}
+
+> `readonly` `static` **AFTER\_TRIGGER\_NAME**: `string` = `"rights-management:pxp:after"`
+
+The after automation trigger name.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IPolicyExecutionAction.className`
+
+***
+
+### supportedStages() {#supportedstages}
+
+> **supportedStages**(): `PolicyDecisionStage`[]
+
+Which stages should the action be executed at.
+
+#### Returns
+
+`PolicyDecisionStage`[]
+
+List of stages.
+
+#### Implementation of
+
+`IPolicyExecutionAction.supportedStages`
+
+***
+
+### execute() {#execute}
+
+> **execute**\<`D`\>(`policy`, `decisions`, `data`, `action`, `stage`): `Promise`\<`void`\>
+
+Execute function type for policy actions.
+
+#### Type Parameters
+
+##### D
+
+`D` = `unknown`
+
+#### Parameters
+
+##### policy
+
+`IRightsManagementPolicy`
+
+The policy that applied to the data.
+
+##### decisions
+
+`IPolicyDecision`[]
+
+The decisions made by the PDP.
+
+##### data
+
+`D` \| `undefined`
+
+The data to process.
+
+##### action
+
+`string` \| `undefined`
+
+Optional action to make a decision on, if not provided, the arbiter will evaluate all actions in the agreement.
+
+##### stage
+
+`PolicyDecisionStage`
+
+The stage of the policy decision.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the action is complete.
+
+#### Implementation of
+
+`IPolicyExecutionAction.execute`

package/docs/reference/classes/DefaultPolicyArbiter.md

@@ -0,0 +1,113 @@
+# Class: DefaultPolicyArbiter
+
+Default Policy Arbiter.
+
+## Implements
+
+- `IPolicyArbiter`
+
+## Constructors
+
+### Constructor
+
+> **new DefaultPolicyArbiter**(`options?`): `DefaultPolicyArbiter`
+
+Create a new instance of DefaultPolicyArbiter.
+
+#### Parameters
+
+##### options?
+
+[`IDefaultPolicyArbiterConstructorOptions`](../interfaces/IDefaultPolicyArbiterConstructorOptions.md)
+
+The options for the default policy arbiter.
+
+#### Returns
+
+`DefaultPolicyArbiter`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+The class name of the Default Policy Arbiter.
+
+***
+
+### SUPPORTED\_PROFILES {#supported_profiles}
+
+> `readonly` `static` **SUPPORTED\_PROFILES**: `ReadonlySet`\<`string`\>
+
+ODRL profiles whose custom vocabulary this arbiter understands and supports.
+Any policy declaring a profile not in this set will be rejected.
+Add a new entry here when support for an additional profile is implemented.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IPolicyArbiter.className`
+
+***
+
+### decide() {#decide}
+
+> **decide**\<`D`\>(`agreement`, `information?`, `data?`, `action?`): `Promise`\<`IPolicyDecision`[]\>
+
+Makes decisions regarding policy access to data.
+
+#### Type Parameters
+
+##### D
+
+`D` = `unknown`
+
+#### Parameters
+
+##### agreement
+
+`IDataspaceProtocolAgreement`
+
+The agreement to evaluate.
+
+##### information?
+
+`IRightsManagementInformation`
+
+Information provided by the requester to determine if a policy can be created.
+
+##### data?
+
+`D`
+
+The data to make a decision on.
+
+##### action?
+
+`string`
+
+Optional action to make a decision on, if not provided, the arbiter will evaluate all actions in the agreement.
+
+#### Returns
+
+`Promise`\<`IPolicyDecision`[]\>
+
+The decisions about access to the data.
+
+#### Implementation of
+
+`IPolicyArbiter.decide`

package/docs/reference/classes/DefaultPolicyEnforcementProcessor.md

@@ -0,0 +1,107 @@
+# Class: DefaultPolicyEnforcementProcessor
+
+Default Policy Enforcement Processor.
+
+## Implements
+
+- `IPolicyEnforcementProcessor`
+
+## Constructors
+
+### Constructor
+
+> **new DefaultPolicyEnforcementProcessor**(`options?`): `DefaultPolicyEnforcementProcessor`
+
+Create a new instance of DefaultPolicyEnforcementProcessor.
+
+#### Parameters
+
+##### options?
+
+[`IDefaultPolicyEnforcementProcessorConstructorOptions`](../interfaces/IDefaultPolicyEnforcementProcessorConstructorOptions.md)
+
+The options for the default policy enforcement processor.
+
+#### Returns
+
+`DefaultPolicyEnforcementProcessor`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+The class name of the Default Policy Enforcement Processor.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IPolicyEnforcementProcessor.className`
+
+***
+
+### process() {#process}
+
+> **process**\<`D`, `R`\>(`agreement`, `decisions`, `data?`, `action?`): `Promise`\<`R`\>
+
+Process the response from the policy decision point.
+
+#### Type Parameters
+
+##### D
+
+`D` = `unknown`
+
+##### R
+
+`R` = `D`
+
+#### Parameters
+
+##### agreement
+
+`IDataspaceProtocolAgreement`
+
+The agreement to process.
+
+##### decisions
+
+`IPolicyDecision`[]
+
+The decisions made by the policy decision point.
+
+##### data?
+
+`D`
+
+The data to process.
+
+##### action?
+
+`string`
+
+Optional action to make a decision on, if not provided, the arbiter will evaluate all actions in the agreement.
+
+#### Returns
+
+`Promise`\<`R`\>
+
+The data after processing.
+
+#### Implementation of
+
+`IPolicyEnforcementProcessor.process`