[dmihalcik-virtru]

What

Adds an optional, per-key AES-GCM encryptor to the CryptoService interface. The encryptor owns its IV construction: no IV goes in, and the IV only comes back as output.

interface CryptoService {
  // ...existing members
  createAesGcmEncryptor?: (key: SymmetricKey) => Promise<AesGcmEncryptor>;
}

type AesGcmEncryptor = {
  readonly ivConstruction: 'deterministic' | 'rbg'; // NIST SP 800-38D §8.2.1 or §8.2.2
  readonly invocationLimit: number;                 // hard ceiling per encryptor, counting attempts
  readonly encrypt: (plaintext: Uint8Array) => Promise<AesGcmEncryptResult>; // { readonly iv, ciphertext, tag }
};

• createAesGcmEncryptorFor(cryptoService, key) uses the provider's encryptor when the provider has one. Otherwise it builds §8.2.1 deterministic IVs through GcmIvCounter over the provider's own randomBytes and caller-IV encrypt: a random 8-byte fixed field drawn per encryptor, then a 4-byte big-endian counter, with an invocationLimit of 2^32.
• DefaultCryptoService deliberately does not implement createAesGcmEncryptor, and takes that fallback. If it did, a provider written as { ...DefaultCryptoService, encrypt: hsmEncrypt } would inherit an encryptor bound to the WebCrypto encrypt, and the SDK would prefer it, silently bypassing the override.
• guardAesGcmEncryptor wraps every encryptor:
  • it reads ivConstruction and invocationLimit once, and rejects an unknown construction or a limit that is not an integer from 1 to 2^32;
  • it counts attempts before calling down, failed and concurrent ones included, and throws the new IvExhaustionError at the limit;
  • it checks that each result has a 12-byte IV, a 16-byte tag, and ciphertext the same length as the plaintext, all as Uint8Arrays;
  • it copies the IV and tag, so a provider that reuses its buffers cannot change them after the check.
• New public types: AesGcmEncryptor, AesGcmEncryptResult and AesGcmIvConstruction from tdf3; IvExhaustionError from the package root.
• The AES-GCM constants live in a new import-free module, ciphers/aes-gcm-limits.ts, so sizing code later in the series can use them without an import cycle.
• The design note is in spec/DSPX-4496.md.

The writer doesn't use any of this yet. #1018 routes encryption through it, so this PR changes nothing at runtime.

Why

The DSPX-4492 ADR allows both §8.2.1 deterministic and §8.2.2 RBG IVs. FIPS 140-3 IG C.H ties approved AES-GCM encryption to IVs generated inside the module, and deterministic counter state is security-relevant state. If the SDK builds the IV and passes it in, the IV comes from outside the module.

Making the IV an output of a per-key encryptor lets any provider keep the whole construction inside its boundary. The SDK only looks at what the encryptor reports; it never needs to know which provider it has. SP 800-38D §8.3 caps RBG-based IVs at 2^32 invocations per key; per the ADR, providers using random IVs should report invocationLimit ≤ 2^26. The limit is enforced per encryptor, not across encryptors that share a key.

Open question for reviewers

ivConstruction: 'deterministic' | 'rbg' versus a boolean such as deterministicCounter or needsRbgIvs. See the spec.

How to test

cd lib && npm test. tests/mocha/unit/aes-gcm-encryptor.spec.ts and the GcmIvCounter tests in tdf.spec.ts cover:

• the default path's IV layout, and decrypting its output;
• a fresh fixed field for each encryptor;
• a provider spread from DefaultCryptoService keeping its encrypt and randomBytes overrides;
• splitting off a tag that a caller-IV service leaves inside the payload, and rejecting a service that returns no tag;
• an IV staying spent when the provider's encrypt fails;
• concurrent calls: distinct, consecutive IVs, and no overshooting the limit;
• the limit, including failed attempts, reading the limit only once, and invalid limits (NaN, Infinity, strings, undefined, out of range);
• rejecting malformed results, including a ciphertext with the tag still attached and a missing result;
• the guard being applied to the provider's encryptor;
• counter carry and the 2^32 ceiling.

Risk

This adds to the public crypto interface, so please review the API shape carefully. The runtime risk is nil until #1018.

DSPX-4496 series

Part	PR	Base	Depends on
1 of 6	#1059 reject non-positive segment sizes	main	merged
2 of 6	#1060 require 12-byte AES-GCM IVs	main	merged
3 of 6	#1061 calculate encrypted segment size	main	merged
4 of 6	#1062 default segment size 2 MiB	main	merged
5 of 6	#1063 AesGcmEncryptor SPI	main	—
6 of 6	#1018 writer IVs from the CryptoService encryptor	DSPX-4496-aes-gcm-encryptor	#1063

The large-file work (#1019 through #1024) is stacked on #1018. #1022 uses the payload encryptor's invocationLimit for its up-front byte ceiling.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

X-Test Results

✅ js@main-v0.9.0
✅ js@v0.4.0-v0.9.0
✅ js@pull-1063-main
✅ js@v0.4.0-main
✅ js@pull-1063-v0.9.0
✅ go@main-main
coverage-roundtrip-browser
✅ java@main-main
✅ java@main-v0.9.0
✅ js@main-main
✅ go@main-v0.9.0
coverage-web-app-browser
coverage-web-app
opentdf-sdk-lib
opentdf-ctl
coverage-lib

[github-actions]

X-Test Failure Report

coverage-web-app-browser
opentdf-ctl
coverage-web-app
opentdf-sdk-lib
coverage-lib

[github-actions]

X-Test Results

✅ java@main-main
✅ go@main-v0.9.0
✅ js@pull-1063-v0.9.0
coverage-roundtrip-browser
✅ js@v0.4.0-main
✅ js@main-main
✅ js@pull-1063-main
✅ js@main-v0.9.0
coverage-web-app-browser
opentdf-ctl
coverage-web-app
✅ java@main-v0.9.0
opentdf-sdk-lib
coverage-lib
✅ go@main-main
✅ js@v0.4.0-v0.9.0

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
99.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

X-Test Results

✅ js@pull-1063-v0.9.0
✅ js@main-v0.9.0
✅ go@main-v0.9.0
✅ java@main-v0.9.0
✅ js@pull-1063-main
✅ java@main-main
coverage-web-app
✅ js@main-main
✅ js@v0.4.0-main
opentdf-ctl
✅ go@main-main
coverage-web-app-browser
coverage-roundtrip-browser
opentdf-sdk-lib
coverage-lib
✅ js@v0.4.0-v0.9.0