feat(sdk): Add obligations support.

[c-r33d]

Caution

DO NOT MERGE

Need Authorization changes from service to be merged first

Proposed Changes

1.) Expose Obligations function to TDF/NanoTDF
2.) Expose new NanoTDFReader with LoadNanoTDF,Init functions
3.) Within Obligations function allow consumers to retrieve Obligations on-demand by calling AuthService
4.) Refactor bulk to allow consumers to retrieve Obligations before decrypting content
5.) Expose PrepareBulkDecrypt to retrieve Obligations before decrypting the content

Manual E2E tests:

• Ran benchmark and rt tests for bulk
• Nano/ZTDF no access to resource regardless of obligations (returns empty slice of FQNs)
• Nano/ZTDF has access to resource, but does not fulfill obligations (returns required obligations)
• Nano/ZTDF has access to resource and fulfills obligations -> Decrypt successfully.
• Multi-KAS decrypt successful when able to fulfill obligations, failure with returned obligations when not

Caveats

Important

It's possible when making multiple reqs to different KAS's for the same policy,
if the last policy result for a specific KAS fails with a 500, the previous
obligations are cleared from the reader object.

This should be ok, since we allow customers to retrieve obligations on demand.

For bulk decryption, we do not allow on-demand obligation resolution.

Note

Bulk decrypt is designed in a way that will only allow
a global set of fulfillable obligations to be applied, not for
an individual TDF.

Important

We can not retrieve on-demand Obligations for NanoTDFs
where the policy is not plaintext.

Checklist

• I have added or updated unit tests
• I have added or updated integration tests (if appropriate)
• I have added or updated documentation

Testing Instructions

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	176.523015ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	96.097446ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	346.597111ms
Throughput	288.52 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	36.884418596s
Average Latency	366.437234ms
Throughput	135.56 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	25.935593065s
Average Latency	258.232913ms
Throughput	192.79 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	164.910864ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	100.533361ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	366.74801ms
Throughput	272.67 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	38.537614652s
Average Latency	383.697599ms
Throughput	129.74 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	27.101774045s
Average Latency	269.950583ms
Throughput	184.49 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	191.757217ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	104.768664ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	384.942807ms
Throughput	259.78 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	40.974875659s
Average Latency	408.355437ms
Throughput	122.03 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	28.54378908s
Average Latency	284.49637ms
Throughput	175.17 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	175.513914ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	98.70004ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	358.280632ms
Throughput	279.11 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	38.522988539s
Average Latency	383.371023ms
Throughput	129.79 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	26.858259201s
Average Latency	267.744349ms
Throughput	186.16 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	179.922629ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	99.626766ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	358.103853ms
Throughput	279.25 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	38.136281891s
Average Latency	379.16309ms
Throughput	131.11 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	26.813380545s
Average Latency	266.852995ms
Throughput	186.47 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	184.018078ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	101.96059ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	376.4141ms
Throughput	265.66 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	40.941153951s
Average Latency	407.859429ms
Throughput	122.13 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	28.30463278s
Average Latency	281.91763ms
Throughput	176.65 requests/second

[c-r33d]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant and valuable enhancements for handling obligations within the SDK. The refactoring of the bulk decryption process and the introduction of NanoTDFReader are excellent architectural improvements that increase the flexibility and usability of the library.

I've identified a few areas for improvement, including a critical issue related to variable shadowing, a high-severity issue concerning context propagation, and some medium-severity suggestions to enhance efficiency and maintainability. Addressing these points will further solidify the quality of this new feature.

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	184.411804ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	99.560378ms

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	381.223055ms
Throughput	262.31 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	43.406595544s
Average Latency	432.175959ms
Throughput	115.19 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	28.531769659s
Average Latency	284.529168ms
Throughput	175.24 requests/second