aws
diff --git a/‎modules/branch-keystore-node/package.json
+2 b/‎modules/branch-keystore-node/package.json
+2
diff --git a/‎modules/branch-keystore-node/src/branch_keystore.ts
+262 b/‎modules/branch-keystore-node/src/branch_keystore.ts
+262
@@ -20,6 +20,8 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@aws-crypto/kms-keyring": "file:.../kms-keyring",
+    "@aws-sdk/client-dynamodb": "^3.616.0",
+    "@aws-sdk/util-dynamodb": "^3.616.0",
     "tslib": "^2.2.0"
   },
   "sideEffects": false,
 
@@ -0,0 +1,262 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { KmsConfig, RegionalKmsConfig } from './kms_config'
+import { KMSClient } from '@aws-sdk/client-kms'
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
+import {
+  NodeBranchKeyMaterial,
+  immutableClass,
+  needs,
+  readOnlyProperty,
+} from '@aws-crypto/material-management'
+import { v4 } from 'uuid'
+import {
+  constructAuthenticatedEncryptionContext,
+  constructBranchKeyMaterials,
+  decryptBranchKey,
+  getBranchKeyItem,
+  validateBranchKeyRecord,
+} from './branch_keystore_helpers'
+import {
+  BRANCH_KEY_ACTIVE_TYPE,
+  BRANCH_KEY_TYPE_PREFIX,
+  KMS_CLIENT_USER_AGENT,
+} from './constants'
+
+//= aws-encryption-sdk-specification/framework/branch-key-store.md#initialization
+//# 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)
+export interface BranchKeyStoreNodeInput {
+  ddbTableName: string
+  logicalKeyStoreName: string
+  kmsConfiguration: KmsConfig
+  kmsClient?: KMSClient
+  ddbClient?: DynamoDBClient
+  keyStoreId?: string
+  grantTokens?: string[]
+}
+
+export interface IBranchKeyStoreNode {
+  ddbTableName: string
+  logicalKeyStoreName: string
+  kmsConfiguration: Readonly<KmsConfig>
+  kmsClient: KMSClient
+  ddbClient: DynamoDBClient
+  keyStoreId: string
+  grantTokens: ReadonlyArray<string>
+
+  getActiveBranchKey(branchKeyId: string): Promise<NodeBranchKeyMaterial>
+  getBranchKeyVersion(
+    branchKeyId: string,
+    branchKeyVersion: string
+  ): Promise<NodeBranchKeyMaterial>
+}
+
+export class BranchKeyStoreNode implements IBranchKeyStoreNode {
+  public declare ddbTableName: string
+  public declare logicalKeyStoreName: string
+  public declare kmsConfiguration: Readonly<KmsConfig>
+  public declare kmsClient: KMSClient
+  public declare ddbClient: DynamoDBClient
+  public declare keyStoreId: string
+  public declare grantTokens: ReadonlyArray<string>
+
+  constructor({
+    ddbTableName,
+    logicalKeyStoreName,
+    kmsConfiguration,
+    kmsClient,
+    ddbClient,
+    keyStoreId,
+    grantTokens,
+  }: BranchKeyStoreNodeInput) {
+    //= aws-encryption-sdk-specification/framework/branch-key-store.md#keystore-id
+    //# The Identifier for this KeyStore.
+    //# If one is not supplied, then a [version 4 UUID](https://www.ietf.org/rfc/rfc4122.txt) MUST be used.
+    readOnlyProperty(this, 'keyStoreId', keyStoreId ? keyStoreId : v4())
+
+    //= aws-encryption-sdk-specification/framework/branch-key-store.md#aws-kms-grant-tokens
+    //# A list of AWS KMS [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token).
+    readOnlyProperty(
+      this,
+      'grantTokens',
+      Object.freeze(grantTokens ? grantTokens : [])
+    )
+
+    needs(kmsConfiguration, 'AWS KMS Configuration required')
+    readOnlyProperty(this, 'kmsConfiguration', Object.freeze(kmsConfiguration))
+
+    //= aws-encryption-sdk-specification/framework/branch-key-store.md#dynamodb-client
+    //# 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.
+    // TODO: when other KMS configuration types/classes are supported for the keystore,
+    // verify the configuration object type to determine how we instantiate the
+    // DDB client. This will ensure safe type casting.
+    readOnlyProperty(
+      this,
+      'ddbClient',
+      ddbClient ||
+        new DynamoDBClient({
+          region: (this.kmsConfiguration as RegionalKmsConfig).getRegion(),
+        })
+    )
+
+    //= aws-encryption-sdk-specification/framework/branch-key-store.md#kms-client
+    //# 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`.
+    // TODO: when other KMS configuration types/classes are supported for the keystore,
+    // verify the configuration object type to determine how we instantiate the
+    // KMS client. This will ensure safe type casting.
+    readOnlyProperty(
+      this,
+      'kmsClient',
+      kmsClient ||
+        new KMSClient({
+          region: (this.kmsConfiguration as RegionalKmsConfig).getRegion(),
+          customUserAgent: KMS_CLIENT_USER_AGENT,
+        })
+    )
+
+    //= aws-encryption-sdk-specification/framework/branch-key-store.md#table-name
+    //# The table name of the DynamoDb table that backs this Keystore.
+    needs(ddbTableName, 'DynamoDb table name required')
+    readOnlyProperty(this, 'ddbTableName', ddbTableName)
+
+    //= aws-encryption-sdk-specification/framework/branch-key-store.md#logical-keystore-name
+    //# This name is cryptographically bound to all data stored in this table,
+    //# and logically separates data between different tables.
+
+    //# The logical keystore name MUST be bound to every created key.
+
+    //# There needs to be a one to one mapping between DynamoDB Table Names and the Logical KeyStore Name.
+    //# This value can be set to the DynamoDB table name itself, but does not need to.
+
+    //# Controlling this value independently enables restoring from DDB table backups
+    //# even when the table name after restoration is not exactly the same.
+    needs(logicalKeyStoreName, 'Logical Keystore name required')
+    readOnlyProperty(this, 'logicalKeyStoreName', logicalKeyStoreName)
+
+    // make this instance immutable
+    Object.freeze(this)
+  }
+
+  /**
+   * This is a utility method that encapsulates the overlapping logic for getActiveBranchKey
+   * and getBranchKeyVersion to retreive the branch key materials
+   * @param branchKeyId
+   * @param type - this could indicate an active or versioned request
+   * @returns branch key materials
+   */
+  private async _getBranchKeyMaterials(
+    branchKeyId: string,
+    type: string
+  ): Promise<NodeBranchKeyMaterial> {
+    // get the ddb response item using the partition & sort keys
+    const ddbBranchKeyItem = await getBranchKeyItem(this, branchKeyId, type)
+    // validate and form the branch key record
+    const ddbBranchKeyRecord = validateBranchKeyRecord(ddbBranchKeyItem)
+    // construct an encryption context from the record
+    const authenticatedEncryptionContext =
+      constructAuthenticatedEncryptionContext(this, ddbBranchKeyRecord)
+    // decrypt the encrypted branch key
+    const branchKey = await decryptBranchKey(
+      this,
+      ddbBranchKeyRecord,
+      authenticatedEncryptionContext
+    )
+    // construct branch key materials from the authenticated encryption context
+    const branchKeyMaterials = constructBranchKeyMaterials(
+      branchKey,
+      branchKeyId,
+      authenticatedEncryptionContext
+    )
+    return branchKeyMaterials
+  }
+
+  async getActiveBranchKey(
+    branchKeyId: string
+  ): Promise<NodeBranchKeyMaterial> {
+    //= aws-encryption-sdk-specification/framework/branch-key-store.md#getactivebranchkey
+    //# On invocation, the caller:
+
+    //# - MUST supply a `branch-key-id`
+    needs(branchKeyId, 'MUST supply a 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
+    )
+  }
+
+  async getBranchKeyVersion(
+    branchKeyId: string,
+    branchKeyVersion: string
+  ): Promise<NodeBranchKeyMaterial> {
+    //= aws-encryption-sdk-specification/framework/branch-key-store.md#getbranchkeyversion
+    //# On invocation, the caller:
+
+    //# - MUST supply a `branch-key-id`
+    //# - MUST supply a `branchKeyVersion`
+    needs(
+      branchKeyId && branchKeyVersion,
+      'MUST supply a branch key id and 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
+    )
+  }
+}
+
+immutableClass(BranchKeyStoreNode)