feat(sdk): Encapsulate all crypto in cryptoservice, make it pluggable

[elizabethhealy]

FEATURE BRANCH

This pull request introduces a pluggable cryptography service to the SDK, improving modularity, testability, and security. It encapsulates all crypto operations within a consistent interface, allowing for flexible integration of different cryptographic implementations and custom crypto backends.

Highlights

• Pluggable Crypto Service: Introduced a CryptoService interface for pluggable cryptography implementations, enhancing modularity and extensibility.
• Comprehensive Default Crypto Implementation: Implemented a default CryptoService using the Web Crypto API, supporting a wide range of cryptographic operations.
• Refactored JWT Handling: Refactored JWT signing and verification logic to leverage the new CryptoService, centralizing cryptographic primitives.
• Vendoring of jose utilities: Vendored specific jose utility functions for JWT claims and critical header validation to maintain consistent behavior.
• Enhanced Test Coverage: Added comprehensive unit tests for the new CryptoService methods and refactored JWT utility functions.

[gemini-code-assist]

Summary of Changes

Hello @elizabethhealy, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant architectural improvement by refactoring the cryptography layer into a pluggable service. This change enhances modularity, testability, and extensibility, allowing for flexible integration of different cryptographic implementations. The core library now centralizes all crypto operations, providing a consistent and secure foundation for future development.

Highlights

• Pluggable Crypto Service: All cryptography operations are now encapsulated within a new CryptoService interface, making the implementation pluggable. This allows for custom crypto backends, such as FIPS-compliant modules, to be injected into the OpenTDF and TDF3Client.
• Comprehensive Default Crypto Implementation: A robust default CryptoService has been implemented using the Web Crypto API, supporting a wide range of operations including asymmetric (RSA, ECDSA) and symmetric (HMAC) signing and verification, ECDH key derivation, various hashing algorithms, and key format conversions (PEM, JWK).
• Refactored JWT Handling: JWT signing and verification logic has been refactored to leverage the new CryptoService, centralizing cryptographic primitives and replacing direct calls to the jose library for core crypto operations. Specific jose utility functions for JWT claims and critical header validation have been vendored to maintain consistent behavior.
• Enhanced Test Coverage: Extensive unit tests have been added for the new CryptoService methods and the refactored JWT utility functions, ensuring the correctness and security of the cryptographic operations.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• lib/.prettierignore
  • Updated Prettier ignore configuration.
• lib/package-lock.json
  • Pinned jose dependency version.
• lib/package.json
  • Updated build scripts and pinned jose dependency.
• lib/scripts/vendor-jose-jwt-helpers.cjs
  • Added a new script to vendor specific jose JWT helper files.
• lib/src/opentdf.ts
  • Introduced a pluggable CryptoService to the OpenTDF class and its options.
• lib/tdf3/index.ts
  • Exported new cryptography-related types.
• lib/tdf3/src/crypto/declarations.ts
  • Expanded the CryptoService interface and added new type declarations for various cryptographic operations.
• lib/tdf3/src/crypto/index.ts
  • Implemented a comprehensive set of cryptographic functions for the default CryptoService using Web Crypto API and jose utilities.
• lib/tdf3/src/crypto/jose/jwt-claims-set.ts
  • Added a typed wrapper for the vendored jose JWT claims set validation.
• lib/tdf3/src/crypto/jose/validate-crit.ts
  • Added a typed wrapper for the vendored jose critical header parameter validation.
• lib/tdf3/src/crypto/jose/vendor/lib/buffer_utils.ts
  • Vendored jose buffer utility functions.
• lib/tdf3/src/crypto/jose/vendor/lib/epoch.ts
  • Vendored jose epoch utility function.
• lib/tdf3/src/crypto/jose/vendor/lib/is_object.ts
  • Vendored jose object type checking utility.
• lib/tdf3/src/crypto/jose/vendor/lib/jwt_claims_set.ts
  • Vendored jose JWT claims set validation logic.
• lib/tdf3/src/crypto/jose/vendor/lib/secs.ts
  • Vendored jose duration parsing utility.
• lib/tdf3/src/crypto/jose/vendor/lib/validate_crit.ts
  • Vendored jose critical header parameter validation logic.
• lib/tdf3/src/crypto/jose/vendor/util/errors.ts
  • Vendored jose custom error classes.
• lib/tdf3/src/crypto/jwt.ts
  • Added new JWT utility functions that leverage the CryptoService.
• lib/tests/mocha/unit/crypto-di.spec.ts
  • Updated mock CryptoService and added tests for OpenTDF's pluggable crypto service.
• lib/tests/mocha/unit/crypto/crypto-service.spec.ts
  • Added comprehensive unit tests for the newly implemented cryptographic functions in the default CryptoService.
• lib/tests/mocha/unit/jwt.spec.ts
  • Added new unit tests for the JWT utility functions, covering signing, verification, and claim validation.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/build-and-test.yaml

Activity

• No specific activity (comments, reviews, etc.) was provided in the pull request context.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly refactors cryptographic operations into a pluggable CryptoService, enhancing architectural flexibility and test coverage. However, a medium-severity vulnerability was identified in the RSA public key import logic, which incorrectly validates and accepts weak RSA keys (less than 2048 bits). Additionally, there is a high-severity finding concerning the extractPublicKeyPem implementation that could impact EC-based certificates.

[github-actions]

X-Test Results

opentdf-sdk-lib
opentdf-ctl
✅ go-main
✅ go-v0.9.0
✅ java-v0.9.0
✅ java-main
✅ js-v0.9.0
✅ js-main

[github-actions]

X-Test Results

opentdf-sdk-lib
opentdf-ctl
✅ go-main
✅ go-v0.9.0
✅ java-v0.9.0
✅ java-main
✅ js-v0.9.0
✅ js-main

[github-actions]

X-Test Failure Report

opentdf-ctl
opentdf-sdk-lib

[elizabethhealy]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a significant and valuable refactoring by encapsulating cryptographic operations within a pluggable CryptoService. This greatly improves the architecture by abstracting away the underlying crypto implementation. The changes are extensive, touching many parts of the SDK, and have been applied consistently for the most part.

I've identified a few areas for improvement:

• In the CLI, a validation for PEM-formatted keys is missing.
• A comment in the OIDC logic has become outdated due to the refactoring.
• The web-app's custom OIDC client contains complex workarounds to deal with the new opaque key types, which should be refactored to align with the new crypto architecture of the SDK.

Overall, this is a great step forward for the SDK's design. Addressing these points will further improve the quality and maintainability of the code.

_{Note: Security Review did not run due to the size of the PR.}

[elizabethhealy]

/gemini summary

[gemini-code-assist]

Summary of Changes

This pull request introduces a pluggable cryptography service to the SDK, improving modularity, testability, and security. It encapsulates all crypto operations within a consistent interface, allowing for flexible integration of different cryptographic implementations and custom crypto backends.

Highlights

• Pluggable Crypto Service: Introduced a CryptoService interface for pluggable cryptography implementations, enhancing modularity and extensibility.
• Comprehensive Default Crypto Implementation: Implemented a default CryptoService using the Web Crypto API, supporting a wide range of cryptographic operations.
• Refactored JWT Handling: Refactored JWT signing and verification logic to leverage the new CryptoService, centralizing cryptographic primitives.
• Vendoring of jose utilities: Vendored specific jose utility functions for JWT claims and critical header validation to maintain consistent behavior.
• Enhanced Test Coverage: Added comprehensive unit tests for the new CryptoService methods and refactored JWT utility functions.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• lib/.prettierignore
  • Added /tdf3/src/crypto/jose/vendor to .prettierignore.
• lib/package-lock.json
  • Removed dpop dependency and pinned jose dependency version.
• lib/package.json
  • Updated build scripts, added vendor:jose-jwt-helpers script, and pinned jose dependency.
• lib/scripts/vendor-jose-jwt-helpers.cjs
  • Added a new script to vendor specific jose JWT helper files.
• lib/src/access.ts
  • Removed ServiceError import and noteInvalidPublicKey function.
• lib/src/access/access-fetch.ts
  • Removed noteInvalidPublicKey and pemToCryptoPublicKey imports.
• lib/src/access/access-rpc.ts
  • Removed noteInvalidPublicKey and pemToCryptoPublicKey imports.
• lib/src/auth/auth.ts
  • Updated imports to use CryptoService, KeyPair, PrivateKey from ../../tdf3/src/crypto/declarations.js and signJwt from ../../tdf3/src/crypto/jwt.js, and updated reqSignature and updateClientPublicKey functions to use these new types.
• lib/src/auth/dpop.ts
  • Added a new file implementing DPoP proof JWT generation using CryptoService.
• lib/src/auth/oidc-clientcredentials-provider.ts
  • Updated constructor and updateClientPublicKey to use CryptoService and KeyPair.
• lib/src/auth/oidc-externaljwt-provider.ts
  • Updated constructor and updateClientPublicKey to use CryptoService and KeyPair.
• lib/src/auth/oidc-refreshtoken-provider.ts
  • Updated constructor and updateClientPublicKey to use CryptoService and KeyPair.
• lib/src/auth/oidc.ts
  • Updated imports, constructor, userInfo and refreshTokenClaimsWithClientPubkeyIfNeeded functions to use CryptoService and KeyPair, and removed cryptoPublicToPem import.
• lib/src/auth/providers.ts
  • Updated clientSecretAuthProvider, externalAuthProvider, refreshAuthProvider, and clientAuthProvider functions to accept and pass CryptoService.
• lib/src/cli.ts
  • Updated imports and function signatures to use KeyPair instead of webcrypto.CryptoKeyPair and string instead of CryptoKey for assertion keys.
• lib/src/crypto/index.ts
  • Exported PEM formatting utilities from tdf3 and added more exports from pemPublicToCrypto.ts.
• lib/src/crypto/pemPublicToCrypto.ts
  • Exported OID constants and guessAlgorithmName, guessCurveName, and toJwsAlg functions.
• lib/src/opentdf.ts
  • Added cryptoService option to OpenTDFOptions and OpenTDF class, and updated constructor to use CryptoService for key generation.
• lib/tdf3/index.ts
  • Exported new cryptography-related types.
• lib/tdf3/src/assertions.ts
  • Updated hash, sign, and verify functions to use CryptoService, and updated AssertionKey type to include PrivateKey, PublicKey, and SymmetricKey.
• lib/tdf3/src/ciphers/aes-gcm-cipher.ts
  • Updated encrypt and decrypt functions to use SymmetricKey.
• lib/tdf3/src/ciphers/symmetric-cipher-base.ts
  • Updated generateKey, encrypt, and decrypt functions to use SymmetricKey.
• lib/tdf3/src/client/builders.ts
  • Updated DecryptKeyMiddleware type to use SymmetricKey.
• lib/tdf3/src/client/index.ts
  • Updated ClientConfig to use KeyPair, updated createSessionKeys function to use CryptoService and KeyPair, and updated resolveKasInfo function to use CryptoService.
• lib/tdf3/src/crypto/crypto-utils.ts
  • Updated isPemKeyPair and isCryptoKeyPair functions to accept PemKeyPair | CryptoKeyPair and removed unused toCryptoKeyPair function.
• lib/tdf3/src/crypto/declarations.ts
  • Added new type declarations for various cryptographic operations and updated CryptoService interface.
• lib/tdf3/src/crypto/index.ts
  • Implemented a comprehensive set of cryptographic functions for the default CryptoService using Web Crypto API and jose utilities.
• lib/tdf3/src/crypto/jose/jwt-claims-set.ts
  • Added a typed wrapper for the vendored jose JWT claims set validation.
• lib/tdf3/src/crypto/jose/validate-crit.ts
  • Added a typed wrapper for the vendored jose critical header parameter validation.
• lib/tdf3/src/crypto/jose/vendor/lib/buffer_utils.ts
  • Vendored jose buffer utility functions.
• lib/tdf3/src/crypto/jose/vendor/lib/epoch.ts
  • Vendored jose epoch utility function.
• lib/tdf3/src/crypto/jose/vendor/lib/is_object.ts
  • Vendored jose object type checking utility.
• lib/tdf3/src/crypto/jose/vendor/lib/jwt_claims_set.ts
  • Vendored jose JWT claims set validation logic.
• lib/tdf3/src/crypto/jose/vendor/lib/secs.ts
  • Vendored jose duration parsing utility.
• lib/tdf3/src/crypto/jose/vendor/lib/validate_crit.ts
  • Vendored jose critical header parameter validation logic.
• lib/tdf3/src/crypto/jose/vendor/util/errors.ts
  • Vendored jose custom error classes.
• lib/tdf3/src/crypto/jwt.ts
  • Added new JWT utility functions that leverage the CryptoService.
• lib/tdf3/src/models/encryption-information.ts
  • Updated encrypt and decrypt functions to use SymmetricKey.
• lib/tdf3/src/models/key-access.ts
  • Updated ECWrapped and Wrapped classes to use CryptoService and opaque keys.
• lib/tdf3/src/salt.ts
  • Updated ztdfSalt to use CryptoService for salt generation.
• lib/tests/mocha/unit/assertions.spec.ts
  • Updated tests to use CryptoService and opaque keys.
• lib/tests/mocha/unit/crypto-di.spec.ts
  • Added comprehensive unit tests for the newly implemented cryptographic functions in the default CryptoService.
• lib/tests/mocha/unit/jwt.spec.ts
  • Added new unit tests for the JWT utility functions, covering signing, verification, and claim validation.
• lib/tests/mocha/unit/keysplits.spec.ts
  • Updated tests to use CryptoService and opaque keys.
• lib/tests/mocha/unit/tdf.spec.ts
  • Updated tests to use CryptoService and opaque keys.
• web-app/src/session.ts
  • Updated OidcClient class to use KeyPair and WebCryptoService and removed direct dependency on dpop.

Activity

• The pull request includes test results from opentdf-sdk-lib, opentdf-ctl, go-main, go-v0.9.0, java-v0.9.0, java-main, js-v0.9.0, and js-main.
• There was a failure report for opentdf-ctl and opentdf-sdk-lib on March 6, 2026.
• elizabethhealy requested a code review and summary from Gemini Code Assist.

[github-actions]

X-Test Results

✅ js-main
✅ js-v0.9.0
✅ java-main
✅ java-v0.9.0
✅ go-main
✅ go-v0.9.0
opentdf-ctl
opentdf-sdk-lib

[github-actions]

X-Test Results

✅ js-main
✅ js-v0.9.0
✅ java-main
✅ go-main
✅ java-v0.9.0
✅ go-v0.9.0
opentdf-ctl
opentdf-sdk-lib

[elizabethhealy]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a significant refactoring of the cryptography layer, moving from direct jose and WebCrypto API usage to a new CryptoService abstraction. This change allows for dependency injection of cryptographic implementations, enhancing flexibility and testability. Key changes include replacing CryptoKey with opaque KeyPair and SymmetricKey types, vendoring jose JWT helper functions and the dpop library to use the new CryptoService interface, and updating all related modules (CLI, access, authentication providers, TDF3 client, assertions, ciphers, and key access models) to adopt the new crypto abstraction. The KasPublicKeyInfo structure is simplified by removing the key property, and the OpenTDF constructor now accepts an optional cryptoService parameter, defaulting to a native browser implementation. Additionally, a test file contains duplicated test cases for OpenTDF crypto service initialization that should be removed for maintainability.

_{Note: Security Review did not run due to the size of the PR.}

[github-actions]

X-Test Results

✅ js-main
✅ js-v0.9.0
✅ java-main
✅ go-main
✅ java-v0.9.0
✅ go-v0.9.0
opentdf-ctl
opentdf-sdk-lib

[github-actions]

X-Test Results

✅ js-main
✅ js-v0.9.0
✅ java-main
✅ go-main
✅ java-v0.9.0
✅ go-v0.9.0
opentdf-ctl
opentdf-sdk-lib

[eugenioenko]

This looks fantastic! 🔥

Thank you @elizabethhealy for putting the stacked PR for review this mega feature, extremely helpful.