Merge branch 'main' into release-0.x

Author: aka-bo

CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the Asherah encryption SDK.
+
+## Project Overview
+Asherah is an application-layer encryption SDK providing envelope encryption with hierarchical key management, secure memory handling, and defense in depth against compromise. It supports multiple languages with pluggable KMS and metastore backends.
+
+## Build Commands
+- C#: `cd csharp/<Project> && ./scripts/build.sh` or `dotnet build`
+- Go: `cd go/<module> && ./scripts/build.sh` or `go build ./...`
+- Java: `cd java/<module> && ./scripts/build.sh` or `mvn compile`
+- Server: `cd server/<language> && ./scripts/build.sh`
+
+## Test Commands
+- Full test suites: `./scripts/test.sh` (in respective language directories)
+- Integration tests: `./scripts/integration_test.sh` (where available)
+- C# single test: `dotnet test --filter "FullyQualifiedName=Namespace.ClassName.MethodName"`
+- Go single test: `go test -run TestName ./path/to/package`
+- Java single test: `mvn -Dtest=TestClassName#methodName test`
+- Cross-language tests: `cd tests/cross-language && ./scripts/encrypt_all.sh && ./scripts/decrypt_all.sh`
+
+## Lint Commands
+- C#: `dotnet format` for formatting, built-in analyzers
+- Go: `./scripts/lint.sh` (installs and runs golangci-lint v1.59.0)
+- Java: Checkstyle via Maven (configured in pom.xml)
+
+## Environment Setup
+Common test environment variables:
+```bash
+export AWS_ACCESS_KEY_ID=dummykey
+export AWS_SECRET_ACCESS_KEY=dummysecret
+export AWS_DEFAULT_REGION=us-west-2
+export MYSQL_HOSTNAME=localhost
+export DYNAMODB_HOSTNAME=localhost
+```
+
+## Key Components
+- **AppEncryption**: Core encryption libraries (C#, Go, Java)
+- **SecureMemory**: Protected memory allocation (C#, Go, Java)
+- **Server**: gRPC service layer (Go, Java)
+- **Samples**: Reference implementations and AWS deployment examples
+
+## Testing Infrastructure
+- Uses TestContainers for integration testing (DynamoDB, MySQL)
+- Docker Compose files for local development (`samples/` directory)
+- Cross-language compatibility tests verify encrypt/decrypt operations work across all SDKs
+
+## Style Guidelines
+- C#: Microsoft guidelines, 120 char line limit, prefer method overloading over optional args
+- Go: Standard idioms, proper error handling with error propagation
+- Java: Google's style guide with Checkstyle enforcement
+
+## Security Patterns
+- Envelope encryption with hierarchical key model (System Key → Intermediate Key → Data Encryption Key)
+- Protected memory handling for sensitive data (off-heap, secure wiping)
+- Session-based encryption with partition isolation
+- KMS integration for root key management (AWS KMS, Static keys for testing)
+- Pluggable metastore backends (DynamoDB, RDBMS, In-Memory)

csharp/AppEncryption/AppEncryption.IntegrationTests/AppEncryption.IntegrationTests.csproj

@@ -9,18 +9,18 @@
         <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     </PropertyGroup>
     <ItemGroup Label="Package References">
-        <PackageReference Include="AWSSDK.SecurityToken" Version="4.0.1.6" />
+        <PackageReference Include="AWSSDK.SecurityToken" Version="4.0.2.1" />
         <PackageReference Include="coverlet.msbuild" Version="6.0.4">
           <PrivateAssets>all</PrivateAssets>
           <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
         </PackageReference>
         <PackageReference Include="MySql.Data" Version="9.4.0" />
         <PackageReference Include="NetEscapades.Configuration.Yaml" Version="3.1.0" />
-        <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.7" />
+        <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.8" />
         <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
         <PackageReference Include="Moq" Version="4.20.72" />
         <PackageReference Include="xunit" Version="2.9.3" />
-        <PackageReference Include="xunit.runner.visualstudio" Version="3.1.3">
+        <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4">
           <PrivateAssets>all</PrivateAssets>
           <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
         </PackageReference>

csharp/AppEncryption/AppEncryption.Tests/AppEncryption.Tests.csproj

@@ -9,23 +9,23 @@
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
   </PropertyGroup>
   <ItemGroup Label="Package References">
-    <PackageReference Include="AWSSDK.SecurityToken" Version="4.0.1.6" />
+    <PackageReference Include="AWSSDK.SecurityToken" Version="4.0.2.1" />
     <PackageReference Include="JunitXml.TestLogger" Version="6.1.0" />
     <PackageReference Include="coverlet.msbuild" Version="6.0.4">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.7" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.8" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
     <PackageReference Include="Moq" Version="4.20.72" />
     <PackageReference Include="MySql.Data" Version="9.4.0" />
     <PackageReference Include="System.Net.Http" Version="4.3.4" />
     <PackageReference Include="System.Net.Security" Version="4.3.2" />
     <PackageReference Include="System.Text.RegularExpressions" Version="4.3.1" />
-    <PackageReference Include="Testcontainers.DynamoDb" Version="4.6.0" />
-    <PackageReference Include="Testcontainers.MySql" Version="4.6.0" />
+    <PackageReference Include="Testcontainers.DynamoDb" Version="4.7.0" />
+    <PackageReference Include="Testcontainers.MySql" Version="4.7.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
-    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.3">
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>

csharp/AppEncryption/AppEncryption.Tests/AppEncryption/Persistence/DynamoDbMetastoreImplTest.cs

@@ -266,6 +266,23 @@ public void TestStoreWithSuffixSuccess()
             Assert.True(actualValue);
         }
 
+        [Fact]
+        public void TestStoreWithClientProvidedExternally()
+        {
+            var client = new AmazonDynamoDBClient(new AmazonDynamoDBConfig
+            {
+                ServiceURL = serviceUrl,
+                AuthenticationRegion = Region,
+            });
+
+            var dbMetastoreImpl = NewBuilder(Region)
+                .WithDynamoDbClient(client)
+                .Build();
+            bool actualValue = dbMetastoreImpl.Store(TestKey, DateTimeOffset.Now, JObject.FromObject(keyRecord));
+
+            Assert.True(actualValue);
+        }
+
         [Fact]
         public void TestStoreWithDbErrorShouldThrowException()
         {

csharp/AppEncryption/AppEncryption/AppEncryption.csproj

@@ -24,15 +24,15 @@
     <!-- End of Properties related to NuGet packaging: -->
   </PropertyGroup>
   <ItemGroup Label="Package References">
-    <PackageReference Include="AWSSDK.DynamoDBv2" Version="4.0.3.1" />
-    <PackageReference Include="AWSSDK.KeyManagementService" Version="4.0.3.9" />
+    <PackageReference Include="AWSSDK.DynamoDBv2" Version="4.0.6.1" />
+    <PackageReference Include="AWSSDK.KeyManagementService" Version="4.0.4.1" />
     <PackageReference Include="LanguageExt.Core" Version="4.4.9" />
-    <PackageReference Include="Microsoft.Extensions.Caching.Memory" Version="9.0.7" />
-    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="9.0.7" />
+    <PackageReference Include="Microsoft.Extensions.Caching.Memory" Version="9.0.8" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="9.0.8" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageReference Include="App.Metrics" Version="4.3.0" />
-    <PackageReference Include="System.Text.Encodings.Web" Version="9.0.7" />
-    <PackageReference Include="System.Text.Json" Version="9.0.7" />
+    <PackageReference Include="System.Text.Encodings.Web" Version="9.0.8" />
+    <PackageReference Include="System.Text.Json" Version="9.0.8" />
   </ItemGroup>
   <ItemGroup Label="Project References">
     <ProjectReference Include="../Crypto/Crypto.csproj" />

csharp/AppEncryption/AppEncryption/Persistence/DynamoDbMetastoreImpl.cs

@@ -43,6 +43,7 @@ public class DynamoDbMetastoreImpl : IMetastore<JObject>
         private readonly string preferredRegion;
         private readonly Table table;
 
+
         internal DynamoDbMetastoreImpl(Builder builder)
         {
             DbClient = builder.DbClient;
@@ -51,6 +52,7 @@ internal DynamoDbMetastoreImpl(Builder builder)
             hasKeySuffix = builder.HasKeySuffix;
             this._logger = builder.Logger;
 
+
             // Note this results in a network call. For now, cleaner than refactoring w/ thread-safe lazy loading
             table = builder.LoadTable(DbClient, TableName);
         }
@@ -83,6 +85,8 @@ public interface IBuildStep
 
             /// <summary>
             /// Adds Endpoint config to the AWS DynamoDb client.
+            /// Note: This method will be ignored if <see cref="WithRegion"/> has already been called.
+            /// The first method called between <see cref="WithRegion"/> and <see cref="WithEndPointConfiguration"/> takes precedence.
             /// </summary>
             ///
             /// <param name="endPoint">the service endpoint either with or without the protocol.</param>
@@ -93,6 +97,8 @@ public interface IBuildStep
             /// <summary>
             /// Specifies the region for the AWS DynamoDb client. If this is not specified, then the region from
             /// <see cref="DynamoDbMetastoreImpl.NewBuilder"/> is used.
+            /// Note: This method will be ignored if <see cref="WithEndPointConfiguration"/> has already been called.
+            /// The first method called between <see cref="WithRegion"/> and <see cref="WithEndPointConfiguration"/> takes precedence.
             /// </summary>
             ///
             /// <param name="region">The region for the DynamoDb client.</param>
@@ -107,6 +113,17 @@ public interface IBuildStep
             /// <returns>The current <see cref="IBuildStep"/> instance.</returns>
             IBuildStep WithLogger(ILogger logger);
 
+            /// <summary>
+            /// Provides a custom DynamoDB client. When this is used, the credentials, endpoint, and region
+            /// configurations will be ignored.
+            /// Note: This method completely bypasses all other client configuration methods.
+            /// This is the recommended approach, especially when using dependency injection frameworks.
+            /// </summary>
+            ///
+            /// <param name="client">The custom DynamoDB client to use.</param>
+            /// <returns>The current <see cref="IBuildStep"/> instance.</returns>
+            IBuildStep WithDynamoDbClient(IAmazonDynamoDB client);
+
             /// <summary>
             /// Builds the finalized <see cref="DynamoDbMetastoreImpl"/> with the parameters specified in the builder.
             /// </summary>
@@ -274,26 +291,31 @@ public string GetKeySuffix()
             return DefaultKeySuffix;
         }
 
+
+
         /// <summary>
         /// Builder class to create an instance of the <see cref="DynamoDbMetastoreImpl"/> class.
         /// </summary>
-        public class Builder : IBuildStep, IDisposable
+        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1001:TypesThatOwnDisposableFieldsShouldBeDisposable", Justification = "Builder intentionally should not manage client lifecycle")]
+        public class Builder : IBuildStep
         {
             private readonly string preferredRegion;
-            private AmazonDynamoDBClient dbClient;
+            private IAmazonDynamoDB dbClient;
             private bool hasKeySuffix;
             private string tableName = DefaultTableName;
             private AWSCredentials credentials;
             private ILogger _logger;
 
+
             // Internal properties for access
             internal string PreferredRegion => preferredRegion;
-            internal AmazonDynamoDBClient DbClient => dbClient;
+            internal IAmazonDynamoDB DbClient => dbClient;
             internal bool HasKeySuffix => hasKeySuffix;
             internal string TableName => tableName;
             internal AWSCredentials Credentials => credentials;
             internal ILogger Logger => _logger;
 
+
             private const string DefaultTableName = "EncryptionKey";
             private readonly AmazonDynamoDBConfig dbConfig = new AmazonDynamoDBConfig();
             private bool hasEndPoint;
@@ -366,6 +388,21 @@ public IBuildStep WithLogger(ILogger logger)
                 return this;
             }
 
+            /// <summary>
+            /// Provides a custom DynamoDB client. When this is used, the credentials, endpoint, and region
+            /// configurations will be ignored.
+            /// Note: This method completely bypasses all other client configuration methods.
+            /// This is the recommended approach, especially when using dependency injection frameworks.
+            /// </summary>
+            ///
+            /// <param name="client">The custom DynamoDB client to use.</param>
+            /// <returns>The current <see cref="IBuildStep"/> instance.</returns>
+            public IBuildStep WithDynamoDbClient(IAmazonDynamoDB client)
+            {
+                this.dbClient = client;
+                return this;
+            }
+
             /// <summary>
             /// Builds the finalized <see cref="DynamoDbMetastoreImpl"/> object with the parameters specified in the
             /// <see cref="Builder"/>.
@@ -374,12 +411,15 @@ public IBuildStep WithLogger(ILogger logger)
             /// <returns>The fully instantiated <see cref="DynamoDbMetastoreImpl"/> object.</returns>
             public DynamoDbMetastoreImpl Build()
             {
-                if (!hasEndPoint && !hasRegion)
+                if (dbClient == null)
                 {
-                    dbConfig.RegionEndpoint = RegionEndpoint.GetBySystemName(preferredRegion);
-                }
+                    if (!hasEndPoint && !hasRegion)
+                    {
+                        dbConfig.RegionEndpoint = RegionEndpoint.GetBySystemName(preferredRegion);
+                    }
 
-                dbClient = new AmazonDynamoDBClient(credentials, dbConfig);
+                    dbClient = new AmazonDynamoDBClient(credentials, dbConfig);
+                }
 
                 return new DynamoDbMetastoreImpl(this);
             }
@@ -392,26 +432,7 @@ internal virtual Table LoadTable(IAmazonDynamoDB client, string tableName)
                     .Build();
             }
 
-            /// <summary>
-            /// Disposes of the managed resources.
-            /// </summary>
-            public void Dispose()
-            {
-                Dispose(true);
-                GC.SuppressFinalize(this);
-            }
 
-            /// <summary>
-            /// Disposes of the managed resources.
-            /// </summary>
-            /// <param name="disposing">True if called from Dispose, false if called from finalizer.</param>
-            protected virtual void Dispose(bool disposing)
-            {
-                if (disposing)
-                {
-                    dbClient?.Dispose();
-                }
-            }
         }
     }
 }

csharp/AppEncryption/Crypto/Crypto.csproj

@@ -23,7 +23,7 @@
   <ItemGroup Label="Package References">
     <PackageReference Include="BouncyCastle.NetCore" Version="2.2.1" />
     <PackageReference Include="GoDaddy.Asherah.SecureMemory" Version="0.4.0" />
-    <PackageReference Include="System.Text.Encodings.Web" Version="9.0.7" />
-    <PackageReference Include="System.Text.Json" Version="9.0.7" />
+    <PackageReference Include="System.Text.Encodings.Web" Version="9.0.8" />
+    <PackageReference Include="System.Text.Json" Version="9.0.8" />
   </ItemGroup>
 </Project>

csharp/AppEncryption/Directory.Build.props

@@ -1,5 +1,5 @@
 <Project>
   <PropertyGroup>
-    <Version>0.7.0</Version>
+    <Version>0.8.0</Version>
   </PropertyGroup>
 </Project>

csharp/AppEncryption/README.md

@@ -95,9 +95,10 @@ build the metastore by calling the `Build` method.
  - **WithKeySuffix**: Specifies whether key suffix should be enabled for DynamoDB. **This is required to enable Global
  Tables**.
  - **WithTableName**: Specifies the name of the DynamoDb table.
- - **WithRegion**: Specifies the region for the AWS DynamoDb client.
- - **WithEndPointConfiguration**: Adds an EndPoint configuration to the AWS DynamoDb client.
+ - **WithRegion**: Specifies the region for the AWS DynamoDb client. *Will be ignored if WithEndPointConfiguration was called first*.
+ - **WithEndPointConfiguration**: Adds an EndPoint configuration to the AWS DynamoDb client. *Will be ignored if WithRegion was called first*.
  - **WithCredentials**: Specifies custom credentials for the AWS DynamoDb client.
+ - **WithDynamoDbClient**: **Recommended** - Provides a custom DynamoDB client. This method is preferred over letting the builder create the client, especially when using dependency injection frameworks. It gives you full control over client configuration and lifecycle management. *Completely bypasses all other client configuration methods*.
 
 Below is an example of a DynamoDB metastore that uses a Global Table named `TestTable`
 
@@ -112,6 +113,49 @@ IMetastore<JObject> dynamoDbMetastore = DynamoDbMetastoreImpl.NewBuilder("us-wes
       .Build();
 ```
 
+**Recommended: Using WithDynamoDbClient with Dependency Injection and AWSSDK.Extensions.NETCore.Setup**
+
+```c#
+// In your DI container setup (e.g., Startup.cs, Program.cs)
+services.AddDefaultAWSOptions(Configuration.GetAWSOptions());
+services.AddAWSService<IAmazonDynamoDB>();
+
+// In your service or controller
+public class AsherahHelper(IAmazonDynamoDB dynamoDbClient, AWSOptions awsOptions)
+{
+    public SessionFactory BuildSessionFactory()
+    {
+        var preferredRegion = awsOptions.Region.SystemName;
+        var metastore = DynamoDbMetastoreImpl.NewBuilder(preferredRegion)
+            .WithDynamoDbClient(dynamoDbClient)  // Use the injected client
+            .WithKeySuffix()
+            .WithTableName("TestTable")
+            .Build();
+
+        // continue building factory here
+    }
+}
+```
+
+**Alternative: Manual Client Configuration**
+
+```c#
+// Create a custom DynamoDB client with specific configuration
+var config = new AmazonDynamoDBConfig
+{
+    RegionEndpoint = Amazon.RegionEndpoint.USWest2,
+    Timeout = TimeSpan.FromSeconds(30)
+};
+var customClient = new AmazonDynamoDBClient(credentials, config);
+
+// Use the custom client in the metastore
+IMetastore<JObject> dynamoDbMetastore = DynamoDbMetastoreImpl.NewBuilder("us-west-2")
+    .WithDynamoDbClient(customClient)
+    .WithKeySuffix()
+    .WithTableName("TestTable")
+    .Build();
+```
+
 #### In-memory Metastore (FOR TESTING ONLY)
 
 ```c#