Metadata-Version: 2.4
Name: pyreqsign
Version: 1.3.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP
Summary: HMAC-based API request signing with environment-bound key derivation for microservices
Keywords: api,signing,hmac,authentication,microservice,security,request-signing
Author-email: infra-security-tooling <infra@pyreqsign.dev>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# pyreqsign

> HMAC-based API request signing with environment-bound key derivation for microservices.

## Installation

```bash
pip install pyreqsign
```

## Quick Start

```python
from pyreqsign import sign, verify, sign_request

# Sign API parameters
signature = sign(secret="my-api-key", params={"user_id": "42"}, method="POST", path="/api/data")
# → "ES-v2:YWJjZGVm..."

# Verify on the server side
is_valid = verify(secret="my-api-key", params={"user_id": "42"}, signature=signature)

# Or sign an entire HTTP request (returns headers dict)
headers = sign_request("my-api-key", "POST", "https://api.example.com/v1/data",
                       json_body={"action": "update"})
# → {"Authorization": "EnvSign ES-v2:...", "X-EnvSign-Timestamp": "1714300000"}
```

## Why EnvSign?

Standard HMAC signing only binds the secret key. EnvSign additionally binds the signing environment — the derived key depends on both the secret AND the machine fingerprint, making it ideal for:

- **Microservice-to-microservice auth** where each service instance has a unique identity
- **API gateway request validation** with replay protection via timestamp binding
- **Webhook verification** where the sender environment is part of the trust chain

## API

### Core Signing

| Function | Description |
|----------|-------------|
| `sign(secret, params, ...)` | Sign request parameters, returns `ES-v2:<sig>` |
| `verify(secret, params, sig, ...)` | Verify signature, constant-time comparison |
| `sign_request(secret, method, url, ...)` | Sign full HTTP request, returns auth headers |
| `env_fingerprint()` | Generate 256-bit machine identity |
| `derive_key(secret, fp)` | Derive signing key from secret + fingerprint |

### Config Helpers

| Function | Description |
|----------|-------------|
| `get_env(key, default)` | Read string env var |
| `parse_bool(key, default)` | Parse boolean (true/1/yes/on) |
| `parse_int(key, default)` | Parse integer, silent fallback |
| `parse_list(key, sep, default)` | Parse comma-separated list |
| `load_config(prefix)` | Collect all vars matching prefix |

## License

MIT

