aauth-signing 0.1.0__tar.gz

aauth_signing-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: aauth-signing
+Version: 0.1.0
+Summary: HTTP Message Signing (RFC 9421 + draft-hardt-httpbis-signature-key) for AAuth
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: PyJWT>=2.8.0
+
+# aauth-signing
+
+HTTP Message Signatures ([RFC 9421](https://www.rfc-editor.org/rfc/rfc9421)) and the **Signature-Key** header ([draft-hardt-httpbis-signature-key](https://datatracker.ietf.org/doc/draft-hardt-httpbis-signature-key/)) as used by [AAuth](https://github.com/ietf-wg-aauth).
+
+This package is **AAuth-oriented** (e.g. `aa-agent+jwt` / `aa-auth+jwt` in the `jwt` signature scheme, optional `aauth-mission` covered component).
+
+## Install
+
+```bash
+pip install aauth-signing
+```
+
+## Usage
+
+```python
+from aauth_signing import sign_request, verify_signature
+from aauth_signing import build_signature_key_header, parse_signature_key
+```
+
+## Development
+
+From the repository root:
+
+```bash
+pip install -e ./aauth-signing
+```

aauth_signing-0.1.0/README.md

@@ -0,0 +1,26 @@
+# aauth-signing
+
+HTTP Message Signatures ([RFC 9421](https://www.rfc-editor.org/rfc/rfc9421)) and the **Signature-Key** header ([draft-hardt-httpbis-signature-key](https://datatracker.ietf.org/doc/draft-hardt-httpbis-signature-key/)) as used by [AAuth](https://github.com/ietf-wg-aauth).
+
+This package is **AAuth-oriented** (e.g. `aa-agent+jwt` / `aa-auth+jwt` in the `jwt` signature scheme, optional `aauth-mission` covered component).
+
+## Install
+
+```bash
+pip install aauth-signing
+```
+
+## Usage
+
+```python
+from aauth_signing import sign_request, verify_signature
+from aauth_signing import build_signature_key_header, parse_signature_key
+```
+
+## Development
+
+From the repository root:
+
+```bash
+pip install -e ./aauth-signing
+```

aauth_signing-0.1.0/aauth_signing/__init__.py

@@ -0,0 +1,60 @@
+"""HTTP Message Signing layer (RFC 9421 + draft-hardt-httpbis-signature-key).
+
+This package provides AAuth-oriented HTTP message signing:
+
+  - HTTP Message Signatures per RFC 9421
+  - Signature-Key header per draft-hardt-httpbis-signature-key
+    (schemes: hwk, jwks_uri, jwt, jkt-jwt)
+
+Typical usage::
+
+    from aauth_signing import sign_request, verify_signature
+    from aauth_signing import build_signature_key_header, parse_signature_key
+"""
+
+from .signer import sign_request
+from .verifier import verify_signature
+from .algorithms import (
+    ED25519,
+    RSA_PSS_SHA512,
+    RSA_PSS_SHA256,
+    ECDSA_P256_SHA256,
+    ECDSA_P384_SHA384,
+    SUPPORTED_ALGORITHMS,
+    is_supported,
+)
+from .signature_base import (
+    build_signature_base,
+    build_signature_params,
+    calculate_content_digest,
+)
+from .signature_key import build_signature_key_header, parse_signature_key
+from .signature_input import build_signature_input_header, parse_signature_input
+from .signature import build_signature_header, parse_signature
+
+__all__ = [
+    # Core sign/verify
+    "sign_request",
+    "verify_signature",
+    # Algorithms
+    "ED25519",
+    "RSA_PSS_SHA512",
+    "RSA_PSS_SHA256",
+    "ECDSA_P256_SHA256",
+    "ECDSA_P384_SHA384",
+    "SUPPORTED_ALGORITHMS",
+    "is_supported",
+    # Signature base (RFC 9421)
+    "build_signature_base",
+    "build_signature_params",
+    "calculate_content_digest",
+    # Signature-Key header (draft-hardt-httpbis-signature-key)
+    "build_signature_key_header",
+    "parse_signature_key",
+    # Signature-Input header (RFC 9421)
+    "build_signature_input_header",
+    "parse_signature_input",
+    # Signature header (RFC 9421)
+    "build_signature_header",
+    "parse_signature",
+]

aauth_signing-0.1.0/aauth_signing/algorithms.py

@@ -0,0 +1,34 @@
+"""Signature algorithm support for AAuth."""
+
+# Supported algorithms per AAuth spec Section 10.2
+# MUST support ed25519, MAY support others
+
+ED25519 = "ed25519"
+RSA_PSS_SHA512 = "rsa-pss-sha512"
+RSA_PSS_SHA256 = "rsa-pss-sha256"
+ECDSA_P256_SHA256 = "ecdsa-p256-sha256"
+ECDSA_P384_SHA384 = "ecdsa-p384-sha384"
+
+# Required algorithm
+REQUIRED_ALGORITHM = ED25519
+
+# All supported algorithms
+SUPPORTED_ALGORITHMS = [
+    ED25519,
+    RSA_PSS_SHA512,
+    RSA_PSS_SHA256,
+    ECDSA_P256_SHA256,
+    ECDSA_P384_SHA384,
+]
+
+
+def is_supported(algorithm: str) -> bool:
+    """Check if algorithm is supported.
+
+    Args:
+        algorithm: Algorithm name
+
+    Returns:
+        True if supported, False otherwise
+    """
+    return algorithm.lower() in [alg.lower() for alg in SUPPORTED_ALGORITHMS]

aauth_signing-0.1.0/aauth_signing/errors.py

@@ -0,0 +1,29 @@
+"""Exceptions shared by the aauth-signing package."""
+
+# Signature-Error header codes (401 responses, per draft-hardt-httpbis-signature-key)
+ERROR_INVALID_SIGNATURE = "invalid_signature"
+
+
+class AAuthError(Exception):
+    """Base exception for AAuth-related errors in this package."""
+
+    pass
+
+
+class SignatureError(AAuthError):
+    """HTTP signature validation or creation error."""
+
+    def __init__(self, message: str, error_code: str = None, details: dict = None):
+        super().__init__(message)
+        self.error_code = error_code or ERROR_INVALID_SIGNATURE
+        self.details = details or {}
+
+
+class TokenError(AAuthError):
+    """Token validation or creation error."""
+
+    def __init__(self, message: str, token_type: str = None, error_code: str = None, details: dict = None):
+        super().__init__(message)
+        self.token_type = token_type
+        self.error_code = error_code
+        self.details = details or {}

aauth_signing-0.1.0/aauth_signing/keys/__init__.py

@@ -0,0 +1 @@
+"""JWK and keypair helpers for aauth-signing."""

aauth_signing-0.1.0/aauth_signing/keys/jwk.py

@@ -0,0 +1,122 @@
+"""JWK (JSON Web Key) operations for aauth-signing."""
+
+import base64
+import hashlib
+import json
+from typing import Dict, Any, Optional
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives import serialization
+
+
+def private_key_to_jwk(private_key: Ed25519PrivateKey, kid: Optional[str] = None) -> Dict[str, Any]:
+    """Convert Ed25519 private key to JWK format.
+
+    Args:
+        private_key: Ed25519 private key
+        kid: Optional key ID
+
+    Returns:
+        JWK dictionary
+    """
+    public_key = private_key.public_key()
+    return public_key_to_jwk(public_key, kid)
+
+
+def public_key_to_jwk(public_key: Ed25519PublicKey, kid: Optional[str] = None) -> Dict[str, Any]:
+    """Convert Ed25519 public key to JWK format.
+
+    Args:
+        public_key: Ed25519 public key
+        kid: Optional key ID
+
+    Returns:
+        JWK dictionary
+    """
+    public_bytes = public_key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw
+    )
+
+    # Ed25519 public key is 32 bytes, encode as base64url
+    x = base64.urlsafe_b64encode(public_bytes).decode('utf-8').rstrip('=')
+
+    jwk = {
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "x": x
+    }
+
+    if kid:
+        jwk["kid"] = kid
+
+    return jwk
+
+
+def jwk_to_public_key(jwk: Dict[str, Any]) -> Ed25519PublicKey:
+    """Convert JWK to Ed25519PublicKey object.
+
+    Args:
+        jwk: JWK dictionary with kty="OKP", crv="Ed25519"
+
+    Returns:
+        Ed25519PublicKey object
+
+    Raises:
+        ValueError: If JWK is not Ed25519 format
+    """
+    if jwk.get("kty") != "OKP" or jwk.get("crv") != "Ed25519":
+        raise ValueError("JWK must be Ed25519 (OKP, Ed25519)")
+
+    x = jwk["x"]
+    # Add padding if needed
+    x += '=' * (4 - len(x) % 4)
+    public_bytes = base64.urlsafe_b64decode(x)
+
+    return Ed25519PublicKey.from_public_bytes(public_bytes)
+
+
+def calculate_jwk_thumbprint(jwk: Dict[str, Any]) -> str:
+    """Calculate JWK Thumbprint per RFC 7638.
+
+    Args:
+        jwk: JWK dictionary (must be canonical - only include required fields)
+
+    Returns:
+        Base64url-encoded SHA-256 hash of canonical JWK JSON
+    """
+    # Create canonical JWK (only include required fields, sorted)
+    # For Ed25519: kty, crv, x (kid excluded from thumbprint)
+    canonical_jwk = {}
+
+    # Required fields in order
+    if "kty" in jwk:
+        canonical_jwk["kty"] = jwk["kty"]
+    if "crv" in jwk:
+        canonical_jwk["crv"] = jwk["crv"]
+    if "x" in jwk:
+        canonical_jwk["x"] = jwk["x"]
+
+    # Convert to canonical JSON (no spaces, sorted keys)
+    canonical_json = json.dumps(canonical_jwk, separators=(',', ':'), sort_keys=True)
+
+    # SHA-256 hash
+    hash_bytes = hashlib.sha256(canonical_json.encode('utf-8')).digest()
+
+    # Base64url encode (no padding)
+    thumbprint = base64.urlsafe_b64encode(hash_bytes).decode('utf-8').rstrip('=')
+
+    return thumbprint
+
+
+def generate_jwks(keys: list[Dict[str, Any]]) -> Dict[str, Any]:
+    """Generate a JWKS document from a list of JWKs.
+
+    Args:
+        keys: List of JWK dictionaries
+
+    Returns:
+        JWKS document dictionary
+    """
+    return {
+        "keys": keys
+    }

aauth_signing-0.1.0/aauth_signing/keys/keypair.py

@@ -0,0 +1,15 @@
+"""Key pair generation for aauth-signing."""
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from typing import Tuple
+
+
+def generate_ed25519_keypair() -> Tuple[Ed25519PrivateKey, Ed25519PublicKey]:
+    """Generate a new Ed25519 key pair.
+
+    Returns:
+        Tuple of (private_key, public_key)
+    """
+    private_key = Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    return private_key, public_key

aauth_signing-0.1.0/aauth_signing/signature.py

@@ -0,0 +1,52 @@
+"""Signature header parsing and building (RFC 9421)."""
+
+import re
+import base64
+from typing import Optional
+
+
+def build_signature_header(signature_bytes: bytes, label: str = "sig") -> str:
+    """Build Signature header per RFC 9421 Section 4.2.
+
+    Args:
+        signature_bytes: Raw signature bytes
+        label: Signature label (default: "sig")
+
+    Returns:
+        Signature header value
+    """
+    signature_b64 = base64.urlsafe_b64encode(signature_bytes).decode('utf-8').rstrip('=')
+    return f'{label}=:{signature_b64}:'
+
+
+def parse_signature(header_value: str, label: Optional[str] = None) -> bytes:
+    """Parse Signature header to extract signature bytes.
+
+    Args:
+        header_value: Signature header value
+        label: Optional expected label (for validation)
+
+    Returns:
+        Signature bytes
+
+    Raises:
+        ValueError: If header format is invalid or label doesn't match
+    """
+    match = re.search(r'(\w+)=:([A-Za-z0-9_-]+):', header_value)
+    if not match:
+        raise ValueError(f"Invalid Signature format: {header_value}")
+
+    found_label = match.group(1)
+    signature_b64 = match.group(2)
+
+    if label and found_label != label:
+        raise ValueError(f"Label mismatch: expected {label}, got {found_label}")
+
+    # Add padding if needed
+    signature_b64 += '=' * (4 - len(signature_b64) % 4)
+
+    try:
+        signature_bytes = base64.urlsafe_b64decode(signature_b64)
+        return signature_bytes
+    except Exception as e:
+        raise ValueError(f"Failed to decode signature: {e}")

aauth_signing-0.1.0/aauth_signing/signature_base.py

@@ -0,0 +1,186 @@
+"""Signature base construction for HTTP Message Signing (RFC 9421)."""
+
+from typing import List, Tuple, Dict, Optional
+
+__all__ = [
+    "build_signature_base",
+    "build_signature_params",
+    "calculate_content_digest",
+    "_determine_covered_components",
+]
+import base64
+import hashlib
+
+
+def build_signature_base(
+    method: str,
+    authority: str,
+    path: str,
+    query: Optional[str],
+    headers: Dict[str, str],
+    body: Optional[bytes],
+    signature_key_header: str,
+    covered_components: Optional[List[str]] = None,
+    signature_params: Optional[str] = None
+) -> str:
+    """Build signature base string per RFC 9421 Section 2.5.
+
+    Args:
+        method: HTTP method
+        authority: Canonical authority (host:port)
+        path: Request path
+        query: Query string (without leading "?")
+        headers: Request headers
+        body: Request body bytes (None if no body)
+        signature_key_header: Signature-Key header value
+        covered_components: Optional list of components to cover (auto-detected if None)
+        signature_params: Signature-Input header value (required for @signature-params line)
+
+    Returns:
+        Signature base string
+    """
+    if covered_components is None:
+        covered_components = _determine_covered_components(query, body, additional_components=None)
+
+    components: List[Tuple[str, str]] = []
+
+    for component_name in covered_components:
+        if component_name == "@method":
+            components.append(("@method", method))
+        elif component_name == "@authority":
+            components.append(("@authority", authority))
+        elif component_name == "@path":
+            components.append(("@path", path))
+        elif component_name == "@query":
+            if query:
+                components.append(("@query", f"?{query}"))
+            else:
+                raise ValueError("@query component specified but no query string present")
+        elif component_name == "content-type":
+            if body:
+                content_type = _get_header(headers, "content-type")
+                if content_type:
+                    components.append(("content-type", content_type))
+                else:
+                    raise ValueError("content-type component required but header missing")
+            else:
+                raise ValueError("content-type component specified but no body present")
+        elif component_name == "content-digest":
+            if body:
+                content_digest = _get_header(headers, "content-digest")
+                if content_digest:
+                    components.append(("content-digest", content_digest))
+                else:
+                    raise ValueError("content-digest component required but header missing")
+            else:
+                raise ValueError("content-digest component specified but no body present")
+        elif component_name == "signature-key":
+            components.append(("signature-key", signature_key_header))
+        elif component_name == "aauth-mission":
+            mission_val = _get_header(headers, "aauth-mission")
+            if not mission_val:
+                raise ValueError("aauth-mission in Signature-Input but AAuth-Mission header missing")
+            components.append(("aauth-mission", mission_val))
+        else:
+            raise ValueError(f"Unknown component: {component_name}")
+
+    # Build signature base (RFC 9421 Section 2.5)
+    signature_base_parts = []
+    for component_name, component_value in components:
+        if component_name.startswith("@"):
+            signature_base_parts.append(f'"{component_name}": {component_value}')
+        else:
+            header_name = component_name.lower()
+            signature_base_parts.append(f'"{header_name}": {component_value}')
+
+    # Add @signature-params as the FINAL line (RFC 9421 Section 2.5)
+    if not signature_params:
+        raise ValueError("signature_params is required for valid signature base")
+    signature_base_parts.append(f'"@signature-params": {signature_params}')
+
+    return "\n".join(signature_base_parts)
+
+
+def _determine_covered_components(
+    query: Optional[str],
+    body: Optional[bytes],
+    additional_components: Optional[List[str]] = None,
+    *,
+    include_aauth_mission: bool = False,
+) -> List[str]:
+    """Determine covered components based on request structure.
+
+    Per AAuth spec Section 15.3, MUST cover:
+    - @method, @authority, @path, signature-key
+
+    With ``AAuth-Mission`` on authorization requests, also cover ``aauth-mission`` after
+    ``signature-key`` (spec §Authorization Endpoint Request).
+
+    Resources MAY require additional components via additional_signature_components.
+
+    Args:
+        query: Query string (None if no query)
+        body: Request body (None if no body)
+        additional_components: Optional list of additional components to include
+        include_aauth_mission: If True, append ``aauth-mission`` after ``signature-key``.
+
+    Returns:
+        List of component names
+    """
+    components = ["@method", "@authority", "@path"]
+
+    if query:
+        components.append("@query")
+
+    if additional_components:
+        components.extend(additional_components)
+
+    # signature-key MUST always be included
+    components.append("signature-key")
+
+    if include_aauth_mission:
+        components.append("aauth-mission")
+
+    return components
+
+
+def _get_header(headers: Dict[str, str], name: str) -> Optional[str]:
+    """Get header value (case-insensitive)."""
+    name_lower = name.lower()
+    for key, value in headers.items():
+        if key.lower() == name_lower:
+            return value
+    return None
+
+
+def build_signature_params(
+    covered_components: List[str],
+    created: int
+) -> str:
+    """Build the Signature-Input value (the part after the label).
+
+    Per AAuth spec Section 15.4, only `created` is REQUIRED.
+
+    Args:
+        covered_components: List of component names
+        created: Creation timestamp (Unix time)
+
+    Returns:
+        Signature params string: ("@method" "@authority" ...);created=1234567890
+    """
+    components_str = " ".join(f'"{c}"' for c in covered_components)
+    return f"({components_str});created={created}"
+
+
+def calculate_content_digest(body: bytes) -> str:
+    """Calculate Content-Digest header value per RFC 9530.
+
+    Args:
+        body: Request body bytes
+
+    Returns:
+        Content-Digest header value (e.g., "sha-256=:...:")
+    """
+    digest = hashlib.sha256(body).digest()
+    digest_b64 = base64.b64encode(digest).decode('ascii')
+    return f"sha-256=:{digest_b64}:"

aauth_signing-0.1.0/aauth_signing/signature_input.py

@@ -0,0 +1,62 @@
+"""Signature-Input header parsing and building (RFC 9421)."""
+
+import re
+import time
+from typing import List, Dict, Any, Optional
+
+
+def build_signature_input_header(
+    covered_components: List[str],
+    label: str = "sig",
+    created: Optional[int] = None
+) -> str:
+    """Build Signature-Input header per RFC 9421 Section 4.1.
+
+    Args:
+        covered_components: List of component names to cover
+        label: Signature label (default: "sig")
+        created: Creation timestamp (Unix time). If None, uses current time.
+
+    Returns:
+        Signature-Input header value
+    """
+    if created is None:
+        created = int(time.time())
+
+    component_list = ' '.join([
+        f'"{comp}"' for comp in covered_components
+    ])
+
+    return f'{label}=({component_list});created={created}'
+
+
+def parse_signature_input(header_value: str) -> tuple[List[str], Dict[str, Any]]:
+    """Parse Signature-Input header to extract covered components and parameters.
+
+    Args:
+        header_value: Signature-Input header value
+
+    Returns:
+        Tuple of (components list, parameters dict)
+
+    Raises:
+        ValueError: If header format is invalid
+    """
+    match = re.match(r'(\w+)=\((.*)\)(?:;(.*))?', header_value)
+    if not match:
+        raise ValueError(f"Invalid Signature-Input format: {header_value}")
+
+    components_str = match.group(2)
+    params_str = match.group(3) or ""
+
+    components = []
+    for match in re.finditer(r'"([^"]+)"', components_str):
+        components.append(match.group(1))
+
+    params = {}
+    for match in re.finditer(r'(\w+)=([^\s;]+)', params_str):
+        key = match.group(1)
+        value = match.group(2).strip('"')
+        params[key] = value
+
+    return components, params