binary-credential-format-boundary

Binary Credential Format Boundary

Preserve opaque binary values byte-for-byte while supporting explicitly defined text encodings through a separate parsing branch. Treat a flaky cryptographic verification as a possible ingestion bug before changing the cryptographic primitive.

Diagnose

1. Reproduce the failure and capture only exception types, lengths, and hashes; never print credential bytes.
2. Verify the primitive independently with an in-memory generate/sign/verify or encrypt/decrypt control.
3. Trace the exact bytes from serialization through file/environment ingestion to the primitive.
4. Look for pre-validation mutations: .strip(), .splitlines(), Unicode decode/encode, newline normalization, NUL termination, case conversion, or permissive Base64 decoding.
5. Compare interpreter and library versions only after the byte path is proven unchanged.

Parse Without Ambiguity

For a contract that accepts either a fixed-length raw value or Base64 text:

raw = path.read_bytes()
if len(raw) == EXPECTED_RAW_LENGTH:
    value = raw
else:
    value = base64.b64decode(raw.strip(), validate=True)
    if len(value) != EXPECTED_RAW_LENGTH:
        raise ValueError("invalid credential length")

Apply text cleanup only inside the text-encoding branch. Do not call .strip() before checking the raw representation: bytes such as 0x09, 0x0a, 0x0b, 0x0c, 0x0d, and 0x20 are valid opaque octets and may occur at either boundary.

Prefer an explicit format option or distinct file extension when the accepted encodings can have overlapping lengths. Use official PEM/DER/JWK loaders for those formats instead of inventing detection logic. Reject unknown, ambiguous, malformed, oversized, or non-canonical input fail-closed.

Test First

Add deterministic regressions before changing the reader:

• A raw value of the exact required length whose first byte is an ASCII whitespace octet.
• A raw value whose final byte is an ASCII whitespace octet.
• Raw values containing NUL and non-UTF-8 octets.
• Valid Base64 text with the contractually allowed line ending.
• Invalid Base64, decoded wrong length, ambiguous representation, and extra binary bytes.
• An end-to-end primitive check using the loaded value.