fix(security): AES key/IV validation, SecureRandom.base64Url, GCM docs + tests

[tsavo-at-pieces]

Summary

• H1: AES key length validation — rejects keys that aren't 16/24/32 bytes (128/192/256-bit)
• H2: AES IV length validation — enforces 12-byte IV for GCM (NIST SP 800-38D), 16-byte IV for other modes
• H5: Added SecureRandom.base64Url getter for URL-safe random token generation
• GCM docs + tests: Added GCM to README supported modes list, added 5 GCM test cases (round-trip, AAD, wrong-AAD rejection, key sizes, IV uniqueness)

Test plan

• All 56 tests pass (dart test from package directory)
• GCM round-trip encrypt/decrypt
• GCM with associated data (AAD)
• GCM rejects wrong associated data on decrypt
• GCM supports 128, 192, and 256-bit keys
• Different IVs produce different ciphertexts

Closes #17
Closes #18

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Touches core cryptographic input validation and will now throw on previously-accepted key/IV sizes, which can break existing callers and requires careful compatibility review.

Overview
Adds runtime validation in AES to reject invalid key sizes (only 16/24/32 bytes) and to enforce correct IV lengths (12 bytes for AESMode.gcm, 16 bytes for other non-ECB modes) during encrypt/decrypt.

Extends SecureRandom with a base64Url getter for URL-safe tokens, updates README to document AESMode.gcm and mark AESMode.ecb as deprecated/insecure, and adds a dedicated AES GCM test suite covering round-trips, AAD, wrong-AAD failure, key sizes, and IV uniqueness.

^{Written by Cursor Bugbot for commit 6cc0a92. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

[cursor]

base64Url includes padding characters

Medium Severity

SecureRandom.base64Url uses convert.base64Url.encode, which emits padded Base64URL (often ending in =). For “URL-safe random token generation”, padding can still break usage in URL/path/query contexts unless callers remember to strip/encode it, so the getter’s behavior doesn’t match the implied guarantee.

 

[cursor]

New base64Url getter appears unused

Low Severity

The new SecureRandom.base64Url getter is not referenced anywhere in the repo (the only base64Url usage in tests refers to dart:convert’s top-level base64Url). This looks like dead API surface that increases maintenance cost without coverage proving it works as intended.

 

[sentry]

Bug: The new validation in aes.dart requires a 12-byte IV for GCM mode, but the example code in example/aes_gcm.dart uses a 16-byte IV, causing a runtime ArgumentError.
_{Severity: HIGH}

Suggested Fix

Update the example code in example/aes_gcm.dart to use a 12-byte IV, for instance, by changing IV.fromSecureRandom(16) to IV.fromSecureRandom(12). This will align the example with the new validation rules. Alternatively, if supporting variable-length IVs for GCM is desired, the validation logic should be relaxed or removed.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: lib/src/algorithms/aes.dart#L33-L39

Potential issue: A new validation was added in `lib/src/algorithms/aes.dart` that
enforces a strict 12-byte IV length for AES in GCM mode. However, the library's own
example file, `example/aes_gcm.dart`, uses `IV.fromSecureRandom(16)` to generate a
16-byte IV. This mismatch will cause the example code to fail with an `ArgumentError` at
runtime, making it unusable and creating a breaking change for users who might have been
using other IV lengths with GCM mode.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[Copilot]

Pull request overview

This pull request enhances AES encryption security by adding key and IV length validation, introduces a URL-safe random token generator, and improves GCM mode documentation and test coverage.

Changes:

• Added AES key length validation enforcing 16/24/32-byte keys (128/192/256-bit)
• Added AES IV length validation: 12 bytes for GCM mode, 16 bytes for other modes
• Added SecureRandom.base64Url getter for URL-safe random token generation
• Enhanced GCM documentation in README with AEAD explanation and ECB deprecation note
• Added 5 comprehensive GCM test cases covering round-trip encryption, AAD, key sizes, and IV uniqueness

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
lib/src/algorithms/aes.dart	Adds key length validation in constructor and IV length validation in encrypt/decrypt methods
lib/src/secure_random.dart	Adds base64Url getter for URL-safe encoding
test/encrypt_test.dart	Adds comprehensive GCM test suite with 5 test cases
README.md	Updates supported modes list with GCM AEAD description and ECB deprecation note

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The IV validation logic is duplicated between the encrypt and decrypt methods. Consider extracting this validation into a private helper method to reduce code duplication and ensure consistency. For example, a method like _validateIV(IV? iv) could be called at the start of both encrypt and decrypt methods.

[Copilot]

The new key and IV validation logic lacks test coverage. While the GCM functional tests are comprehensive, there are no tests verifying that invalid key lengths (e.g., 15, 17, 20 bytes) or invalid IV lengths (e.g., 11, 13, 16 bytes for GCM; 15, 17 bytes for other modes) correctly throw ArgumentError exceptions. The codebase has established patterns for testing validation errors (see test/encrypt_test.dart lines 271-282 for RSA StateError tests). Consider adding a dedicated test group for AES validation errors to ensure the validation logic works correctly and provide clear documentation of expected error behavior.

Suggested change

	group('AES validation errors', () {
	test('throws ArgumentError for invalid GCM key lengths', () {
	for (final keyLen in [15, 17, 20]) {
	expect(
	() => Encrypter(AES(Key.fromLength(keyLen), mode: AESMode.gcm)),
	throwsA(isA<ArgumentError>()),
	);
	}
	});
	test('throws ArgumentError for invalid GCM IV lengths', () {
	final encrypter = Encrypter(AES(key, mode: AESMode.gcm));
	for (final ivLen in [11, 13, 16]) {
	final iv = IV.fromLength(ivLen);
	expect(
	() => encrypter.encrypt(text, iv: iv),
	throwsA(isA<ArgumentError>()),
	);
	}
	});
	test('throws ArgumentError for invalid IV lengths in non-GCM mode', () {
	final encrypter = Encrypter(AES(key, mode: AESMode.cbc));
	for (final ivLen in [15, 17]) {
	final iv = IV.fromLength(ivLen);
	expect(
	() => encrypter.encrypt(text, iv: iv),
	throwsA(isA<ArgumentError>()),
	);
	}
	});
	});