Add KeyMetadata data class for symmetric key rotation, Fixes AB#3546146

[Copilot]

Foundational immutable data class for tracking symmetric encryption key versions, enabling SDL-compliant key rotation in the Android Broker. Each key instance captures its version ID, creation timestamp, algorithm, key size, and deprecation status (decrypt-only flag).

Changes

common4j/.../crypto/KeyMetadata.java

• Immutable final class using Lombok @Getter and @Builder annotations to eliminate boilerplate
• Fields: versionId, createdAtMillis, algorithm (default AES/CBC/PKCS5Padding), keySize (default 256), deprecated
• Fail-fast validation in constructor: blank versionId throws IllegalStateException; non-positive keySize throws IllegalArgumentException
• toJson() / fromJson(String) via org.json for persistence by the KeyVersionRegistry
• fromJson() uses opt* APIs for optional fields (algorithm, keySize, deprecated) so deserialization is backward-compatible with older persisted JSON

KeyMetadata key = KeyMetadata.builder()
        .versionId("K001")
        .createdAtMillis(System.currentTimeMillis())
        .deprecated(false)
        .build();

String json = key.toJson();
KeyMetadata restored = KeyMetadata.fromJson(json);

common4j/.../crypto/KeyMetadataTest.java

Unit tests covering builder defaults, field validation, JSON round-trip, deprecated flag semantics, backward-compatible deserialization of JSON missing optional fields, and malformed JSON error handling.

Original prompt

[Symmetric Key Rotation] Add KeyMetadata data class

Fixes AB#3546146

Objective

Add a KeyMetadata data class to common4j that stores version information for symmetric encryption keys. This is the foundational data structure for the symmetric key rotation feature.

Context

The Android Broker needs to support multiple symmetric key versions to enable SDL-compliant key rotation. Each key needs metadata including version ID, creation timestamp, algorithm, and deprecation status. This data class will be used by the KeyVersionRegistry (in common) and the encryption managers (in broker).

Technical Requirements

• Create new file common4j/src/main/com/microsoft/identity/common/java/crypto/KeyMetadata.java
• Implement as an immutable data class with the following fields:
  • versionId (String): Key identifier like K001, K002
  • createdAtMillis (long): Unix timestamp of key creation
  • algorithm (String): Encryption algorithm, default AES/CBC/PKCS5Padding
  • keySize (int): Key size in bits, default 256
  • isDeprecated (boolean): If true, key can only decrypt (not encrypt)
• Add JSON serialization/deserialization methods (toJson(), fromJson(String)) using org.json
• Follow existing patterns in common4j for data classes
• Add appropriate JavaDoc comments
• Add copyright header to the new file

Scope

In scope: KeyMetadata data class with all fields, JSON serialization/deserialization, Builder pattern for construction.
Out of scope: Persistence logic (handled by KeyVersionRegistry), Key generation logic (handled elsewhere).

Files to Create

• common4j/src/main/com/microsoft/identity/common/java/crypto/KeyMetadata.java

Acceptance Criteria

• KeyMetadata class exists with all required fields
• toJson() produces valid JSON representation
• fromJson(String) reconstructs the object correctly
• Class is immutable (final fields, no setters)
• JavaDoc comments document each field
• Compile check passes: ./gradlew :common4j:compileJava

Follow .github/copilot-instructions.md strictly.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[github-actions]

✅ Work item link check complete. Description contains link AB#3546146 to an Azure Boards work item.

[Copilot]

Pull request overview

Adds a foundational immutable metadata model in common4j to represent symmetric key versions for upcoming key-rotation work (intended to be consumed by a KeyVersionRegistry and broker encryption managers).

Changes:

• Introduces KeyMetadata (immutable, builder-based) with JSON serialization/deserialization for persistence.
• Adds unit tests validating builder behavior and JSON round-tripping.

Reviewed changes

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

File	Description
common4j/src/main/com/microsoft/identity/common/java/crypto/KeyMetadata.java	New immutable key-version metadata type with a Builder and org.json (de)serialization helpers.
common4j/src/test/com/microsoft/identity/common/java/crypto/KeyMetadataTest.java	Unit tests for builder defaults/validation and JSON round-trip behavior.

[fadidurah]

@copilot we can make this class much more concise using Lombok's Getter and Builder annotations

[Copilot]

@copilot we can make this class much more concise using Lombok's Getter and Builder annotations

Done in 7e519e3. The class now uses @Getter + @Builder + @Builder.Default, removing ~120 lines of boilerplate (all manual getters and the entire inner Builder class). Validation is kept in a private constructor that Lombok's generated build() calls. I also took the opportunity to fix fromJson() to use opt* APIs for optional fields and improve the JSON assertion test to parse the JSON object and check each field directly.