The length check guards against a missing nonce, but AES-GCM also requires a 16-byte auth tag. A 12–27 byte buffer passes this check and then surfaces as an opaque InvalidTag from AESGCM.decrypt, which conflates truncated ciphertext with active tampering in logs/Sentry.

Suggest:

if len(value) < self._nonce_size + 16:
    raise ValueError("Encrypted payload is too short (missing nonce or auth tag)")

The GCM tag is fixed at 16 bytes for AES-128/192/256.

Done.

NotImplementedError is conventionally for unimplemented abstract methods / unfinished features. An unsupported runtime config is a caller/data error — TypeError (matches Python's own behavior for unmatched match over types) or ValueError is more appropriate, so callers can distinguish the loader is incomplete from you passed a bogus config.

The test at test_kms_envelope_payload_codec_loader.py:88-89 would need a matching update.

Complements the Copilot note above: when urlsafe_b64decode rejects malformed input it raises binascii.Error, which is currently re-raised unwrapped. AGENTS.md L94 requires raise ... from err chaining so the original cause is preserved. Suggest:

import binascii

if isinstance(value, str):
    try:
        return urlsafe_b64decode(value.encode("ascii"))
    except (binascii.Error, ValueError) as e:
        raise ValueError("wrapped_dek is not valid base64url") from e

Same pattern needed for associated_data at line 51.

Done.

KMSEnvelopePayloadCodecConfig is intended as an abstract base (no type discriminator) but is freely instantiable — test_kms_envelope_payload_codec_loader.py:80-96 confirms this by constructing an UnknownKMSEnvelopePayloadCodecConfig directly.

A couple of options:

• If genuinely abstract: make it ABC (or a typing.Protocol) and move the base64 validators into a shared mixin. Bare instantiation should fail.
• If purely structural: consider composition — give each concrete config an envelope: KMSEnvelopeParams field instead of inheritance. That flattens the discriminated union and removes the abstract base in a union hazard.

Either way, consider model_config = ConfigDict(frozen=True) — config objects holding (wrapped) key material should be immutable.

Composition is probably better than inheritance here from a design pattern perspective, but it will make config processing more complicated.

Three defensive branches the codec adds are currently untested — easy wins:

• nonce_size <= 0 constructor guard (codec line 24-25)
• short-payload ValueError branch (codec line 39-40)
• tampered ciphertext distinct from AD mismatch — the existing wrong_codec test only varies the AAD, so a regression that silently disabled GCM auth-tag verification while leaving AAD intact would still pass. Flipping a byte in the ciphertext (buf = bytearray(encoded); buf[20] ^= 1) and asserting InvalidTag would catch it.

Done.

associated_data=None is never exercised in the codec, config, or loader tests. Both _decode_associated_data / _serialize_associated_data None branches and AESGCM.encrypt(...) with aad=None are unverified. A second loader test with associated_data=None would close this — it's the path most production callers will hit first if they forget to pass AAD.