fleche.security

Attributes

logger

Exceptions

SignatureError

Exception raised when signature verification fails.

Classes

SignedBytes

Helper class to sign and verify serialized data using HMAC-SHA256.

Functions

`normalize_secret_key`(→ list[bytes])	Normalize a secret key value to `list[bytes]`.
`get_secret_key`(→ list[bytes])	Retrieve the secret key(s) from the `FLECHE_SECRET_KEY` environment variable.

Module Contents

fleche.security.logger[source]

exception fleche.security.SignatureError[source]

Bases: Exception

Exception raised when signature verification fails.

fleche.security.normalize_secret_key(key: bytes | str | collections.abc.Sequence[bytes | str]) → list[bytes][source]

Normalize a secret key value to list[bytes].

Accepts: - bytes: wrapped in a list - str: interpreted as a hex-encoded key; colon (:) separates multiple keys - list[bytes]: each element used as-is - list[str]: each element interpreted as hex-encoded; colon-delimited parts

within an element are treated as separate keys

This is the single normalization path used by both the FLECHE_SECRET_KEY environment variable and programmatic secret_key arguments — so any key that can be expressed in the environment variable can also be passed directly, and vice-versa.

Raises:

TypeError – if key or any list element is not bytes or str
ValueError – if any string part is not valid hex

fleche.security.get_secret_key() → list[bytes][source]

Retrieve the secret key(s) from the FLECHE_SECRET_KEY environment variable.

The value must be a colon-separated list of hex-encoded byte strings. Returns an empty list if the environment variable is not set (security disabled).

Uses the same normalize_secret_key() logic as the programmatic API, so any value valid here is also valid as a secret_key argument and vice-versa.

Returns:: A list of secret keys as bytes.
Return type:: list[bytes]

class fleche.security.SignedBytes[source]

Helper class to sign and verify serialized data using HMAC-SHA256. Allows for key rotation by accepting a list of keys.

Parameters:: keys (list[bytes]) – A list of secret keys. The first key is used for signing, and all keys are attempted during verification.

keys: collections.abc.Sequence[bytes][source]

_sign(data: bytes, key: bytes) → bytes[source]

Generate HMAC-SHA256 hex signature for data using the specified key. Hex encoding ensures the signature string (0-9a-f) never contains the pickle STOP opcode byte (ASCII 46, .).

Parameters:

data (bytes) – The data to sign.
key (bytes) – The secret key to use for signing.

Returns:

The resulting 64-byte hex-encoded HMAC signature.

Return type:

bytes

dumps(content: bytes) → bytes[source]

Signs the content using the first key in the list and appends the hex signature. If no keys are provided, returns the content unmodified.

Parameters:: content (bytes) – The serialized data to sign.
Returns:: The original data with the 64-byte hex signature appended (if keys exist).
Return type:: bytes

loads(content: bytes) → bytes[source]

Verifies the signature of the content. Extracts the signature by searching for the pickle STOP opcode. Iterates through all provided keys for verification. Returns the original content if verification passes.

Parameters:: content (bytes) – The payload containing the data and the appended signature.
Returns:: The original serialized data, stripped of the signature.
Return type:: bytes
Raises:: SignatureError – If verification fails, if the data is corrupted, or if the STOP opcode is missing.