feat(vault): add key-version header and rotation keyring support (#1770)

[trivikramkalagi91-commits]

Description

Refactor VaultCrypto in backend/secuscan/vault.py to add explicit key-version headers, rotation keyring support, collision-safe legacy fallback decryption, key ID extraction, and strict payload length guards.

Key Technical Enhancements

• Wire Format Specification (Version 1):
  Prepend magic header b"SV1:" (4 bytes) and raw key fingerprint (8 bytes) to newly encrypted blobs:
  $$\text{Wire Format} = \text{b"SV1:"}(4) ;||; \text{key_id_bytes}(8) ;||; \text{nonce}(12) ;||; \text{ciphertext} ;||; \text{auth_tag}(16)$$
• Zero-Downtime Key Rotation & Keyring:
  Updated VaultCrypto.__init__(key, fallback_keys=[...]) to maintain an internal $\mathcal{O}(1)$ keyring lookup dictionary (_keyring: Dict[bytes, AESGCM]). Decryption extracts the key ID from the header to look up the correct key instantly without trial-and-error GCM tag failures.
• Collision-Safe Legacy Fallback Protocol:
  If versioned decryption fails or if a legacy random 12-byte nonce coincidentally starts with b"SV1:" (1 in $2^{32}$ probability), decrypt() automatically falls back to attempting legacy decryption (nonce(12) || ciphertext), guaranteeing zero false-positive decryption failures for pre-existing secrets.
• Out-of-Band Key ID Extraction:
  Added VaultCrypto.extract_key_id(cls, payload: str) -> Optional[str] to inspect base64url payloads and return the colon-separated hex key fingerprint without requiring secret decryption.
• Explicit Payload Length Guards:
  Enforced strict minimum length guards ($\ge 28$ bytes for legacy, $\ge 40$ bytes for versioned) to fail fast on truncated inputs before touching underlying cryptographic routines.

Related Issues

Closes #1770

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

How Has This Been Tested?

Automated backend unit and integration test suites executed:

.\venv\Scripts\pytest testing/backend/unit/test_vault.py testing/backend/unit/test_vault_failure_messages.py testing/backend/unit/test_vault_fingerprint.py testing/backend/unit/test_vault_owner_isolation.py testing/backend/unit/test_vault_security.py -v

note :- though i have used ai to solve but i completely reviewed the changes made by ai tested it and then approved the changes 

[trivikramkalagi91-commits]

hey @utksh1 all the 26 checks have been passed with no error please review the pr as it is ready to merge

[trivikramkalagi91-commits]

hi @utksh1 i have resolved the merge conflict and also the issue is solved and PR is ready to merge plese review it

[trivikramkalagi91-commits]

hi @utksh1 i have resolved the merge conflict and also the issue is solved and PR is ready to merge plese review it