From e7a1deacc1c14626003db39508c103b1bd67df67 Mon Sep 17 00:00:00 2001 From: Chris Reed Date: Mon, 16 Jun 2025 10:33:14 -0500 Subject: [PATCH 1/5] adr(docs): Decision around 2.0.5 sdk compatibility. --- .../2025-06-16-expected-use-cases-sdk-205.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 adr/decisions/2025-06-16-expected-use-cases-sdk-205.md diff --git a/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md new file mode 100644 index 0000000000..7bde650854 --- /dev/null +++ b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md @@ -0,0 +1,37 @@ +--- +# Required +status: 'accepted' +date: '2025-06-16' +tags: + - sdk:v2.0.5 + - key management +# Optional +driver: '@strantalis @jrschumacher @c-r33d @damorris25' +deciders: '@strantalis @jrschumacher @c-r33d @damorris25' +consulted: '@strantalis @jrschumacher @c-r33d @damorris25' +informed: '@strantalis @jrschumacher @c-r33d @damorris25' +--- +# SDK backwards/forward compatibility v2.0.5 + +## Decision Outcome + +1. v2.0.5 of SDK should work with < v2.0.4 of platform +2. < v2.0.5 of SDK should work with >= v2.0.5 of plaform +3. We should not have a WithBaseKeyEnabled option, instead the platform version should be derived from the well-known. +4. After an admin has created their first key-mapping the SDK will **only** use mappings and not any previous grants. + + +### Consequences + +- 🟩 **Good**, maintains backwards/forward compatibility +- 🟩 **Good**, allows us to not add another TDFOption +- 🟨 **Neutral**: Wellknown needs to be updated with platform version information. +- 🟨 **Neutral**: After an admin creates their first key mapping the SDK will ignore previously created grants. + + +## Validation + +- **Unit Tests:** SDK conditions for no base key functionality based on platform version +- **Integration Tests:** Mix of tests using new and old platform/sdk. *Should be covered in existing XTests* +- **Manual Testing:** Deploy different versions of the SDK/Platform. +- **Documentation:** Update SDK and platform documentation to reflect the new configuration option and its usage. From 90ad57f582209507b1b61fa3ddf80e6b36b714cb Mon Sep 17 00:00:00 2001 From: Chris Reed Date: Mon, 16 Jun 2025 11:14:47 -0500 Subject: [PATCH 2/5] rewrite. --- adr/decisions/2025-06-16-expected-use-cases-sdk-205.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md index 7bde650854..e916f82d3c 100644 --- a/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md +++ b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md @@ -18,7 +18,7 @@ informed: '@strantalis @jrschumacher @c-r33d @damorris25' 1. v2.0.5 of SDK should work with < v2.0.4 of platform 2. < v2.0.5 of SDK should work with >= v2.0.5 of plaform 3. We should not have a WithBaseKeyEnabled option, instead the platform version should be derived from the well-known. -4. After an admin has created their first key-mapping the SDK will **only** use mappings and not any previous grants. +4. When creating a split plan if the SDK notices that there are key mappings it will **only** use those key mappings instead of grants. If no key mappings are present, the sdk will fallback to grants. ### Consequences From 358feec4d4e24af1909bfe3c94be1af125bcb0f3 Mon Sep 17 00:00:00 2001 From: Chris Reed Date: Mon, 16 Jun 2025 11:18:47 -0500 Subject: [PATCH 3/5] rewrite. --- adr/decisions/2025-06-16-expected-use-cases-sdk-205.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md index e916f82d3c..3b6a3ada29 100644 --- a/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md +++ b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md @@ -17,7 +17,7 @@ informed: '@strantalis @jrschumacher @c-r33d @damorris25' 1. v2.0.5 of SDK should work with < v2.0.4 of platform 2. < v2.0.5 of SDK should work with >= v2.0.5 of plaform -3. We should not have a WithBaseKeyEnabled option, instead the platform version should be derived from the well-known. +3. We should not have a WithBaseKeyEnabled option, instead the platform version should be derived from the well-known. For v2.0.5 of the SDK we will attempt to infer the version of the platform by whether or not the base key key/value is apart of the json object. If it is not, we will fallback to using the default kases. 4. When creating a split plan if the SDK notices that there are key mappings it will **only** use those key mappings instead of grants. If no key mappings are present, the sdk will fallback to grants. From 196527973e4b955328dbd95bdfd6656374e904a6 Mon Sep 17 00:00:00 2001 From: Chris Reed Date: Mon, 16 Jun 2025 13:34:41 -0500 Subject: [PATCH 4/5] update. --- adr/decisions/2025-06-16-expected-use-cases-sdk-205.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md index 3b6a3ada29..b583c306de 100644 --- a/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md +++ b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md @@ -17,7 +17,7 @@ informed: '@strantalis @jrschumacher @c-r33d @damorris25' 1. v2.0.5 of SDK should work with < v2.0.4 of platform 2. < v2.0.5 of SDK should work with >= v2.0.5 of plaform -3. We should not have a WithBaseKeyEnabled option, instead the platform version should be derived from the well-known. For v2.0.5 of the SDK we will attempt to infer the version of the platform by whether or not the base key key/value is apart of the json object. If it is not, we will fallback to using the default kases. +3. We should not have a WithBaseKeyEnabled option, instead the platform version should be derived from the well-known. For v2.0.5 of the SDK we will prefer to use the base key if present and set properly. If it is not, we will fallback to using the default kases. 4. When creating a split plan if the SDK notices that there are key mappings it will **only** use those key mappings instead of grants. If no key mappings are present, the sdk will fallback to grants. From cfb6ff95c24eb93510750c4882166319e03c3711 Mon Sep 17 00:00:00 2001 From: Chris Reed Date: Mon, 16 Jun 2025 13:57:45 -0500 Subject: [PATCH 5/5] update. --- adr/decisions/2025-06-16-expected-use-cases-sdk-205.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md index b583c306de..81d015e14c 100644 --- a/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md +++ b/adr/decisions/2025-06-16-expected-use-cases-sdk-205.md @@ -17,7 +17,7 @@ informed: '@strantalis @jrschumacher @c-r33d @damorris25' 1. v2.0.5 of SDK should work with < v2.0.4 of platform 2. < v2.0.5 of SDK should work with >= v2.0.5 of plaform -3. We should not have a WithBaseKeyEnabled option, instead the platform version should be derived from the well-known. For v2.0.5 of the SDK we will prefer to use the base key if present and set properly. If it is not, we will fallback to using the default kases. +3. We should not have a WithBaseKeyEnabled option, instead the platform version should be derived from the well-known. For v2.0.5 of the SDK we will prefer to use the base key if present and set properly. If it is not, we will fallback to using the default kases. In v2.0.6 the plan would be to error if the platform is >= v2.0.5 and the base key is not set. 4. When creating a split plan if the SDK notices that there are key mappings it will **only** use those key mappings instead of grants. If no key mappings are present, the sdk will fallback to grants.