feat: add obligations (#150)

Co-authored-by: Jp Ayyappan <108297634+jp-ayyappan@users.noreply.github.com>
Co-authored-by: Jake Van Vorhis <83739412+jakedoublev@users.noreply.github.com>

Author: 3 people

docs/components/policy/obligations.md

@@ -0,0 +1,80 @@
+# Obligations
+
+Obligations are policy constructs that enable Policy Decision Point(PDP) - to - Policy Enforcement Point (PEP) directives that accompany a decision. They express additional controls the PEP should enforce—such as requiring MFA, applying watermarking, encrypting content, or limiting access by time. In effect, the PDP is saying “permit, provided these controls are enforced.” The PDP cannot compel or verify enforcement; it relies on the PEP to honor the obligations. 
+If the PEP cannot or will not enforce an obligation, it should decline to grant access.
+## Composition
+
+An obligation consists of:
+
+1. A Namespace
+2. A Definition
+3. Values
+4. Triggers
+
+Platform Policy Obligations can contain multiple Namespaces, each with multiple Definitions, and each Definition can have multiple Values. Each Value can have multiple Triggers. Each trigger can have an Action, Attribute Value, and PEP identifier (optional). Not specifying a PEP results in a global obligation that applies across *all* PEPs.
+
+```mermaid
+graph LR;
+%% Every definition is namespaced.
+Namespace_A-->ObligationDefinition_A;
+
+%% Define definition and value A.
+ObligationDefinition_A-->ObligationValue_A;
+
+%% Define triggers.
+ObligationValue_A-->Trigger_A1
+Trigger_A1-->Action_A1
+Trigger_A1-->AttributeValue_A1
+Trigger_A1-->PEP_A
+
+ObligationValue_A-->Trigger_A2
+Trigger_A2-->Action_A2
+Trigger_A2-->AttributeValue_A2
+
+%% Define definition and value B.
+ObligationDefinition_A-->ObligationValue_B;
+
+%% Define triggers.
+ObligationValue_B-->Trigger_B1
+Trigger_B1-->Action_B1
+Trigger_B1-->AttributeValue_B1
+
+ObligationValue_B-->Trigger_B2
+Trigger_B2-->Action_B2
+Trigger_B2-->AttributeValue_B2
+Trigger_B2-->PEP_B
+```
+
+## Standard Obligations
+
+Standard Obligations are enforced by the Access PDP (Policy Decision Point) when validating whether an Entity of a specified Category can perform an Action on a given Resource. These obligations must be satisfied for access to be granted.
+
+A Standard Obligation includes:
+- **Action**: The specific action being performed (READ, STORE, CREATE, UPDATE, DELETE)
+- **Resource Attribute Value**: The data attribute for which this obligation is scoped
+- **Obligation Value**: The required obligation value that must be satisfied
+
+### Examples of Standard Obligations:
+
+#### Watermarking
+Ensure document traceability:
+- **Obligation**: `https://example.com/obl/drm/value/watermarking`
+- **Applied to**: sensitive documents
+- **Condition**: PEP must apply watermark
+
+#### Prevent Download
+Prevent download of plaintext content:
+- **Obligation**: `https://example.com/obl/drm/value/no-download`
+- **Applied to**: sensitive documents
+- **Condition**: PEP must not allow download
+
+## FQN (Fully Qualified Name) Convention
+
+Obligations use a specific naming convention to distinguish them from attributes:
+
+- **Obligation Definition**: `<namespace>/obl/<obligation_name>`
+- **Obligation Value**: `<namespace>/obl/<obligation_name>/value/<obligation_value>`
+
+For example:
+- `https://example.com/obl/drm` (definition)
+- `https://example.com/obl/drm/value/watermarking` (value)

specs/authorization/v2/authorization.openapi.yaml

@@ -296,6 +296,25 @@ components:
           title: resources
           maxItems: 1000
           minItems: 1
+        fulfillableObligationFqns:
+          type: array
+          items:
+            type: string
+            description: |+
+              if provided, fulfillable_obligation_fqns must be between 1 and 50 in count with all valid FQNs:
+              ```
+              this.size() == 0 || (this.size() <= 50 && this.all(item, item.isUri()))
+              ```
+
+          title: fulfillable_obligation_fqns
+          description: |+
+            obligations (fully qualified values) the requester is capable of fulfilling
+             i.e. https://<namespace>/obl/<definition name>/value/<value>
+            if provided, fulfillable_obligation_fqns must be between 1 and 50 in count with all valid FQNs:
+            ```
+            this.size() == 0 || (this.size() <= 50 && this.all(item, item.isUri()))
+            ```
+
       title: GetDecisionMultiResourceRequest
       required:
         - entityIdentifier
@@ -306,6 +325,9 @@ components:
          1. one entity reference (actor)
          2. one action
          3. multiple resources
+
+         If entitled, checks obligation policy: fulfillable obligations must satisfy all triggered.
+
          Note: this is a more performant bulk request for multiple resource decisions, up to 1000 per request
         action.name must be provided:
         ```
@@ -341,6 +363,25 @@ components:
         resource:
           title: resource
           $ref: '#/components/schemas/authorization.v2.Resource'
+        fulfillableObligationFqns:
+          type: array
+          items:
+            type: string
+            description: |+
+              if provided, fulfillable_obligation_fqns must be between 1 and 50 in count with all valid FQNs:
+              ```
+              this.size() == 0 || (this.size() <= 50 && this.all(item, item.isUri()))
+              ```
+
+          title: fulfillable_obligation_fqns
+          description: |+
+            obligations (fully qualified values) the requester is capable of fulfilling
+             i.e. https://<namespace>/obl/<definition name>/value/<value>
+            if provided, fulfillable_obligation_fqns must be between 1 and 50 in count with all valid FQNs:
+            ```
+            this.size() == 0 || (this.size() <= 50 && this.all(item, item.isUri()))
+            ```
+
       title: GetDecisionRequest
       required:
         - entityIdentifier
@@ -352,6 +393,8 @@ components:
          1. one entity reference (actor)
          2. one action
          3. one resource
+
+         If entitled, checks obligation policy: fulfillable obligations must satisfy all triggered.
         action.name must be provided:
         ```
         has(this.action.name)
@@ -362,9 +405,7 @@ components:
       properties:
         decision:
           title: decision
-          description: |-
-            decision on the resource optional list of obligations represented in URI format
-             repeated string obligations = 2;
+          description: decision on the resource
           $ref: '#/components/schemas/authorization.v2.ResourceDecision'
       title: GetDecisionResponse
       additionalProperties: false
@@ -457,6 +498,14 @@ components:
           title: decision
           description: decision result
           $ref: '#/components/schemas/authorization.v2.Decision'
+        requiredObligations:
+          type: array
+          items:
+            type: string
+          title: required_obligations
+          description: |-
+            obligations (fully qualified values) the PEP is required to fulfill on the given resource
+             i.e. https://<namespace>/obl/<definition name>/value/<value>
       title: ResourceDecision
       additionalProperties: false
     common.Metadata:

specs/policy/actions/actions.openapi.yaml

@@ -665,6 +665,81 @@ components:
           description: Keys for the namespace
       title: Namespace
       additionalProperties: false
+    policy.Obligation:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        namespace:
+          title: namespace
+          $ref: '#/components/schemas/policy.Namespace'
+        name:
+          type: string
+          title: name
+        values:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationValue'
+          title: values
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: Obligation
+      additionalProperties: false
+    policy.ObligationTrigger:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligationValue:
+          title: obligation_value
+          $ref: '#/components/schemas/policy.ObligationValue'
+        action:
+          title: action
+          $ref: '#/components/schemas/policy.Action'
+        attributeValue:
+          title: attribute_value
+          $ref: '#/components/schemas/policy.Value'
+        context:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.RequestContext'
+          title: context
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationTrigger
+      additionalProperties: false
+    policy.ObligationValue:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligation:
+          title: obligation
+          $ref: '#/components/schemas/policy.Obligation'
+        value:
+          type: string
+          title: value
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationTrigger'
+          title: triggers
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationValue
+      additionalProperties: false
     policy.PageRequest:
       type: object
       properties:
@@ -707,6 +782,15 @@ components:
           description: Total count of entire list
       title: PageResponse
       additionalProperties: false
+    policy.PolicyEnforcementPoint:
+      type: object
+      properties:
+        clientId:
+          type: string
+          title: client_id
+          minLength: 1
+      title: PolicyEnforcementPoint
+      additionalProperties: false
     policy.PublicKey:
       type: object
       oneOf:
@@ -735,6 +819,17 @@ components:
       title: PublicKey
       additionalProperties: false
       description: Deprecated
+    policy.RequestContext:
+      type: object
+      properties:
+        pep:
+          title: pep
+          $ref: '#/components/schemas/policy.PolicyEnforcementPoint'
+      title: RequestContext
+      required:
+        - pep
+      additionalProperties: false
+      description: Holds the context needed for obligation fulfillment
     policy.ResourceMapping:
       type: object
       properties:
@@ -927,6 +1022,11 @@ components:
           items:
             $ref: '#/components/schemas/policy.ResourceMapping'
           title: resource_mappings
+        obligations:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Obligation'
+          title: obligations
         metadata:
           title: metadata
           description: Common metadata