Multi-Algorithm JWS Utility

A small module that signs and verifies payloads using compact JSON Web Signatures across symmetric and asymmetric algorithms.

Capabilities

HS256 signing and verification

• Signing payload b"ping" with algorithm "HS256" and secret b"shared-key" produces a compact JWS whose verification with the same secret returns the original payload bytes. @test

RS256 verification with public keys

• Given a compact JWS created with "RS256" and a provided private key, verification with the matching public key returns the payload bytes and raises ValueError for a token signed with a different RSA key. @test

PS256 tamper detection

• After creating a compact "PS256" token for payload b"hello", changing a character in the signature causes verification to raise ValueError. @test

ES256 header enforcement

• Signing payload b"data" with "ES256" ensures the protected header contains alg: ES256; verification raises ValueError if the caller requests a different algorithm value when checking the same token. @test

Implementation

@generates

API

from typing import Mapping, Optional, Union

KeyMaterial = Union[bytes, str]

def sign_compact(payload: bytes, alg: str, key_data: KeyMaterial, protected_headers: Optional[Mapping[str, str]] = None) -> str:
    """
    Return a compact JWS string for the payload using the specified algorithm.
    key_data is a shared secret for HS* algorithms or a PEM/DER private key for RS*/PS*/ES* algorithms.
    Raises ValueError if the algorithm is unsupported or headers conflict with signing requirements.
    """


def verify_compact(token: str, alg: str, key_data: KeyMaterial) -> bytes:
    """
    Validate the compact JWS using the provided algorithm and key_data.
    key_data is the shared secret for HS* algorithms or a PEM/DER public/private key for asymmetric algorithms.
    Returns the payload bytes when validation succeeds; raises ValueError on failure.
    """

Dependencies { .dependencies }

josepy { .dependency }

Provides JWA signing and verification primitives for HS*, RS*, PS*, and ES* algorithms.