Binary Envelope Toolkit

Utility module for converting between JOSE-safe encodings and X.509 objects with strict length validation.

Capabilities

JOSE base64 conversion

• Decoding the JOSE base64 string dGVzdA (ASCII or bytes input) yields the bytes b"test" and re-encoding returns the same paddingless string. @test
• When expecting an 8-byte payload, decoding ZGF0YQ (4-byte content) fails with a size-validation error. @test

Hex parsing safeguards

• Converting the hex string deadbeef to bytes returns b"\xde\xad\xbe\xef" and enforcing an exact 4-byte size passes. @test
• When minimum length is set to 2 bytes, decoding 0a0b0c succeeds and leaves the 3-byte result unchanged. @test

X.509 DER helpers

• Serializing a certificate object to a base64 DER string and parsing it back preserves the common name in the subject. @test
• Parsing a malformed base64 DER string as a CSR raises an explicit deserialization failure instead of returning a partial object. @test

Implementation

@generates

API

from typing import Optional, Union
from cryptography import x509

def to_jose_base64(data: bytes) -> str:
    """Encode binary data to paddingless, URL-safe base64 suitable for JOSE contexts."""

def from_jose_base64(value: Union[str, bytes], expected_size: Optional[int] = None, minimum: bool = False) -> bytes:
    """Decode JOSE-safe base64 input with optional exact or minimum-length enforcement."""

def encode_hex(value: bytes) -> str:
    """Produce a lowercase hexadecimal representation of binary data."""

def decode_hex(value: str, expected_size: Optional[int] = None, minimum: bool = False) -> bytes:
    """Decode hex strings with optional exact or minimum-length enforcement."""

def serialize_certificate(cert: x509.Certificate) -> str:
    """Convert a certificate object to a base64 DER string."""

def parse_certificate(value: str) -> x509.Certificate:
    """Parse a base64 DER certificate string and return a certificate object."""

def serialize_csr(csr: x509.CertificateSigningRequest) -> str:
    """Convert a CSR object to a base64 DER string."""

def parse_csr(value: str) -> x509.CertificateSigningRequest:
    """Parse a base64 DER CSR string and return a CSR object."""

Dependencies { .dependencies }

josepy { .dependency }

Provides JOSE-focused base64, hex, and X.509 DER helpers with length validation.

@satisfied-by

cryptography { .dependency }

Supplies X.509 certificate and CSR primitives for encoding and decoding.

@satisfied-by