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

[elizabethhealy]

No description provided.

[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.

[gemini-code-assist]

The extractPublicKeyPem function hardcodes the algorithm to 'RS256' when calling jose.importX509. This will cause it to fail when processing X.509 certificates that contain EC public keys, as the underlying key material will not match the expected RSA algorithm. This is a significant limitation, as a KAS might provide an EC certificate.

To fix this, you should avoid hardcoding the algorithm. One approach could be to attempt to import the certificate with different supported algorithms (e.g., 'RS256', 'ES256', 'ES384', 'ES512') in a try-catch block, similar to how extractEcCurveFromPublicKey determines the curve.

For example:

  if (certOrPem.includes('-----BEGIN CERTIFICATE-----')) {
    // The `jose.importX509` function requires an algorithm hint. We'll try common ones.
    const algorithmsToTry: AsymmetricSigningAlgorithm[] = ['RS256', 'ES256', 'ES384', 'ES512'];
    for (const alg of algorithmsToTry) {
      try {
        const cert = await importX509(certOrPem, alg, { extractable: true });
        return exportSPKI(cert);
      } catch {
        // Ignore errors and try the next algorithm.
      }
    }
    throw new ConfigurationError(
      'Could not extract public key from certificate. Unsupported algorithm?'
    );
  }

[gemini-code-assist]

The importPublicKeyPem function uses permissive upper-bound checks (<= 2048 and <= 4096) to categorize RSA keys. This logic incorrectly labels keys smaller than 2048 bits (e.g., 1024 bits) as rsa:2048 and allows their use. 1024-bit RSA keys are considered cryptographically weak and should be rejected according to modern security standards (e.g., NIST SP 800-57) and the library's own MIN_ASYMMETRIC_KEY_SIZE_BITS constant. Additionally, keys between 2048 and 4096 bits (e.g., 3072 bits) are incorrectly labeled as rsa:4096.

Recommendation: Enforce a minimum key size of 2048 bits and use exact matches or stricter ranges for categorization.

[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