swarmauri_signing_dpop 0.11.0.dev1

DPoP signer/verifier for Swarmauri

Swarmauri Signing DPoP

DPoP proof signer/verifier implementing RFC 9449 for proof-of-possession over HTTP requests.

Features:

• Creates and validates dpop+jwt proofs with embedded public JWK thumbprints.
• Supports ES256, RS256, and EdDSA algorithms through the SigningBase interface.
• Optional access-token hash binding (ath), nonce enforcement, and replay-protection hooks.

Installation

The package is published on PyPI together with the dependencies required to sign and verify DPoP proofs.

pip

pip install swarmauri_signing_dpop

uv

uv add swarmauri_signing_dpop

Poetry

poetry add swarmauri_signing_dpop

Usage

DpopSigner implements the asynchronous SigningBase / ISigning interface. Signing requires the HTTP method and URL (opts['htm'] and opts['htu']), and verification requires the same data passed via require.

Signing and verifying a request

import asyncio

from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ed25519

from swarmauri_signing_dpop import DpopSigner


async def main() -> None:
    signer = DpopSigner()

    private_key = ed25519.Ed25519PrivateKey.generate()
    priv_pem = private_key.private_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PrivateFormat.PKCS8,
        encryption_algorithm=serialization.NoEncryption(),
    )
    key = {"kind": "pem", "priv": priv_pem, "alg": "EdDSA"}

    signatures = await signer.sign_bytes(
        key,
        b"",
        opts={"htm": "GET", "htu": "https://api.example/x"},
    )

    is_valid = await signer.verify_bytes(
        b"",
        signatures,
        require={"htm": "GET", "htu": "https://api.example/x"},
    )
    assert is_valid
    print("DPoP proof valid:", is_valid)


asyncio.run(main())

Signature format

sign_bytes and sign_envelope return a sequence with a single detached signature entry:

{
    "alg": "EdDSA",            # JWS algorithm used
    "format": "dpop+jwt",      # proof media type
    "sig": "<compact JWT>",    # DPoP proof token containing the claims
    "jkt": "<thumbprint>",     # SHA-256 JWK thumbprint for cnf.jkt binding
}

Use the jkt helper when comparing against cnf.jkt values embedded in access tokens.

Key references

Keys are provided using the KeyRef mapping expected by other Swarmauri signing packages:

• { "kind": "pem", "priv": <PEM bytes|str> } ? RSA/EC keys and Ed25519 PKCS8 PEM.
• { "kind": "jwk", "priv": <private JWK dict> } ? accepts EC, RSA, or OKP keys with private fields.

For Ed25519 material, both formats are supported; the signer derives and embeds the public JWK automatically.

Options reference

• opts['htm'] / opts['htu']: HTTP method and URL that will be bound in the proof (required for signing).
• opts['nonce']: Optional server-issued DPoP-Nonce to include in the proof.
• opts['access_token']: Optional access token to derive the ath confirmation hash.
• require['htm'] / require['htu']: Expected method and URL (required for verification).
• require['max_skew_s']: IAT skew tolerance (defaults to 300 seconds).
• require['algs']: Allowed signing algorithms. Defaults to all supported values.
• require['nonce']: Expected nonce when enforcing a server challenge.
• require['access_token']: Expected bearer token when validating ath.
• require['replay']: Mapping with seen(jti) -> bool and mark(jti, ttl_s) callables for replay prevention.

sign_envelope and verify_envelope reuse the same logic after canonicalizing the envelope to bytes (raw or json). Payload bytes are otherwise unused because the DPoP proof binds request metadata instead of message content.

Entry Point

The signer registers under the swarmauri.signings entry point as DpopSigner.

Want to help?

If you want to contribute to swarmauri-sdk, read up on our guidelines for contributing that will help you get started.