update duvet anotations

Author: seebees

modules/branch-keystore-node/src/branch_keystore.ts

@@ -279,10 +279,6 @@ export class BranchKeyStoreNode implements IBranchKeyStoreNode {
       'MUST supply a string branch key id'
     )
 
-    //= aws-encryption-sdk-specification/framework/branch-key-store.md#getactivebranchkey
-    //# To get the active version for the branch key id from the keystore
-    //# this operation MUST call AWS DDB `GetItem`
-    //# using the `branch-key-id` as the Partition Key and `"branch:ACTIVE"` value as the Sort Key.
     return await this._getBranchKeyMaterials(
       branchKeyId,
       BRANCH_KEY_ACTIVE_TYPE
@@ -307,9 +303,6 @@ export class BranchKeyStoreNode implements IBranchKeyStoreNode {
       'MUST supply a string branch key version'
     )
 
-    //= aws-encryption-sdk-specification/framework/branch-key-store.md#getbranchkeyversion
-    //# To get a branch key from the keystore this operation MUST call AWS DDB `GetItem`
-    //# using the `branch-key-id` as the Partition Key and "branch:version:" + `branchKeyVersion` value as the Sort Key.
     return await this._getBranchKeyMaterials(
       branchKeyId,
       BRANCH_KEY_TYPE_PREFIX + branchKeyVersion

modules/branch-keystore-node/src/branch_keystore_helpers.ts

@@ -88,23 +88,22 @@ export async function getBranchKeyItem(
  * if there are additional fields within the response item that
  * don't follow the proper custom encryption context key naming convention
  */
-//= aws-encryption-sdk-specification/framework/branch-key-store.md#getactivebranchkey
+//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedactivebranchkey
 //# The AWS DDB response MUST contain the fields defined in the [branch keystore record format](#record-format).
-//# If the record does not contain the defined fields, this operation MUST fail.
 export function validateBranchKeyRecord(item: BranchKeyItem): BranchKeyRecord {
-  //= aws-encryption-sdk-specification/framework/branch-key-store.md#record-format
+  //= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
   //# 1. `branch-key-id` : Unique identifier for a branch key; represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)
   needs(
     BRANCH_KEY_IDENTIFIER_FIELD in item &&
       typeof item[BRANCH_KEY_IDENTIFIER_FIELD] === 'string',
     `Branch keystore record does not contain a ${BRANCH_KEY_IDENTIFIER_FIELD} field of type string`
   )
 
-  //= aws-encryption-sdk-specification/framework/branch-key-store.md#record-format
+  //= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
   //# 1. `type` : One of the following; represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)
-  //#   - The string literal `"beacon:ACTIVE"`. Then `enc` is the wrapped beacon key.
-  //#   - The string `"branch:version:"` + `version`, where `version` is the Branch Key Version. Then `enc` is the wrapped branch key.
-  //#   - The string literal `"branch:ACTIVE"`. Then `enc` is the wrapped beacon key of the active version.
+  //#    - The string literal `"beacon:ACTIVE"`. Then `enc` is the wrapped beacon key.
+  //#    - The string `"branch:version:"` + `version`, where `version` is the Branch Key Version. Then `enc` is the wrapped branch key.
+  //#    - The string literal `"branch:ACTIVE"`. Then `enc` is the wrapped beacon key of the active version. Then
   needs(
     TYPE_FIELD in item &&
       typeof item[TYPE_FIELD] === 'string' &&
@@ -114,7 +113,7 @@ export function validateBranchKeyRecord(item: BranchKeyItem): BranchKeyRecord {
     `Branch keystore record does not contain a valid ${TYPE_FIELD} field of type string`
   )
 
-  //= aws-encryption-sdk-specification/framework/branch-key-store.md#record-format
+  //= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
   //# 1. `version` : Only exists if `type` is the string literal `"branch:ACTIVE"`.
   //#   Then it is the Branch Key Version. represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)
   if (item[TYPE_FIELD] === BRANCH_KEY_ACTIVE_TYPE) {
@@ -125,23 +124,23 @@ export function validateBranchKeyRecord(item: BranchKeyItem): BranchKeyRecord {
     )
   }
 
-  //= aws-encryption-sdk-specification/framework/branch-key-store.md#record-format
+  //= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
   //# 1. `enc` : Encrypted version of the key;
   //#   represented as [AWS DDB Binary](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)
   needs(
     BRANCH_KEY_FIELD in item && item[BRANCH_KEY_FIELD] instanceof Uint8Array,
     `Branch keystore record does not contain ${BRANCH_KEY_FIELD} field of type Uint8Array`
   )
 
-  //= aws-encryption-sdk-specification/framework/branch-key-store.md#record-format
+  //= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
   //# 1. `kms-arn`: The AWS KMS Key ARN used to generate the `enc` value.
   //#   represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)
   needs(
     KMS_FIELD in item && typeof item[KMS_FIELD] === 'string',
     `Branch keystore record does not contain ${KMS_FIELD} field of type string`
   )
 
-  //= aws-encryption-sdk-specification/framework/branch-key-store.md#record-format
+  //= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
   //# 1. `create-time`: Timestamp in ISO 8601 format in UTC, to microsecond precision.
   //#   Represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)
   needs(
@@ -150,7 +149,7 @@ export function validateBranchKeyRecord(item: BranchKeyItem): BranchKeyRecord {
     `Branch keystore record does not contain ${KEY_CREATE_TIME_FIELD} field of type string`
   )
 
-  //= aws-encryption-sdk-specification/framework/branch-key-store.md#record-format
+  //= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
   //# 1. `hierarchy-version`: Version of the hierarchical keyring;
   //#   represented as [AWS DDB Number](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)
   needs(
@@ -159,9 +158,9 @@ export function validateBranchKeyRecord(item: BranchKeyItem): BranchKeyRecord {
     `Branch keystore record does not contain ${HIERARCHY_VERSION_FIELD} field of type number`
   )
 
-  //= aws-encryption-sdk-specification/framework/branch-key-store.md#record-format
-  //# A branch key record MAY include [custom encryption context](#custom-encryption-context) key-value pairs.
-  //# These attributes should be prefixed with `aws-crypto-ec:` the same way they are for [AWS KMS encryption context](#encryption-context).
+  //= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
+  //# A branch key record MAY include [custom encryption context](../branch-key-store.md#custom-encryption-context) key-value pairs.
+  //# These attributes should be prefixed with `aws-crypto-ec:` the same way they are for [AWS KMS encryption context](../branch-key-store.md#encryption-context).
   for (const field in item) {
     if (!POTENTIAL_BRANCH_KEY_RECORD_FIELDS.includes(field)) {
       needs(
@@ -189,7 +188,7 @@ export function constructAuthenticatedEncryptionContext(
 ): EncryptionContext {
   //= aws-encryption-sdk-specification/framework/branch-key-store.md#encryption-context
   //# This section describes how the AWS KMS encryption context is built
-  //# from the DynamoDB items that store the branch keys.
+  //# from an [encrypted hierarchical key](./key-store/key-storage.md#encryptedhierarchicalkey).
 
   //# The following encryption context keys are shared:
 
@@ -203,8 +202,10 @@ export function constructAuthenticatedEncryptionContext(
   //# - MUST have a `hierarchy-version`
   //# - MUST NOT have a `enc` attribute
 
-  //# Any additionally attributes on the DynamoDB item
+  //# Any additionally attributes in the EncryptionContext
+  //# of the [encrypted hierarchical key](./key-store/key-storage.md#encryptedhierarchicalkey)
   //# MUST be added to the encryption context.
+  //# 
 
   // the encryption context is a string to string map, so serialize the branch
   // key record to this form

modules/branch-keystore-node/test/branch_keystore.test.ts

@@ -48,17 +48,6 @@ describe('Test Branch keystore', () => {
   describe('Test constructor', () => {
     const KMS_CONFIGURATION = new SrkCompatibilityKmsConfig(KEY_ARN)
 
-    //= aws-encryption-sdk-specification/framework/branch-key-store.md#initialization
-    //= type=test
-    //# The following inputs MAY be specified to create a KeyStore:
-    //# - [ID](#keystore-id)
-    //# - [AWS KMS Grant Tokens](#aws-kms-grant-tokens)
-    //# - [DynamoDb Client](#dynamodb-client)
-    //# - [KMS Client](#kms-client)
-    //# The following inputs MUST be specified to create a KeyStore:
-    //# - [Table Name](#table-name)
-    //# - [AWS KMS Configuration](#aws-kms-configuration)
-    //# - [Logical KeyStore Name](#logical-keystore-name)
     const BRANCH_KEYSTORE = new BranchKeyStoreNode({
       ddbTableName: DDB_TABLE_NAME,
       logicalKeyStoreName: LOGICAL_KEYSTORE_NAME,
@@ -306,21 +295,6 @@ describe('Test Branch keystore', () => {
       }
     })
 
-    //= aws-encryption-sdk-specification/framework/branch-key-store.md#dynamodb-client
-    //= type=test
-    //# The DynamoDb Client used to put and get keys from the backing DDB table.
-    //# If the AWS KMS Configuration is KMS Key ARN or KMS MRKey ARN,
-    //# and no DynamoDb Client is provided,
-    //# a new DynamoDb Client MUST be created
-    //# with the region of the supplied KMS ARN.
-    //# If the AWS KMS Configuration is Discovery,
-    //# and no DynamoDb Client is provided,
-    //# a new DynamoDb Client MUST be created
-    //# with the default configuration.
-    //# If the AWS KMS Configuration is MRDiscovery,
-    //# and no DynamoDb Client is provided,
-    //# a new DynamoDb Client MUST be created
-    //# with the region configured in the MRDiscovery.
     it('Postcondition: If unprovided, the DDB client is configured', async () => {
       for (const ddbClient of falseyValues) {
         const { ddbClient: client } = new BranchKeyStoreNode({
@@ -336,24 +310,6 @@ describe('Test Branch keystore', () => {
       }
     })
 
-    //= aws-encryption-sdk-specification/framework/branch-key-store.md#kms-client
-    //= type=test
-    //# The KMS Client used when wrapping and unwrapping keys.
-    //# If the AWS KMS Configuration is KMS Key ARN or KMS MRKey ARN,
-    //# and no KMS Client is provided,
-    //# a new KMS Client MUST be created
-    //# with the region of the supplied KMS ARN.
-    //# If the AWS KMS Configuration is Discovery,
-    //# and no KMS Client is provided,
-    //# a new KMS Client MUST be created
-    //# with the default configuration.
-    //# If the AWS KMS Configuration is MRDiscovery,
-    //# and no KMS Client is provided,
-    //# a new KMS Client MUST be created
-    //# with the region configured in the MRDiscovery.
-    //# On initialization the KeyStore SHOULD
-    //# append a user agent string to the AWS KMS SDK Client with
-    //# the value `aws-kms-hierarchy`.
     it('Postcondition: If unprovided, the KMS client is configured', async () => {
       for (const kmsClient of falseyValues) {
         const { kmsClient: client } = new BranchKeyStoreNode({