version 3.0.0 (#152)

* policy event serializable

refactor event package

add json property value test

add a timestamped policy event

add getter/setter for hash

remove events

add setter methods for memory policy store

cast to memory components

funcexec can't be serialized

add funcexec not serializable test

expose tx in memory policy store

add getter for tx events

fix deserialize from pml

update mysql connector dependency

fix double call to verifySuperPolicy

fix policy store deserialization

fix mem tx and remove unused constants

do not overwrite mem tx on reset

add reset to policy and event

implement reset

add reset event

saving progress

update docs

update tests

update pml serialization

saving serialization progress

serialization tests

updates

fix tests

move amin policy nodes to own enum file

fix documentation references

add node file

access right checker test

fix test config

rename admin policy target node

new test updates

pml updates

add delete tests

remove optional token

remove super bootstrapper and fix tests that use super user

remove unused variable

optimize imports

rename policy classes oa constant

fix doc link error

add nist template files

update readme

remove comment

add tests

review tests

constants and functions handled first

move serialization package to policy

fix json PML functions

pml update for functions and constants

remove println

function invoke updates

fix function returns and explain

make memory policy get methods return unmodifiable objects

modify graph interface to remove no property create methods and allow user attributes to be created without assignments

update mysql connector

update commons-lang version

update commons-lang version to 3.13

update jackson-databind version to 2.15

remove jackson-databind dependency

add neo4j embedded support

add neo4j pdp

add neo4j review tests

create impl package

some package refactoring

package refactor

rename events to operations and move to common package

bump java version to 21 and remove serial uid

saving progress on operations

refactor pap methods

small fixes from previous commit, still some test failures

saving progress, compiles, look for TODOs

saving progress before removing common package

saving progress, pap tests pass

add pdp tests

save progress

updates - serialization not working

remove neo4j tests

remove neo4j classes

update jitpack java version to 21

saving progress before refactor

saving progress with json before rebase

fix errors from rebase

small fix

serialization and test fixes

rename child -> ascendant and parent -> descendant to be more in line with standard

fix sample pml

modifier returns querier not query

multiple input strings to deserialization

operations refactor

saving progress on function refactor

create operations with operands

add ReqCap

update ops

add generic to operation return

update operation

refactor operations

saving before moving to named operations

saving progress

fix pml functions

save

fix patterns for obligations

refactor expressions to not be operations

saving

change assign to to in

tests pass

before refactoring routines

fix operations and routines

add tests

check statement does one ar at a time

dep update

pml patterns tests

add to PML bootstrapper test

add checks to pml methods in pdptx

small fixes and docs

some java docs

move files in memory pkg

fix memory pkg error

small changes

* remove comment

* remove common pkg, move to pap

* fix errors

* readme

* update pom.xml

* update java version in github action

.github/workflows/maven.yml

@@ -22,10 +22,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up JDK 17
+    - name: Set up JDK 21
       uses: actions/setup-java@v3
       with:
-        java-version: '17'
+        java-version: '21'
         distribution: 'temurin'
         cache: maven
     - name: Build with Maven

.gitignore

@@ -1,4 +1,5 @@
 .idea
 policy-machine-core.iml
 /target
-.DS_Store
+.DS_Store
+**/gen/

CODEMETA.yaml

@@ -0,0 +1,36 @@
+# Topics for the NIST Open Source Portal <https://code.nist.gov>
+#
+# Set the topic tags for your open source repository from the nested
+# list below. Un-comment the relevant lines:
+#
+#     remove the `#` character *and* the space immediately after it
+#
+# so that the YAML syntax remains valid. You may delete everything
+# that does not apply, and add new topics from the NIST Taxonomy
+# <https://data.nist.gov/od/id/691DDF3315711C14E0532457068146BE1907>
+#
+# For example, a valid version of this file would be (note the `:`
+# and `---`, they are important!) as follows:
+#
+# ---
+# categories:
+#   - scientific-software
+#
+# themes:
+#   - Information Technology
+#       - Software research
+#           - Software performance
+#
+# Since scientific-software is most common it is left as the default
+# category. Feel free to comment it with a hash (#) if it does not
+# apply. There is no default theme; select as many as are relevant.
+# Make sure to remove unwanted categories as the final topics are
+# produced from this file.
+
+---
+categories:
+  - scientific-software
+
+themes:
+  - Information Technology
+      - Identity and access management

CODEOWNERS

@@ -0,0 +1,9 @@
+# This file lists the contributors responsible for the
+# repository content. They will also be automatically
+# asked to review any pull request made in this repository.
+
+# Each line is a file pattern followed by one or more owners.
+# The sequence matters: later patterns take precedence.
+
+# FILES  OWNERS
+*        @usnistgov/opensource-team

LICENSE.md

@@ -0,0 +1,35 @@
+# NIST Software Licensing Statement
+
+NIST-developed software is provided by NIST as a public service.
+You may use, copy, and distribute copies of the software in any
+medium, provided that you keep intact this entire notice. You may
+improve, modify, and create derivative works of the software or
+any portion of the software, and you may copy and distribute such
+modifications or works. Modified works should carry a notice
+stating that you changed the software and should note the date
+and nature of any such change. Please explicitly acknowledge the
+National Institute of Standards and Technology as the source of
+the software.
+
+NIST-developed software is expressly provided "AS IS." NIST MAKES
+NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT, OR ARISING BY
+OPERATION OF LAW, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+NON-INFRINGEMENT, AND DATA ACCURACY. NIST NEITHER REPRESENTS NOR
+WARRANTS THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED
+OR ERROR-FREE, OR THAT ANY DEFECTS WILL BE CORRECTED. NIST DOES
+NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF THE
+SOFTWARE OR THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE
+CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF THE
+SOFTWARE.
+
+You are solely responsible for determining the appropriateness of
+using and distributing the software and you assume all risks
+associated with its use, including but not limited to the risks
+and costs of program errors, compliance with applicable laws,
+damage to or loss of data, programs or equipment, and the
+unavailability or interruption of operation. This software is not
+intended to be used in any situation where a failure could cause
+risk of injury or damage to property. The software developed by
+NIST employees is not subject to copyright protection within the
+United States.

README.md

@@ -1,14 +1,13 @@
 # Policy Machine Core
 
-The core components of the NIST Policy Machine, a reference implementation of the Next Generation Access Control (NGAC) standard. For complete documentation and detailed examples visit the [Wiki](https://github.com/PM-Master/policy-machine-core/wiki).
+The core components of the NIST Policy Machine, a reference implementation of the Next Generation Access Control (NGAC) standard. 
+For complete documentation and detailed examples visit the Wiki.
 
-## Table of Contents
-1. [Installation](#install-using-maven)
-2. [Basic Usage](#basic-usage)
-3. [Policy Author Language (PAL)](/pml/README.md)
+## Installation
+
+### Install using Maven
+Policy Machine Core uses [JitPack](https://jitpack.io/) to compile and build the artifact to import with maven.
 
-## Install using Maven
-Policy Machine Core uses [JitPack](https://jitpack.io/) to compile and build the artifact to import into projects.
 First, add jitpack as a repository
 ```xml
 <project>
@@ -22,93 +21,131 @@ First, add jitpack as a repository
   --
 </project>
 ```
+
 Then, add the maven dependency
 ```xml
 <dependency>
     <groupId>com.github.PM-Master</groupId>
     <artifactId>policy-machine-core</artifactId>
-    <version>LATEST</version>
+    <version>3.0.0</version>
 </dependency>
 ```
+## Package Description
+
+- `pap` - Policy Administration Point. Provides the Policy Machine implementation of the NGAC PAP interfaces for modifying and querying policy.
+- `pdp` - Policy Decision Point. Implementation of an administrative PDP that controls access to admin operations on the PAP.
+- `epp` - Event Processing Point. The epp attaches to a PDP to listen to administrative events while exposing an interface for a PEP to send events.
+- `impl` - Policy Machine supported implementations of the PAP interfaces.
 
 ## Basic Usage
+The following examples use the provided in memory PAP.
 
-Policy Machine Language docs can be found [here](/pml)
+### PAP Usage
 
-### 1. Policy Machine Language (PML) definition
+#### Create a policy with the `PolicyModification` interface
 ```java
-String pal = """
-set resource access rights ["read", "write"]
-
-create policy class "pc1"
-create user attribute "ua1" in ["pc1"]
-create user attribute "oa1" in ["pc1"]
-associate "ua1" and "oa1" with ["read", "write"]
-
-create policy class "pc2"
-assign "ua2" to ["pc2"]
-create user attribute "oa2" in ["pc2"]
-associate "ua2" and "oa2" with ["read", "write"]
-
-create user "u1" in ["ua1", "ua2"]
-create user "u2" in ["ua1", "ua2"]
+// create a new memory PAP
+PAP pap = new MemoryPAP();
 
-create object "o1" in ["oa1", "oa2"]
+// set the resource operations that the policy will support
+pap.modify().operations().setResourceOperations(new AccessRightSet("read", "write"));
+
+// create a simple configuration with one of each node type, granting u1 read access to o1.
+pap.modify().graph().createPolicyClass("pc1");
+pap.modify().graph().createUserAttribute("ua1", List.of("pc1"));
+pap.modify().graph().createUser("u1", List.of("ua1"));
+pap.modify().graph().createObjectAttribute("oa1", List.of("pc1"));
+pap.modify().graph().createObject("o1", List.of("oa1"));
+
+// create a prohibition
+pap.modify().prohibitions().createProhibition(
+        "deny u1 write on oa1", 
+        ProhibitionSubject.userAttribute("u1"), 
+        new AccessRightSet("write"), 
+        false,
+        List.of("oa1")
+);
+
+// create an obligation that associates ua1 with any OA
+String obligationPML = """
+create obligation "sample_obligation" {
+	create rule "rule1"
+	when any user
+	performs "create_object_attribute"
+	on {
+        descendants: "oa1"
+    }
+	do(ctx) {
+		associate "ua1" and ctx.operands.name with ["read", "write"]
+	}
+}
+""";
 
-create prohibition "u2-prohibition"
-deny user "u2"
-access rights ["write"]
-on intersection of ["oa1", "oa2"]
+// when creating an obligation a user is required
+// this is the user the obligation response will be executed on behalf of
+pap.executePML(new UserContext("u1"), obligationPML);
+```
 
-create obligation "o1-obligation" {
-    create rule "o1-assignment-rule"
+#### Create a policy with `PML`
+```java
+String pml = """
+set resource operations ["read", "write"]
+
+create pc "pc1"
+create oa "oa1" in ["pc1"]
+create ua "ua1" in ["pc1"]
+create u "u1" in ["ua1"]
+create o "o1" in ["oa1"]
+
+create prohibition "deny u1 write on oa1" 
+deny user "u1" 
+access rights ["write"] 
+on union of ["oa1"]
+
+create obligation "sample_obligation" {
+    create rule "rule1"
     when any user
-    performs ["assign"]
-    on "o1"
-    do(evtCtx) {
-        let parent = evtCtx["parent"]
-        associate "ua1" and parent with ["read", "write"]
-        associate "ua2" and parent with ["read", "write"]
+    performs "create_object_attribute"
+    on {
+        descendants: "oa1"
+    }
+    do(ctx) {
+        associate "ua1" and ctx.operands.name with ["read", "write"]
     }
 }
-"""
+""";
 ```
 
-#### 2. Load PAL into a Memory Policy Administration Point (PAP) as the super user
-No access checks are done yet, the user is needed to know who the author of any obligations are.
+A user is required to execute PML. This user will be the defined author of any obligations created.
 ```java
-UserContext superUser = new UserContext(SUPER_USER);
-PAP pap = new MemoryPAP();
-pap.deserialize().fromPML(superUser, input);
-```
+// execute the pml and apply to existing policy
+pap.executePML(new UserContext("u1")), pml);
 
-#### 3. Wrap in a PDP object to add administrative permission checks
-```java
-PDP pdp = new MemoryPDP(pap);
+// or
+
+// reset the current policy befire applying the PML
+pap.deserialize(new UserContext("u1"), pml, new PMLDeserializer())
 ```
 
-#### 4. Run a PDP Transaction as the super user
-This transaction will create 'pc3' and 'oa3', then assign 'o1' to 'oa3'. This will trigger the obligation to associate
-'ua1' and 'ua2' with 'oa3'.
+### PDP Usage
+#### Initialization
 ```java
-pdp.runTx(superUser, (policy) -> {
-    policy.graph().createPolicyClass("pc3")
-    policy.graph().createObjectAttribute("oa3", "pc2");
-    policy.graph().assign("o1", "oa3");
-});
+PDP pdp = new PDP(pap);
 ```
-
-#### 5. Run a PDP transaction as u1 that will fail
-u1 does not have permission to create an object attribute in 'oa1'. This transaction will fail and 'newOA' will not be created.
+#### Run a transaction as a user
 ```java
-UserContext u1 = new UserContext("u1");
-pdp.runTx(u1, (policy) -> {
-    policy.graph().createObjectAttribute("newOA", "oa1");
+pdp.runTx(new UserContext("u1"), (policy) -> {
+    policy.modify().graph().createPolicyClass("pc3")
+    policy.modify().graph().createObjectAttribute("oa3", "pc2");
+    policy.modify().graph().assign("o1", "oa3");
 });
 ```
 
-#### 6. Create an EPP to respond to policy events
-An EPP will listen to policy events from the provided PDP and process obligations accordingly.
+### EPP Usage
+An EPP will listen to policy events from the provided PDP and process obligations in the PAP accordingly. The EPP and PDP uses an event listener pattern. The EPP listens to events from the PDP, attaching itself within the EPP constructor.
 ```java
 EPP epp = new EPP(pdp, pap);
+
+// will trigger above obligation response and associate ua1 with oa2
+pdp.modify().graph().createObjectAttribute("oa2", List.of("oa1"));
 ```