fix(docs): Update kas-registry docs with new shape. (#154)

1.) Update kas-registry docs to fit the new `key_management` way of
importing/creating key and connecting an attribute to a specific key.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: c-r33d

docs/components/policy/key_access_registry.md

@@ -5,43 +5,11 @@ The Key Access Server (KAS) Registry within the platform policy is a store of kn
 Within platform policy, a registered KAS instance has the following key attributes:
 
 1. **URI**: The location where the KAS is accessible. This must be unique among all KAS instances registered in the platform.
-2. **Public Key Location**:
-   1. **Remote**: A public key available at an endpoint, such as `https://kas-one.com/public_key`.
-   2. **Cached**: One or more public keys stored within the platform policy database (see the example below).
-
-These traits are essential for managing KAS Grants to attributes and their associated key splits in encryption and decryption processes.
-
-#### Cached Key Example
-
-```json5
-{
-  "cached": {
-    // One or more known public keys for the KAS
-    "keys": [
-      {
-        // x509 ASN.1 content in PEM format
-        "pem": "<your PEM certificate>",
-        // key identifier 
-        "kid": "<your key id>",
-        // key algorithm (see below)
-        "alg": 1
-      }
-    ]
-  }
-}
-```
-
-1. The `"pem"` field should contain the full certificate, for example:
-   `-----BEGIN CERTIFICATE-----
-MIIB...5Q=
------END CERTIFICATE-----
-`.
-
-2. The `"kid"` field represents the key identifier, which is primarily used for key rotation.
-
-3. The `"alg"` field specifies the key algorithm used:
-
-| Key Algorithm     | `alg` Value |
-| ----------------- | ----------- |
-| `rsa:2048`        | 1           |
-| `ec:secp256r1`    | 5           |
+2. **Source Type**: Indicates whether the KAS is managed by the organization or imported from an external party. (Defaults to unspecified)
+3. **Name**: A friendly name for the registered KAS. (Optional)
+
+:::important
+**PublicKey** is deprecated and no longer used as of `v0.7.0` of service. Instead, import public keys with [key management](./keymanagement/quickstart.md).
+The ability to assign grants was deprecated in [v0.7.0 of service](https://github.com/opentdf/platform/releases/tag/service%2Fv0.7.0),
+in favor of [key mappings](./keymanagement/key_mappings.md).
+:::

specs/authorization/v2/authorization.openapi.yaml

@@ -245,6 +245,20 @@ components:
           title: token
           required:
             - token
+        - properties:
+            withRequestToken:
+              title: with_request_token
+              description: |+
+                derive the entity from the request's authorization access token JWT, rather than passing in the body
+                with_request_token must be true when set:
+                ```
+                this == true
+                ```
+
+              $ref: '#/components/schemas/google.protobuf.BoolValue'
+          title: with_request_token
+          required:
+            - withRequestToken
       title: EntityIdentifier
       additionalProperties: false
       description: |-

specs/policy/actions/actions.openapi.yaml

@@ -491,6 +491,23 @@ components:
       required:
         - rule
       additionalProperties: false
+    policy.Certificate:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+          description: generated uuid in database
+        pem:
+          type: string
+          title: pem
+          description: PEM format certificate
+        metadata:
+          title: metadata
+          description: Optional metadata.
+          $ref: '#/components/schemas/common.Metadata'
+      title: Certificate
+      additionalProperties: false
     policy.Condition:
       type: object
       properties:
@@ -603,7 +620,7 @@ components:
 
         publicKey:
           title: public_key
-          description: Deprecated
+          description: 'Deprecated: KAS can have multiple key pairs'
           $ref: '#/components/schemas/policy.PublicKey'
         sourceType:
           title: source_type
@@ -663,6 +680,12 @@ components:
             $ref: '#/components/schemas/policy.SimpleKasKey'
           title: kas_keys
           description: Keys for the namespace
+        rootCerts:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Certificate'
+          title: root_certs
+          description: Root certificates for chain of trust
       title: Namespace
       additionalProperties: false
     policy.Obligation:

specs/policy/attributes/attributes.openapi.yaml

@@ -135,30 +135,6 @@ paths:
             description: |-
               Required
                Fully Qualified Names of attribute values (i.e. https://<namespace>/attr/<attribute_name>/value/<value_name>), normalized to lower case.
-        - name: withValue.withKeyAccessGrants
-          in: query
-          description: Deprecated
-          schema:
-            type: boolean
-            title: with_key_access_grants
-            description: Deprecated
-        - name: withValue.withSubjectMaps
-          in: query
-          schema:
-            type: boolean
-            title: with_subject_maps
-        - name: withValue.withResourceMaps
-          in: query
-          schema:
-            type: boolean
-            title: with_resource_maps
-        - name: withValue.withAttribute.withKeyAccessGrants
-          in: query
-          description: Deprecated
-          schema:
-            type: boolean
-            title: with_key_access_grants
-            description: Deprecated
       responses:
         default:
           description: Error
@@ -426,10 +402,7 @@ paths:
       tags:
         - policy.attributes.AttributesService
       summary: AssignKeyAccessServerToAttribute
-      description: |-
-        --------------------------------------*
-         Attribute <> Key Access Server RPCs
-        ---------------------------------------
+      description: 'Deprecated: utilize AssignPublicKeyToAttribute'
       operationId: policy.attributes.AttributesService.AssignKeyAccessServerToAttribute
       parameters:
         - name: Connect-Protocol-Version
@@ -466,6 +439,7 @@ paths:
       tags:
         - policy.attributes.AttributesService
       summary: RemoveKeyAccessServerFromAttribute
+      description: 'Deprecated: utilize RemovePublicKeyFromAttribute'
       operationId: policy.attributes.AttributesService.RemoveKeyAccessServerFromAttribute
       parameters:
         - name: Connect-Protocol-Version
@@ -502,6 +476,7 @@ paths:
       tags:
         - policy.attributes.AttributesService
       summary: AssignKeyAccessServerToValue
+      description: 'Deprecated: utilize AssignPublicKeyToValue'
       operationId: policy.attributes.AttributesService.AssignKeyAccessServerToValue
       parameters:
         - name: Connect-Protocol-Version
@@ -538,6 +513,7 @@ paths:
       tags:
         - policy.attributes.AttributesService
       summary: RemoveKeyAccessServerFromValue
+      description: 'Deprecated: utilize RemovePublicKeyFromValue'
       operationId: policy.attributes.AttributesService.RemoveKeyAccessServerFromValue
       parameters:
         - name: Connect-Protocol-Version
@@ -1032,39 +1008,22 @@ components:
       required:
         - rule
       additionalProperties: false
-    policy.AttributeValueSelector:
+    policy.Certificate:
       type: object
       properties:
-        withKeyAccessGrants:
-          type: boolean
-          title: with_key_access_grants
-          description: Deprecated
-        withSubjectMaps:
-          type: boolean
-          title: with_subject_maps
-        withResourceMaps:
-          type: boolean
-          title: with_resource_maps
-        withAttribute:
-          title: with_attribute
-          $ref: '#/components/schemas/policy.AttributeValueSelector.AttributeSelector'
-      title: AttributeValueSelector
-      additionalProperties: false
-    policy.AttributeValueSelector.AttributeSelector:
-      type: object
-      properties:
-        withKeyAccessGrants:
-          type: boolean
-          title: with_key_access_grants
-          description: Deprecated
-        withNamespace:
-          title: with_namespace
-          $ref: '#/components/schemas/policy.AttributeValueSelector.AttributeSelector.NamespaceSelector'
-      title: AttributeSelector
-      additionalProperties: false
-    policy.AttributeValueSelector.AttributeSelector.NamespaceSelector:
-      type: object
-      title: NamespaceSelector
+        id:
+          type: string
+          title: id
+          description: generated uuid in database
+        pem:
+          type: string
+          title: pem
+          description: PEM format certificate
+        metadata:
+          title: metadata
+          description: Optional metadata.
+          $ref: '#/components/schemas/common.Metadata'
+      title: Certificate
       additionalProperties: false
     policy.Condition:
       type: object
@@ -1178,7 +1137,7 @@ components:
 
         publicKey:
           title: public_key
-          description: Deprecated
+          description: 'Deprecated: KAS can have multiple key pairs'
           $ref: '#/components/schemas/policy.PublicKey'
         sourceType:
           title: source_type
@@ -1238,6 +1197,12 @@ components:
             $ref: '#/components/schemas/policy.SimpleKasKey'
           title: kas_keys
           description: Keys for the namespace
+        rootCerts:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Certificate'
+          title: root_certs
+          description: Root certificates for chain of trust
       title: Namespace
       additionalProperties: false
     policy.Obligation:
@@ -1617,6 +1582,7 @@ components:
           $ref: '#/components/schemas/policy.attributes.AttributeKeyAccessServer'
       title: AssignKeyAccessServerToAttributeRequest
       additionalProperties: false
+      description: 'Deprecated: utilize AssignPublicKeyToAttributeRequest'
     policy.attributes.AssignKeyAccessServerToAttributeResponse:
       type: object
       properties:
@@ -1634,6 +1600,7 @@ components:
           $ref: '#/components/schemas/policy.attributes.ValueKeyAccessServer'
       title: AssignKeyAccessServerToValueRequest
       additionalProperties: false
+      description: 'Deprecated: utilize AssignPublicKeyToValueRequest'
     policy.attributes.AssignKeyAccessServerToValueResponse:
       type: object
       properties:
@@ -1868,7 +1835,7 @@ components:
           type: string
           title: id
           format: uuid
-          description: Deprecated
+          description: 'Deprecated: utilize identifier'
           deprecated: true
       title: GetAttributeRequest
       additionalProperties: false
@@ -1917,7 +1884,7 @@ components:
           type: string
           title: id
           format: uuid
-          description: Deprecated
+          description: 'Deprecated: utilize identifier'
           deprecated: true
       title: GetAttributeValueRequest
       additionalProperties: false
@@ -1958,12 +1925,6 @@ components:
           description: |-
             Required
              Fully Qualified Names of attribute values (i.e. https://<namespace>/attr/<attribute_name>/value/<value_name>), normalized to lower case.
-        withValue:
-          title: with_value
-          description: |-
-            Optional
-             This attribute value selector is not used currently, but left here for future use.
-          $ref: '#/components/schemas/policy.AttributeValueSelector'
       title: GetAttributeValuesByFqnsRequest
       additionalProperties: false
     policy.attributes.GetAttributeValuesByFqnsResponse:
@@ -2076,6 +2037,7 @@ components:
           $ref: '#/components/schemas/policy.attributes.AttributeKeyAccessServer'
       title: RemoveKeyAccessServerFromAttributeRequest
       additionalProperties: false
+      description: 'Deprecated: utilize RemovePublicKeyFromAttributeRequest'
     policy.attributes.RemoveKeyAccessServerFromAttributeResponse:
       type: object
       properties:
@@ -2093,6 +2055,7 @@ components:
           $ref: '#/components/schemas/policy.attributes.ValueKeyAccessServer'
       title: RemoveKeyAccessServerFromValueRequest
       additionalProperties: false
+      description: 'Deprecated: utilize RemovePublicKeyFromValueRequest'
     policy.attributes.RemoveKeyAccessServerFromValueResponse:
       type: object
       properties:

specs/policy/kasregistry/key_access_server_registry.openapi.yaml

@@ -879,7 +879,7 @@ components:
 
         publicKey:
           title: public_key
-          description: Deprecated
+          description: 'Deprecated: KAS can have multiple key pairs'
           $ref: '#/components/schemas/policy.PublicKey'
         sourceType:
           title: source_type