fix(core): improve KASR docs and add spellcheck GHA to pipeline (#323)

Resolves #335
Resolves #337

Author: jakedoublev

.github/spellcheck.ignore

@@ -0,0 +1,98 @@
+AllOf
+AnyOf
+Auth
+CLI's
+Changelog
+ConditionGroup
+CoolTool
+Decrypt
+ERS
+FQNs
+Hostname
+JSON
+JWT
+KASes
+KASs
+LDAP
+MacOS
+NPM
+Namespace
+Nano
+OIDC
+OpenTDF
+PDP
+PKCE
+README
+RadService
+SCS
+SDK
+ShinyThing
+TDF
+TDF'd
+TDFd
+TDFs
+TLS
+TODO
+TUI
+URI
+Unassign
+acmeco
+args
+attr
+auth
+cli
+clientId
+clientSecret
+config
+data-centric
+decrypt
+decryptable
+decrypted
+dev
+encodings
+enum
+https
+idP
+jq
+json
+jwt
+kas
+kas-url-path
+kasg
+kasr
+keychain
+keycloak
+keyring
+localhost
+namespace
+namespaces
+nano
+ns
+otdfctl
+performant
+poc
+pubkey
+quickstart
+resm
+resolvers
+scs
+sm
+stdin
+stdout
+stdout
+subcommand
+subcs
+subm
+submap
+tdf
+tdf-type
+tls
+tls-no-verify
+txt
+unassign
+unassignment
+upsert
+uri
+with-client-creds
+with-client-creds-file
+yaml

.github/workflows/spellcheck.yaml

@@ -0,0 +1,22 @@
+name: 'spellcheck'
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - LICENSE
+      - CODEOWNERS
+      - '.gitignore'
+      - '**/*.go'
+
+jobs:
+  spellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: matheus23/[email protected]
+        with:
+          files-to-check: '**/*.md'
+          files-to-exclude: 'CHANGELOG.md'
+          words-to-ignore-file: './.github/spellcheck.ignore'

docs/man/policy/_index.md

@@ -14,7 +14,7 @@ command:
 
 Manage policies within the platform.
 
-Policy is a set of rules that are enforced by the platform. Specific to the the data centric
+Policy is a set of rules that are enforced by the platform. Specific to the the data-centric
 security, policy revolves around data attributes (referred to as attributes). Within the context
 of attributes are namespaces, values, subject-mappings, resource-mappings, key-access-server grants,
 and other key elements.

docs/man/policy/kas-grants/_index.md

@@ -15,7 +15,14 @@ they can be assigned grants to various attribute objects (namespaces, definition
 
 > See `kas-registry` command within `policy` to manage the KASs known to the platform.
 
-Grants are utilized by the platform at two important points when engaging with a TDF.
+Key Access Grants are associations between a registered KAS (see KAS Registry docs) and an Attribute.
+
+An attribute can be assigned a KAS Grant on its namespace, its definition, or any one of its values.
+
+Grants enable key split behaviors on TDFs with attributes, which can be useful for various collaboration scenarios around shared policy.
+
+> [!WARNING]
+> KAS Grants are considered experimental, as grants to namespaces are not fully utilized within encrypt/decrypt flows at present.
 
 ## Utilization
 
@@ -26,7 +33,7 @@ is found to be permissible):
 1. look up the attributes on the TDF within the platform
 2. find any associated grants for those attributes' values, definitions, namespaces
 3. retrieve the public key of each KAS granted to those attribute objects
-4. determine based on the specificity matrix below which keys to utilize
+4. determine based on the specificity matrix below which keys to utilize in splits
 
 ## Specificity
 
@@ -47,3 +54,69 @@ Grants to Attribute Objects:
 
 > Note:
 > A namespace grant may soon be required with deprecation of a default KAS/platform key.
+
+## Split Scenarios
+
+### AnyOf Split
+
+`Bob` and `Alice` want to share data equally, but maintain their ability to decrypt the data without sharing each other’s private keys.
+
+With KAS Grants, they can define a key split where the shared data is wrapped with both of their public keys and AnyOf logic, meaning that each partner could decrypt the data with just one of those keys.
+
+If `Bob` assigns a grant between Bob's running/registered KAS to a known attribute value, and `Alice` defines a grant of Alice's running/registered KAS to the same attribute value,
+any data encrypted in a TDF will be decryptable with a key released by _either_ of their Key Access Servers.
+
+Attribute A: `https://conglomerate.com/attr/organization/value/acmeco`
+
+Attribute B: `https://conglomerate.com/attr/organization/value/example_inc`
+
+| Attribute | Namespace        | Definition   | Value       |
+| --------- | ---------------- | ------------ | ----------- |
+| A         | conglomerate.com | organization | acmeco      |
+| B         | conglomerate.com | organization | example_inc |
+
+**Attribute KAS Grant Scenarios**
+
+1. Bob & Alice represent individual KAS Grants to attributes on TDF'd data
+2. Note that the attributes A and B are of _the same definition and namespace_
+
+| Definition: organization | Value: acmeco | Value: example_inc | Split |
+| ------------------------ | ------------- | ------------------ | ----- |
+| Bob, Alice               | -             | -                  | OR    |
+| -                        | Bob, Alice    | -                  | OR    |
+| -                        | -             | Bob, Alice         | OR    |
+| -                        | Bob           | Alice              | OR    |
+
+### AllOf Split
+
+Unlike the `AnyOf` split above, this time `Bob` and `Alice` want to make sure _both_ of their keys must be granted for data in a TDF
+to be decrypted. With KAS Grants, they can define a key split where the shared data is wrapped with both of their public keys and
+AllOf logic, meaning that neither partner can decrypt the data with just one of those keys.
+
+To accomplish this, they each define KAS Grants between their KASes and policy attributes, and TDF data with at least two attributes -
+one assigned a KAS Grant to Bob's KAS and another assigned a KAS Grant to Alice's KAS.
+
+Both KASes will need to permit access and release payload keys for the data TDF'd with multiple attributes assigned KAS Grants to be accessible and decrypted.
+
+Attribute A: `https://conglomerate.com/attr/organization/value/acmeco`
+
+Attribute B: `https://conglomerate.com/attr/department/value/sales`
+
+| Attribute | Namespace        | Definition   | Value     |
+| --------- | ---------------- | ------------ | --------- |
+| A         | conglomerate.com | organization | acmeco    |
+| A         | conglomerate.com | department   | marketing |
+
+**Attribute KAS Grant Scenarios**
+
+1. Bob & Alice represent individual KAS Grants to attributes on TDF'd data
+2. Note that the attributes A and B are of _the same namespace but different definitions_
+
+| Definition: A | Value: A | Definition: B | Value: B | Split |
+| ------------- | -------- | ------------- | -------- | ----- |
+| Bob           | -        | Alice         | -        | AND   |
+| Bob           | -        | -             | Alice    | AND   |
+| -             | Bob      | -             | Alice    | AND   |
+
+> [!NOTE]
+> Any KAS Grants to attributes of different definitions or namespaces will be `AND` splits.

docs/man/policy/kas-registry/create.md

@@ -44,7 +44,7 @@ can be retrieved for the registered KAS under the `remote` key, such as `https:/
         "pem": "<your PEM certificate>",
         // key identifier 
         "kid": "<your key id>",
-        // algorithm (either: 1 for rsa:2048, 2 for ec:secp256r1)
+        // key algorithm (see table below)
         "alg": 1
       }
     ]
@@ -54,7 +54,16 @@ can be retrieved for the registered KAS under the `remote` key, such as `https:/
 
 The JSON value passed to the `--public-keys` flag stores the set of public keys for the KAS.
 
-The PEM value should contain everything `-----BEGIN CERTIFICATE-----\nMIIB...5Q=\n-----END CERTIFICATE-----\n`.
+1. The `"pem"` value should contain the entire certificate `-----BEGIN CERTIFICATE-----\nMIIB...5Q=\n-----END CERTIFICATE-----\n`.
+
+2. The `"kid"` value is a named key identifier, which is useful for key rotations.
+
+3. The `"alg"` specifies the key algorithm:
+
+| Key Algorithm  | `alg` Value |
+| -------------- | ----------- |
+| `rsa:2048`     | 1           |
+| `ec:secp256r1` | 5           |
 
 ### Local
 

docs/man/policy/subject-mappings/create.md

@@ -1,5 +1,5 @@
 ---
-title: Create a new subject mapping 
+title: Create a new subject mapping
 command:
   name: create
   aliases:
@@ -11,30 +11,30 @@ command:
       description: The ID of the attribute value to map to a subject set
       shorthand: a
       required: true
-      default: ""
+      default: ''
     - name: action-standard
       description: The standard action to map to a subject set
       enum:
         - DECRYPT
         - TRANSMIT
       shorthand: s
       required: true
-      default: ""
+      default: ''
     - name: action-custom
       description: The custom action to map to a subject set
       shorthand: c
       required: false
-      default: ""
+      default: ''
     - name: subject-condition-set-id
-      description: Known pre-existing Subject Condition Set Id
+      description: Known preexisting Subject Condition Set Id
       required: true
-      default: ""
+      default: ''
     - name: subject-condition-set-new
       description: JSON array of Subject Sets to create a new Subject Condition Set associated with the created Subject Mapping
       required: false
-      default: ""
+      default: ''
     - name: label
       description: "Optional metadata 'labels' in the format: key=value"
       shorthand: l
-      default: ""
----
+      default: ''
+---

docs/man/policy/subject-mappings/update.md

@@ -1,5 +1,5 @@
 ---
-title: Update a subject mapping 
+title: Update a subject mapping
 command:
   name: update
   aliases:
@@ -16,20 +16,20 @@ command:
         - TRANSMIT
       shorthand: s
       required: true
-      default: ""
+      default: ''
     - name: action-custom
       description: The custom action to map to a subject set
       shorthand: c
       required: false
-      default: ""
+      default: ''
     - name: subject-condition-set-id
-      description: Known pre-existing Subject Condition Set Id
+      description: Known preexisting Subject Condition Set Id
       required: true
-      default: ""
+      default: ''
     - name: label
       description: "Optional metadata 'labels' in the format: key=value"
       shorthand: l
-      default: ""
+      default: ''
     - name: force-replace-labels
       description: Destructively replace entire set of existing metadata 'labels' with any provided to this command
       default: false