feat(core): add obligations commands

docs/man/policy/obligations/_index.md

@@ -0,0 +1,71 @@
+---
+title: Manage obligations
+command:
+  name: obligations
+---
+
+Commands to manage obligations within the platform.
+
+Obligations are requirements that should be fulfilled by a Subject or Environment requesting access to Resource data. Obligations
+are distinct from Entitlements because they are a post-entitlement decision.
+
+For example, if a Subject user is entitled through a Subject Mapping to access data that is considered confidential intellectual
+property, an obligation can be utilized to ensure the access path is through a PEP or flow that supports watermarking to enhance
+security of the data post-decryption. It is a precondition of an obligation that a Subject requesting access must already be entitled.
+
+Obligations are represented as platform attributes. They can be either added to TDFs directly, or derived via mapping.
+
+**Example:**
+
+As a platform admin, Alice already has the hierarchical attribute `https://namespace.io/attr/card_suits` with high-to-low values `ace, king, queen, jack`
+that are successfully entitled to various Subject users at each intended level of access.
+
+Alice wants to ensure data of the hierarchical attribute `https://namespace.io/attr/card_suits/value/queen`
+is accessible to Subjects that are entitled to Queen or King data, but Alice wants an additional protection of `watermarking` when
+the TDF'd data is decrypted.
+
+To add a `watermarking` assurance when a PEP handles decrypted TDF data a `digital rights management` , she can utilize obligations.
+
+**Option 1: Derived obligations**
+
+To dynamically tie all TDF data of that attribute value to this new obligation to watermark, she will create an obligation
+mapped in platform policy to the `https://namespace.io/attr/card_suits/value/queen` attribute value:
+
+`policy obligations create --name drm --value watermarking`
+
+From this point forward, any time an access request is made on a TDF containing the `/attr/card_suits/value/queen` attribute value, the obligation
+will be derived and considered in the decision.
+
+The same obligation can also be assigned multiple attribute values when derived, so `--attr` can take multiple attribute value IDs, and the
+`assign` and `remove` subcommands exist on `obligations` as well to assign attribute values to already-created obligations.
+
+**Option 2: TDF-only obligations**
+
+To add this obligation to any TDF data without permanently associating every TDF containing an attribute value to the obligation (see derived above),
+Alice can create the obligation without associating it to an attribute value:
+
+`policy obligations create --name drm --value watermarking`
+
+Without the derived assocation, the obligation can be added on TDF encrypt as any other attribute FQN. There is nothing stopping a PEP or admin from utilizing obligations in both manners in tandem as appropriate.
+
+**Evaluation: Fulfillment Conditions**
+
+In either scenario above, resolution of obligation satisfaction is similar to an `anyOf` rule on an attribute definition. If the obligation for `drm` contains
+several values, and only one of them is `watermark`, a PEP or environmental entity that successfully meets the admin-defined obligation fulfillment conditions
+for specifically that obligation or any of the other child values of the `drm` obligation parent for the data (derived via attributes or on the TDF)
+would result in a permitted access decision.
+
+The fulfillment conditions of an obligation can be thought of as loosely similar to Condition Sets within Subject Mappings that drive entitlements.
+
+To allow access to data with obligations (derived by assignment to attribute values or directly added to a TDF), an admin must define the conditions
+an entity must meet as provided by the Entity Resolution Service (ERS) or OIDC token claims if running the platform without an ERS.
+
+For example, if `drm:watermark` is a required obligation contextualizing a TDF access decision, a user must first be entitled to the data attributes via subject mappings,
+but they must also meet the conditions that they're attempting to access through `Some_Cool_PEP`, which is known to the admin to support watermarking
+as a feature and respect it as an obligation on decrypt. The admin should define through the `fulfillments` subcommand the conditions where the obligation
+is fulfilled. In plain English, that would be: `if a user's access token indicates they are accessing through Some_Cool_PEP, the obligation has been fulfilled`.
+
+TODO: fulfillment conditions instruction here that comes from protos
+
+As you can see in the example above, the user's entity chain indicated they came through `Some_Cool_PEP` and therefore they were granted access alongside the obligation
+for `Some_Cool_PEP` to receive in response and drive the watermarking behavior.

docs/man/policy/obligations/create.md

@@ -0,0 +1,23 @@
+---
+title: Create an obligation
+command:
+  name: create
+  flags:
+    - name: name
+      shorthand: n
+      description: Name of the obligation (i.e. 'drm' for Digital Rights Management)
+      required: true
+    - name: value
+      shorthand: v
+      description: Values of the obligation (i.e. 'watermark')
+      required: false
+    - name: label
+      description: "Optional metadata 'labels' in the format: key=value"
+      shorthand: l
+      default: ''
+---
+
+An obligation, like an attribute definition, is a parent that can contain one or more values.
+
+For more information about the significance of obligations and how they are utilized for derived obligations on attribute values
+or when added directly to a TDF, view the parent command documentation with `--help`.

docs/man/policy/obligations/delete.md

@@ -0,0 +1,16 @@
+---
+title: Delete an obligation
+command:
+  name: delete
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the obligation
+      required: true
+---
+
+Because obligations are a post-entitlement decision, they are safe to delete. Upon deletion, any derived obligations as a result of
+mappings to platform policy attribute values will be removed, and any TDFs containing obligations within will remain accessible, just
+without obligations returned along with an access request to drive PEP behavior.
+
+Upon deletion, all child values and the entity conditions to satisfy an obligation are cascadingly deleted.

docs/man/policy/obligations/fulfillments/_index.md

@@ -0,0 +1,10 @@
+---
+title: Manage obligation fulfillments
+command:
+  name: fulfillments
+---
+
+Commands to manage the conditions under which obligations on attributes are fulfilled by subject and environment entities.
+
+For more information about the significance of obligations and how they are utilized for derived obligations on attribute values
+or when added directly to a TDF, view the parent command documentation with `--help`.

docs/man/policy/obligations/fulfillments/create.md

@@ -0,0 +1,23 @@
+---
+title: Create an obligation fulfillment
+command:
+  name: create
+  flags:
+    - name: conditions-json
+      description: TODO - Conditions as defined by the protos as JSON
+      required: false
+    - name: conditions-json-file
+      description: TODO - Conditions as defined by the protos from a JSON file
+      required: false
+    - name: obligation-scope
+      shorthand: s
+      description: Scope of the obligation as subject or environment [ SUBJECT, ENV ]
+      required: true
+    - name: label
+      description: "Optional metadata 'labels' in the format: key=value"
+      shorthand: l
+      default: ''
+---
+
+For more information about the significance of obligations and how they are utilized for derived obligations on attribute values
+or when added directly to a TDF, see the parent command above.

docs/man/policy/obligations/fulfillments/delete.md

@@ -0,0 +1,14 @@
+---
+title: Delete an obligation value
+command:
+  name: delete
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the obligation value
+      required: true
+---
+
+Because obligations are a post-entitlement decision, they are safe to delete. Upon deletion, any derived obligations as a result of
+mappings to platform policy attribute values will be removed, and any TDFs containing obligations within will remain accessible, just
+without obligations returned along with an access request to drive PEP behavior.

docs/man/policy/obligations/fulfillments/get.md

@@ -0,0 +1,18 @@
+---
+title: Get an obligation value
+command:
+  name: get
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the obligation value
+---
+
+Retrieves the obligation value, comprised of:
+
+- ID
+- value
+- parent obligation (name and ID)
+- FQN
+- any assigned attribute value FQNs and IDs for derived obligations
+- condition sets for mappings to entities that satisfy the obligation

docs/man/policy/obligations/fulfillments/list.md

@@ -0,0 +1,19 @@
+---
+title: List obligation values
+command:
+  name: list
+  flags:
+    - name: obligation-id
+      shorthand: o
+      description: The ID of the obligation to list values for
+    - name: state
+      shorthand: s
+      description: Filter by state
+      enum:
+        - active
+        - inactive
+        - any
+      default: active
+---
+
+Retrieves all obligation valuess stored in platform policy.

docs/man/policy/obligations/fulfillments/update.md

@@ -0,0 +1,17 @@
+---
+title: Update an obligation value
+command:
+  name: update
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the obligation value
+      required: true
+    - name: label
+      description: "Optional metadata 'labels' in the format: key=value"
+      shorthand: l
+      default: ""
+    - name: force-replace-labels
+      description: Destructively replace entire set of existing metadata 'labels' with any provided to this command
+      default: false
+---

docs/man/policy/obligations/get.md

@@ -0,0 +1,16 @@
+---
+title: Get an obligation
+command:
+  name: get
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the obligation
+---
+
+Retrieves the obligation, comprised of:
+
+- ID
+- name
+- child values (values and IDs)
+- FQN

docs/man/policy/obligations/list.md

@@ -0,0 +1,7 @@
+---
+title: List obligations
+command:
+  name: list
+---
+
+Retrieves all obligations stored in platform policy.

docs/man/policy/obligations/update.md

@@ -0,0 +1,17 @@
+---
+title: Update an attribute
+command:
+  name: update
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the attribute
+      required: true
+    - name: label
+      description: "Optional metadata 'labels' in the format: key=value"
+      shorthand: l
+      default: ""
+    - name: force-replace-labels
+      description: Destructively replace entire set of existing metadata 'labels' with any provided to this command
+      default: false
+---

docs/man/policy/obligations/values/_index.md

@@ -0,0 +1,10 @@
+---
+title: Manage obligation values
+command:
+  name: values
+---
+
+Commands to manage obligation values within an existing obligation.
+
+For more information about the significance of obligations and how they are utilized for derived obligations on attribute values
+or when added directly to a TDF, view the parent command documentation with `--help`.

docs/man/policy/obligations/values/assign.md

@@ -0,0 +1,18 @@
+---
+title: Assign an obligation value to an attribute value
+command:
+  name: assign
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the obligation value
+      required: true
+    - name: attr-val
+      description: ID of the attribute value(s) being assigned for derived obligations
+      required: true
+---
+
+Assigns an existing obligation value to one or more attribute values for derived obligations in an access decision.
+
+For more information about the significance of obligations and how they are utilized for derived obligations on attribute values,
+see the parent command.

docs/man/policy/obligations/values/create.md

@@ -0,0 +1,25 @@
+---
+title: Create an obligation value
+command:
+  name: create
+  flags:
+    - name: value
+      shorthand: v
+      description: Value being added to the existing obligation (i.e. 'watermark')
+      required: true
+    - name: obligation
+      shorthand: o
+      description: ID of the parent obligation
+      required: true
+    - name: attr-val
+      shorthand: a
+      description: ID of assigned attribute value(s) for derived obligations
+      required: false
+    - name: label
+      description: "Optional metadata 'labels' in the format: key=value"
+      shorthand: l
+      default: ''
+---
+
+For more information about the significance of obligations and how they are utilized for derived obligations on attribute values
+or when added directly to a TDF, see the parent command above.

docs/man/policy/obligations/values/delete.md

@@ -0,0 +1,14 @@
+---
+title: Delete an obligation value
+command:
+  name: delete
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the obligation value
+      required: true
+---
+
+Because obligations are a post-entitlement decision, they are safe to delete. Upon deletion, any derived obligations as a result of
+mappings to platform policy attribute values will be removed, and any TDFs containing obligations within will remain accessible, just
+without obligations returned along with an access request to drive PEP behavior.

docs/man/policy/obligations/values/get.md

@@ -0,0 +1,18 @@
+---
+title: Get an obligation value
+command:
+  name: get
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the obligation value
+---
+
+Retrieves the obligation value, comprised of:
+
+- ID
+- value
+- parent obligation (name and ID)
+- FQN
+- any assigned attribute value FQNs and IDs for derived obligations
+- condition sets for mappings to entities that satisfy the obligation

docs/man/policy/obligations/values/list.md

@@ -0,0 +1,19 @@
+---
+title: List obligation values
+command:
+  name: list
+  flags:
+    - name: obligation-id
+      shorthand: o
+      description: The ID of the obligation to list values for
+    - name: state
+      shorthand: s
+      description: Filter by state
+      enum:
+        - active
+        - inactive
+        - any
+      default: active
+---
+
+Retrieves all obligation valuess stored in platform policy.

docs/man/policy/obligations/values/unassign.md

@@ -0,0 +1,19 @@
+---
+title: Unassign an obligation value from an attribute value
+command:
+  name: unassign
+  flags:
+    - name: id
+      shorthand: i
+      description: ID of the obligation value
+      required: true
+    - name: attr-val
+      description: ID of the attribute value being removed for derived obligation assignment
+      required: true
+---
+
+Unassigns an obligation value from an attribute value so that the obligation is no longer considered a derived obligation in an
+access decision.
+
+For more information about the significance of obligations and how they are utilized for derived obligations on attribute values,
+see the parent command.