opentdf
diff --git a/‎.github/workflows/languagetool.yaml‎
Lines changed: 0 additions & 20 deletions b/‎.github/workflows/languagetool.yaml‎
Lines changed: 0 additions & 20 deletions
diff --git a/‎.github/workflows/vale.yaml‎
Lines changed: 1 addition & 1 deletion b/‎.github/workflows/vale.yaml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.gitignore‎
Lines changed: 2 additions & 0 deletions b/‎.gitignore‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎LICENSE‎
Lines changed: 430 additions & 0 deletions b/‎LICENSE‎
Lines changed: 430 additions & 0 deletions
diff --git a/‎code_samples/policy_code/create_attribute.mdx‎
Lines changed: 17 additions & 4 deletions b/‎code_samples/policy_code/create_attribute.mdx‎
Lines changed: 17 additions & 4 deletions
diff --git a/‎code_samples/policy_code/create_namespace.mdx‎
Lines changed: 1 addition & 1 deletion b/‎code_samples/policy_code/create_namespace.mdx‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎code_samples/policy_code/create_subject_condition_set.mdx‎
Lines changed: 2 additions & 1 deletion b/‎code_samples/policy_code/create_subject_condition_set.mdx‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎code_samples/tdf/encryption_ztdf.mdx‎
Lines changed: 20 additions & 17 deletions b/‎code_samples/tdf/encryption_ztdf.mdx‎
Lines changed: 20 additions & 17 deletions
diff --git a/‎docs/components/authorization.md‎
Lines changed: 143 additions & 9 deletions b/‎docs/components/authorization.md‎
Lines changed: 143 additions & 9 deletions
@@ -3,7 +3,7 @@ name: Vale
 on:
   pull_request:
     branches:
-      - disabled
+      - main
 
 jobs:
   vale-check:
 
@@ -11,6 +11,8 @@ docs/SDK-Samples/
 # Generated files
 .docusaurus
 .cache-loader
+# Ignore all generated _category_.json files in docs/spec
+/docs/spec/**/_category_.json
 
 # Misc
 .DS_Store
 
@@ -11,10 +11,12 @@ package main
 
 import (
 	"context"
+	"crypto/rand"
 	"log"
 
 	"github.com/opentdf/platform/protocol/go/policy"
 	"github.com/opentdf/platform/protocol/go/policy/attributes"
+	"github.com/opentdf/platform/protocol/go/policy/namespaces"
 	"github.com/opentdf/platform/sdk"
 )
 
@@ -32,20 +34,31 @@ func main() {
 		log.Fatal(err)
 	}
 
-	// Create a new attribute
-	namespaceID := "f9ac9403-a12f-4ed3-b3c9-a46910361b4d"
+	// List namespaces to get a namespace ID
+	listResponse, err := client.Namespaces.ListNamespaces(context.Background(), &namespaces.ListNamespacesRequest{})
+	if err != nil {
+		log.Fatalf("failed to list namespaces: %s", err)
+	}
 
+	if len(listResponse.GetNamespaces()) == 0 {
+		log.Fatal("no namespaces found")
+	}
+
+	namespaceID := listResponse.GetNamespaces()[0].GetId()
+
+	// Create a new attribute
 	attrRequest := &attributes.CreateAttributeRequest{
 		NamespaceId: namespaceID,
-		Name:        "role",
+		Name:        "role" + "-" + rand.Text()[:4],
 		Rule:        policy.AttributeRuleTypeEnum_ATTRIBUTE_RULE_TYPE_ENUM_ANY_OF,
 		Values:      []string{"admin", "developer", "guest"},
 	}
 
-	_, err = client.Attributes.CreateAttribute(context.Background(), attrRequest)
+	attribute, err := client.Attributes.CreateAttribute(context.Background(), attrRequest)
 	if err != nil {
 		log.Fatal(err)
 	}
+	log.Printf("Created attribute: %s with ID: %s in namespace: %s\n", attribute.GetAttribute().Name, attribute.GetAttribute().GetId(), namespaceID)
 }
 ```
 
 
@@ -19,7 +19,7 @@ import (
 
 func main() {
 
-	platformEndpoint := "https://opentdf.io"
+	platformEndpoint := "http://localhost:9002"
 
 	// Create a new client
 	client, err := sdk.New(
 
@@ -55,11 +55,12 @@ func main() {
 		},
 	}
 
-	_, err = client.SubjectMapping.CreateSubjectConditionSet(context.Background(), coditionset)
+	log, err := client.SubjectMapping.CreateSubjectConditionSet(context.Background(), coditionset)
 	if err != nil {
 		log.Fatal(err)
 	}
 
+	log.Printf("Created Subject Condition Set with ID: %s\n", resp.GetSubjectConditionSet().GetId())
 }
 ```
 
 
@@ -10,64 +10,67 @@ import TabItem from '@theme/TabItem';
 package main
 
 import (
-	"bufio"
 	"bytes"
 	"log"
-	"os"
 	"strings"
 
 	"github.com/opentdf/platform/sdk"
 )
 
 func main() {
+	log.Println("🚀 Starting OpenTDF example...")
 
 	platformEndpoint := "http://localhost:9002"
+	log.Printf("📡 Connecting to platform: %s", platformEndpoint)
 
 	// Create a new client
+	log.Println("🔐 Initializing new SDK client...")
 	client, err := sdk.New(
 		platformEndpoint,
 		sdk.WithClientCredentials("opentdf", "secret", nil),
 	)
 
 	if err != nil {
-		log.Fatal(err)
+		log.Fatalf("❌ Client initialization failed: %v", err)
 	}
 
 	// Encrypt ztdf
-
+	log.Println("📝 Preparing sensitive data for encryption...")
 	str := strings.NewReader("Sensitive data!")
 	buf := &bytes.Buffer{}
-	out := bufio.NewWriter(buf)
 
-	manifest, err := client.CreateTDF(out, str,
+	log.Println("🔒 Encrypting data...")
+	manifest, err := client.CreateTDF(buf, str,
 		//sdk.WithDataAttributes("https://opentdf.io/attr/role/value/developer"),
 		sdk.WithKasInformation(
 			sdk.KASInfo{
-				URL: "http://localhost:9002",
+				URL: platformEndpoint,
 			},
 		),
 	)
 
 	if err != nil {
-		log.Fatal(err)
+		log.Fatalf("❌ Encryption failed: %v", err)
 	}
 
-	//Flush data to buffer
-	out.Flush()
-
-	log.Printf("TDF Manifest: %v", manifest)
+	log.Println("✅ Data successfully encrypted")
+	log.Printf("📋 TDF Manifest details:\n\n%v\n\n", manifest)
 
 	// Decrypt ztdf
+	log.Println("🔓 Decrypting data...")
 	tdfReader, err := client.LoadTDF(bytes.NewReader(buf.Bytes()))
 	if err != nil {
-		log.Fatal(err)
+		log.Fatalf("❌ Decryption failed: %v", err)
 	}
 
-	// Write decrypted data to stdout
-	_, err = tdfReader.WriteTo(os.Stdout)
-	if err != nil {
-		log.Fatal(err)
+	// Create a buffer to capture the decrypted data
+	var decryptedBuf bytes.Buffer
+	if _, err = tdfReader.WriteTo(&decryptedBuf); err != nil {
+		log.Fatalf("❌ Failed to write decrypted data: %v", err)
 	}
+
+	log.Printf("📤 Decrypted content: \n\n%s\n\n", decryptedBuf.String())
+	log.Println("✅ Example complete!")
 }
 ```
 
 
@@ -4,21 +4,155 @@ sidebar_position: 1
 
 # Authorization Service
 
-The Authorization service makes access decisions based on Attribute-Based Access Control (ABAC) policies and evaluates subject mappings to assign attributes to specific entities. The service provides two endpoints: **GetEntitlements** and **GetDecisions**.
+The Authorization service makes access decisions based on Attribute-Based Access Control (ABAC) policies and evaluates subject mappings and attribute definition rules to determine allowed actions on attribute values for specified entities.
 
-## GetEntitlements
-
-The `GetEntitlements` endpoint takes a list of entities and returns the attributes to which each entity is entitled. Entitlements are based on subject mappings, as described in the [policy documentation](./policy/subject_mappings), and the entity data returned by the [entity resolution service](./entity_resolution).
-
-### Entities
-
-An entity is any being or structure interacting with the platform. A **person entity (PE)** represents an actual user, while a **non-person entity (NPE)** represents a system or program interacting on behalf of a user or via automation.
+An entity is any being or principal interacting with the platform. A **person entity (PE)** represents an actual user, while a **non-person entity (NPE)** represents a system or program interacting on behalf of a user/organization or via automation.
 
 Entities are categorized into two types:
 
 - **Subject entities**: These include PEs or NPEs and are evaluated in access decisions.
 - **Environment entities**: These are excluded from access decisions.
 
+Two versions of Authorization Service are currently served simultaneously by the platform, with v1 being deprecated soon:
+- [v2](#v2-latest)
+- [v1](#v1-soon-to-be-deprecated)
+
+## v2 (latest)
+
+### Changes
+
+Version 2 of Authorization Service introduced the following changes:
+- Consideration of policy [actions](./policy/actions.md) from [subject mappings](./policy/subject_mappings.md) in entitlement decisions
+- API structure and clarity improvements
+  - [entity identifier](#entity-identifier)
+  - multiplexing design within decisioning
+  - removal of scopes when retrieving entitlements, in deference to decision APIs
+- Removal of configurable custom `Rego` support
+
+#### Entity Identifier
+
+The entity identifier is a request proto object allowing multiple structures representing an entity to stand in as the entity in an Auth Service request:
+- an Entity Chain (the response from an `entityresolutionservice.v2.CreateEntityChainsFromTokens` call)
+- a Token (access token JWT)
+- the FQN of a Registered Resource Value (_EXPERIMENTAL_)
+
+#### Resource
+
+The resource is a request proto object allowing multiple structures representing a resource to stand in as the resource in an Auth Service Decision request:
+- a list of Attribute Values FQNs
+- the FQN of a Registered Resource Value (_EXPERIMENTAL_)
+
+### GetEntitlements
+
+The `GetEntitlements` endpoint takes an Entity Identifier and returns the entitled actions per attribute value back (entitlements).
+
+Entitlements are driven by subject mappings, as described in the [policy documentation](./policy/subject_mappings), and the entity data returned by the [entity resolution service](./entity_resolution).
+
+The request flag `with_comprehensive_hierarchy` will drive response behavior for attribute values on definitions with a `hierarchy` rule. If the flag
+is omitted or passed with value `false`, the response will contain strictly the resolved subject mappings' entitled actions for each attribute value.
+However, if it is set to `true` in a request, actions will propagate down hierarchically to each lower-hierarchy attribute value within the response. This propagation behavior is the same utilized during `GetDecision` flows to drive ABAC entitlement between entities and resources.
+
+Say there are three subject mappings for a single entity as the EntityIdentifier ephemeral ID `entity_xyz`:
+1. contains actions `read, update` and a mapped attribute value `https://example.com/attr/department/value/engineering` on an ANY_OF definition
+2. contains action `read` and a mapped attribute value `https://example.com/attr/level/value/higher` on a HIERARCHY definition containing values `higher, medium, lower`, which therefore gets propagated down comprehensively
+3. contains action `delete` and a mapped attribute value `https://example.com/attr/level/value/lower` on a HIERARCHY definition containing values `higher, medium, lower`
+
+The `GetEntitlements` response would look like the below if `with_comprehensive_hierarchy` is set to `true`:
+
+```json
+{
+  "entitlements":[
+    {
+      "ephemeral_id":"entity_xyz",
+      "actions_per_attribute_value_fqn":{
+        "https://example.com/attr/level/value/higher":{
+          "actions":[
+            {
+              "id":"<action policy object UUID>",
+              "name":"read"
+            }
+          ]
+        },
+        "https://example.com/attr/level/value/medium":{
+          "actions":[
+            {
+              "id":"<action policy object UUID>",
+              "name":"read"
+            }
+          ]
+        },
+        "https://example.com/attr/level/value/lower":{
+          "actions":[
+            {
+              "id":"<action policy object UUID>",
+              "name":"delete"
+            },
+            {
+              "id":"<action policy object UUID>",
+              "name":"read"
+            }
+          ]
+        },
+        "https://example.com/attr/department/value/engineering":{
+          "actions":[
+            {
+              "id":"<action policy object UUID>",
+              "name":"read"
+            },
+            {
+              "id":"<action policy object UUID>",
+              "name":"update"
+            }
+          ]
+        },
+      }
+    }
+  ]
+}
+```
+
+### GetDecision, GetDecisionMultiResource, GetDecisionBulk
+
+The `GetDecision` endpoints evaluate access control permissions over entities, actions, and resources.
+
+The [request/response protos](https://github.com/opentdf/platform/blob/main/service/authorization/v2/authorization.proto) define
+structures for more specific decisioning flows than the v1 catch-all `GetDecisions` endpoint.
+
+In all decision flows, the access logic is as follows:
+1. given the Entity Identifier, which Subject Mappings in Policy are relevant and resolve to true?
+2. given the Subject Mappings, which contained Actions are entitled on which Attribute Values?
+3. given the entitled Actions per each Attribute Value, which Attribute Definitions are relevant to the Resource attributes?
+4. given the relevant entitlements and resource attributes, are the attribute definition rules satisfied by the entity's entitlements
+for the requested action name?
+
+In other words, a Decision will be to _deny_ if:
+1. no subject mappings apply to an entity
+2. some subject mappings apply to an entity, but none containing the specific requested action
+3. some subject mappings apply to an entity, but they only entitle the specific requested action on attribute values other than
+those of the requested resource
+4. the subject mappings entitle some of the resource's attribute values for the requested action, but not enough to satisfy the attribute definition rule (ANY_OF, ALL_OF, HIERARCHY) given the requested resource's attribute values
+
+Endpoints:
+1. `GetDecision`: can this entity take this action on this resource?
+  - one Entity Identifier
+  - one Action (`name` is required)
+  - one Resource
+2. `GetDecisionMultiResource`: can this entity take this action on these resources?
+  - one Entity Identifier
+  - one Action (`name` is required)
+  - multiple Resources
+3. `GetDecisionBulk`: more performant batch processing of multiple `GetDecisionMultiResource` requests
+  - useful for multiple entities
+  - useful for multiple actions
+
+## v1 (soon to be deprecated)
+
+### GetEntitlements
+
+The `GetEntitlements` endpoint takes a list of entities and returns the attributes to which each entity is entitled. Entitlements are based on subject mappings, as described in the [policy documentation](./policy/subject_mappings), and the entity data returned by the [entity resolution service](./entity_resolution).
+
+#### Entities
+
 Entities can be identified using various methods, as shown in the proto definition:
 
 ```protobuf
@@ -99,7 +233,7 @@ Below is an example response to the above GetEntitlements request:
 
 The entities in the response can be mapped back to the original input using the entity ID. The "attribute_value_fqns" field includes a list of attribute FQNs to which that particular entity has been entitled. If no scope was provided, this field will include **ALL** of the attribute entitlements for that entity.
 
-## GetDecisions
+### GetDecisions
 
 The `GetDecisions` endpoint evaluates access control rules for one or more entity chains and resources. It checks whether entities have permission to perform specified actions on resources, based on provided attributes.
Original file line number	Diff line number	Diff line change
`@@ -55,11 +55,12 @@ func main() {`
`55`	`55`	`},`
`56`	`56`	`}`
`57`	`57`
`58`		`- _, err = client.SubjectMapping.CreateSubjectConditionSet(context.Background(), coditionset)`
	`58`	`+ log, err := client.SubjectMapping.CreateSubjectConditionSet(context.Background(), coditionset)`
`59`	`59`	`if err != nil {`
`60`	`60`	`log.Fatal(err)`
`61`	`61`	`}`
`62`	`62`
	`63`	`+ log.Printf("Created Subject Condition Set with ID: %s\n", resp.GetSubjectConditionSet().GetId())`
`63`	`64`	`}`
`64`	`65`	```
`65`	`66`