anncsu-sdk 0.0.1.dev21__tar.gz → 0.0.1.dev24__tar.gz

anncsu_sdk-0.0.1.dev24/.env.example

@@ -0,0 +1,34 @@
+# PDND Client Assertion Configuration
+# Copy this file to .env and fill in your actual values
+# All variables are prefixed with PDND_
+
+# Required: Key ID (kid) header parameter - identifies which key was used
+PDND_KID=your-key-id
+
+# Required: Issuer (iss) claim - typically your client_id from PDND
+PDND_ISSUER=your-client-id
+
+# Required: Subject (sub) claim - typically your client_id from PDND
+PDND_SUBJECT=your-client-id
+
+# Required: Audience (aud) claim - the PDND token endpoint URL
+PDND_AUDIENCE=https://auth.interop.pagopa.it/token.oauth2
+
+# Required: Purpose ID for the PDND request
+PDND_PURPOSE_ID=your-purpose-id
+
+# Required (one of the following):
+# Option 1: Path to the RSA private key file (PEM format)
+PDND_KEY_PATH=./private_key.pem
+
+# Option 2: RSA private key content in PEM format (alternative to PDND_KEY_PATH)
+# PDND_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----
+
+# Optional: Algorithm for signing the JWT (default: RS256)
+# PDND_ALG=RS256
+
+# Optional: Token type (default: JWT)
+# PDND_TYP=JWT
+
+# Optional: JWT validity period in minutes (default: 43200 = 30 days, max: 43200)
+# PDND_VALIDITY_MINUTES=43200

anncsu_sdk-0.0.1.dev21/README.md → anncsu_sdk-0.0.1.dev24/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.4
+Name: anncsu-sdk
+Version: 0.0.1.dev24
+Summary: ANNCSU Software Development Kit for API consumption
+Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: authlib>=1.3.0
+Requires-Dist: httpcore>=1.0.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.12.5
+Description-Content-Type: text/markdown
+
 # anncsu-sdk
 ANNCSU Software Development Kit for API consumption
 
@@ -185,10 +199,90 @@ response = sdk.queryparam.esiste_odonimo_get_query_param(
 - **Common Security**: Same `Security` class works across all ANNCSU APIs
 - **Type-Safe**: Full type hints with modern Python syntax
 
+### Generating Client Assertions Programmatically
+
+The SDK includes a built-in module for generating PDND client assertions (JWT tokens) at runtime:
+
+```python
+from anncsu.common import ClientAssertionConfig, create_client_assertion
+
+# Option 1: With private key as bytes
+config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="https://auth.interop.pagopa.it/token.oauth2",
+    purpose_id="your-purpose-id",
+    private_key=b"-----BEGIN RSA PRIVATE KEY-----\n...",
+)
+token = create_client_assertion(config)
+
+# Option 2: With private key file path
+from pathlib import Path
+
+config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="https://auth.interop.pagopa.it/token.oauth2",
+    purpose_id="your-purpose-id",
+    key_path=Path("./private_key.pem"),
+)
+token = create_client_assertion(config)
+
+# Use the token with the SDK
+from anncsu.common import Security
+
+security = Security(bearer=token)
+sdk = Anncsu(security=security)
+```
+
+### Loading Configuration from Environment Variables
+
+The SDK supports loading configuration from environment variables or a `.env` file:
+
+```python
+from anncsu.common.config import ClientAssertionSettings
+from anncsu.common import create_client_assertion, Security
+from anncsu.pa import Anncsu
+
+# Automatically loads from environment variables or .env file
+settings = ClientAssertionSettings()
+token = create_client_assertion(settings.to_config())
+
+# Use with SDK
+security = Security(bearer=token)
+sdk = Anncsu(security=security)
+```
+
+#### Required Environment Variables (prefix: `PDND_`)
+
+| Variable | Description |
+|----------|-------------|
+| `PDND_KID` | Key ID (kid) header parameter |
+| `PDND_ISSUER` | Issuer claim - your client_id |
+| `PDND_SUBJECT` | Subject claim - your client_id |
+| `PDND_AUDIENCE` | Audience claim - PDND token endpoint |
+| `PDND_PURPOSE_ID` | Purpose ID for the request |
+| `PDND_PRIVATE_KEY` | Private key content (or use `PDND_KEY_PATH`) |
+| `PDND_KEY_PATH` | Path to private key file (or use `PDND_PRIVATE_KEY`) |
+
+#### Example .env file
+
+```bash
+PDND_KID=my-key-id
+PDND_ISSUER=my-client-id
+PDND_SUBJECT=my-client-id
+PDND_AUDIENCE=https://auth.interop.pagopa.it/token.oauth2
+PDND_PURPOSE_ID=my-purpose-id
+PDND_KEY_PATH=./private_key.pem
+```
+
 ### Documentation
 
 For comprehensive security documentation including:
 - PDND voucher format and JWT structure
+- Client assertion generation
 - Token refresh strategies
 - Error handling (401/403)
 - Best practices and security checklist

anncsu_sdk-0.0.1.dev21/PKG-INFO → anncsu_sdk-0.0.1.dev24/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.4
-Name: anncsu-sdk
-Version: 0.0.1.dev21
-Summary: ANNCSU Software Development Kit for API consumption
-Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: authlib>=1.3.0
-Requires-Dist: httpcore>=1.0.9
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: pydantic>=2.11.2
-Description-Content-Type: text/markdown
-
 # anncsu-sdk
 ANNCSU Software Development Kit for API consumption
 
@@ -198,10 +185,90 @@ response = sdk.queryparam.esiste_odonimo_get_query_param(
 - **Common Security**: Same `Security` class works across all ANNCSU APIs
 - **Type-Safe**: Full type hints with modern Python syntax
 
+### Generating Client Assertions Programmatically
+
+The SDK includes a built-in module for generating PDND client assertions (JWT tokens) at runtime:
+
+```python
+from anncsu.common import ClientAssertionConfig, create_client_assertion
+
+# Option 1: With private key as bytes
+config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="https://auth.interop.pagopa.it/token.oauth2",
+    purpose_id="your-purpose-id",
+    private_key=b"-----BEGIN RSA PRIVATE KEY-----\n...",
+)
+token = create_client_assertion(config)
+
+# Option 2: With private key file path
+from pathlib import Path
+
+config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="https://auth.interop.pagopa.it/token.oauth2",
+    purpose_id="your-purpose-id",
+    key_path=Path("./private_key.pem"),
+)
+token = create_client_assertion(config)
+
+# Use the token with the SDK
+from anncsu.common import Security
+
+security = Security(bearer=token)
+sdk = Anncsu(security=security)
+```
+
+### Loading Configuration from Environment Variables
+
+The SDK supports loading configuration from environment variables or a `.env` file:
+
+```python
+from anncsu.common.config import ClientAssertionSettings
+from anncsu.common import create_client_assertion, Security
+from anncsu.pa import Anncsu
+
+# Automatically loads from environment variables or .env file
+settings = ClientAssertionSettings()
+token = create_client_assertion(settings.to_config())
+
+# Use with SDK
+security = Security(bearer=token)
+sdk = Anncsu(security=security)
+```
+
+#### Required Environment Variables (prefix: `PDND_`)
+
+| Variable | Description |
+|----------|-------------|
+| `PDND_KID` | Key ID (kid) header parameter |
+| `PDND_ISSUER` | Issuer claim - your client_id |
+| `PDND_SUBJECT` | Subject claim - your client_id |
+| `PDND_AUDIENCE` | Audience claim - PDND token endpoint |
+| `PDND_PURPOSE_ID` | Purpose ID for the request |
+| `PDND_PRIVATE_KEY` | Private key content (or use `PDND_KEY_PATH`) |
+| `PDND_KEY_PATH` | Path to private key file (or use `PDND_PRIVATE_KEY`) |
+
+#### Example .env file
+
+```bash
+PDND_KID=my-key-id
+PDND_ISSUER=my-client-id
+PDND_SUBJECT=my-client-id
+PDND_AUDIENCE=https://auth.interop.pagopa.it/token.oauth2
+PDND_PURPOSE_ID=my-purpose-id
+PDND_KEY_PATH=./private_key.pem
+```
+
 ### Documentation
 
 For comprehensive security documentation including:
 - PDND voucher format and JWT structure
+- Client assertion generation
 - Token refresh strategies
 - Error handling (401/403)
 - Best practices and security checklist

{anncsu_sdk-0.0.1.dev21 → anncsu_sdk-0.0.1.dev24}/docs/SECURITY.md

@@ -70,6 +70,192 @@ PDND vouchers have three parts separated by dots:
 2. **Payload**: Claims (issuer, subject, audience, expiration, etc.)
 3. **Signature**: Cryptographic signature
 
+## Generating Client Assertions
+
+The SDK includes a built-in module for generating PDND client assertions (JWT tokens). This allows you to create the JWT needed to obtain a PDND voucher programmatically.
+
+### Basic Usage
+
+```python
+from anncsu.common import ClientAssertionConfig, create_client_assertion
+
+# With private key as bytes
+config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="https://auth.interop.pagopa.it/token.oauth2",
+    purpose_id="your-purpose-id",
+    private_key=b"-----BEGIN RSA PRIVATE KEY-----\n...",
+)
+token = create_client_assertion(config)
+```
+
+### With Key File Path
+
+```python
+from pathlib import Path
+from anncsu.common import ClientAssertionConfig, create_client_assertion
+
+config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="https://auth.interop.pagopa.it/token.oauth2",
+    purpose_id="your-purpose-id",
+    key_path=Path("./private_key.pem"),
+)
+token = create_client_assertion(config)
+```
+
+### From Environment Variables (.env file)
+
+The SDK supports loading configuration from environment variables or a `.env` file using `ClientAssertionSettings`:
+
+```python
+from anncsu.common.config import ClientAssertionSettings
+from anncsu.common import create_client_assertion
+
+# Loads configuration from environment variables or .env file
+settings = ClientAssertionSettings()
+config = settings.to_config()
+token = create_client_assertion(config)
+```
+
+#### Environment Variables
+
+All environment variables use the `PDND_` prefix:
+
+| Environment Variable | Required | Description |
+|---------------------|----------|-------------|
+| `PDND_KID` | Yes | Key ID (kid) header parameter |
+| `PDND_ISSUER` | Yes | Issuer (iss) claim - your client_id |
+| `PDND_SUBJECT` | Yes | Subject (sub) claim - your client_id |
+| `PDND_AUDIENCE` | Yes | Audience (aud) claim - PDND token endpoint URL |
+| `PDND_PURPOSE_ID` | Yes | Purpose ID for the PDND request |
+| `PDND_PRIVATE_KEY` | One required | RSA private key content in PEM format (string) |
+| `PDND_KEY_PATH` | One required | Path to the RSA private key file |
+| `PDND_ALG` | No | Algorithm (default: "RS256") |
+| `PDND_TYP` | No | Token type (default: "JWT") |
+| `PDND_VALIDITY_MINUTES` | No | JWT validity in minutes (default: 43200) |
+
+#### Example .env File
+
+```bash
+# .env
+PDND_KID=my-key-id
+PDND_ISSUER=my-client-id
+PDND_SUBJECT=my-client-id
+PDND_AUDIENCE=https://auth.interop.pagopa.it/token.oauth2
+PDND_PURPOSE_ID=my-purpose-id
+PDND_KEY_PATH=./private_key.pem
+# Or use PDND_PRIVATE_KEY for inline key content
+```
+
+#### Shell Environment Variables
+
+```bash
+export PDND_KID="my-key-id"
+export PDND_ISSUER="my-client-id"
+export PDND_SUBJECT="my-client-id"
+export PDND_AUDIENCE="https://auth.interop.pagopa.it/token.oauth2"
+export PDND_PURPOSE_ID="my-purpose-id"
+export PDND_KEY_PATH="./private_key.pem"
+```
+
+Then in Python:
+
+```python
+from anncsu.common.config import ClientAssertionSettings
+from anncsu.common import create_client_assertion
+
+# Automatically loads from environment
+settings = ClientAssertionSettings()
+token = create_client_assertion(settings.to_config())
+```
+
+### Configuration Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `kid` | `str` | Yes | Key ID (kid) header parameter - identifies which key was used |
+| `issuer` | `str` | Yes | Issuer (iss) claim - typically your client_id from PDND |
+| `subject` | `str` | Yes | Subject (sub) claim - typically your client_id from PDND |
+| `audience` | `str` | Yes | Audience (aud) claim - the PDND token endpoint URL (must be HTTPS) |
+| `purpose_id` | `str` | Yes | Purpose ID for the PDND request |
+| `private_key` | `bytes` | One of these | RSA private key content in PEM format |
+| `key_path` | `Path` | is required | Path to the RSA private key file |
+| `alg` | `str` | No | Algorithm (default: "RS256") |
+| `typ` | `str` | No | Token type (default: "JWT") |
+| `validity_minutes` | `int` | No | JWT validity period in minutes (default: 43200 = 30 days, max: 43200) |
+
+### Custom Timestamps (for Testing)
+
+```python
+import datetime
+from anncsu.common import ClientAssertionConfig, create_client_assertion
+
+config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="https://auth.interop.pagopa.it/token.oauth2",
+    purpose_id="your-purpose-id",
+    private_key=private_key_bytes,
+    validity_minutes=60,  # 1 hour
+)
+
+# Custom issued_at and jti for deterministic testing
+token = create_client_assertion(
+    config,
+    issued_at=datetime.datetime(2024, 1, 1, 12, 0, 0, tzinfo=datetime.UTC),
+    jti="custom-jti-for-testing",
+)
+```
+
+### Error Handling
+
+```python
+from anncsu.common import (
+    ClientAssertionConfig,
+    create_client_assertion,
+    ClientAssertionError,
+    KeyFileError,
+    JWTGenerationError,
+)
+
+try:
+    config = ClientAssertionConfig(
+        kid="your-key-id",
+        issuer="your-client-id",
+        subject="your-client-id",
+        audience="https://auth.interop.pagopa.it/token.oauth2",
+        purpose_id="your-purpose-id",
+        key_path=Path("./private_key.pem"),
+    )
+    token = create_client_assertion(config)
+except KeyFileError as e:
+    print(f"Error reading key file: {e}")
+except JWTGenerationError as e:
+    print(f"Error generating JWT: {e}")
+except ClientAssertionError as e:
+    print(f"Client assertion error: {e}")
+```
+
+### CLI Tool
+
+For command-line usage, a CLI tool is also available:
+
+```bash
+python scripts/create_client_assertion.py create \
+    --kid "your-key-id" \
+    --issuer "your-client-id" \
+    --subject "your-client-id" \
+    --audience "https://auth.interop.pagopa.it/token.oauth2" \
+    --purpose-id "your-purpose-id" \
+    --key-path ./private_key.pem
+```
+
 ## Authentication Flow
 
 ### 1. Obtain PDND Voucher
@@ -79,9 +265,10 @@ Before using the SDK, you need to obtain a PDND voucher from the PDND platform:
 1. Register your organization on PDND
 2. Request access to ANNCSU APIs
 3. Obtain client credentials (client ID and secret)
-4. Exchange credentials for a voucher token
+4. Generate a client assertion using the SDK or CLI
+5. Exchange the client assertion for a voucher token
 
-*Note: Voucher acquisition is outside the scope of this SDK. Refer to PDND documentation.*
+*Note: The final exchange step is outside the scope of this SDK. Refer to PDND documentation.*
 
 ### 2. Configure SDK with Security
 

{anncsu_sdk-0.0.1.dev21 → anncsu_sdk-0.0.1.dev24}/pyproject.toml

@@ -10,20 +10,21 @@ requires-python = ">=3.12"
 dependencies = [
     "httpcore >=1.0.9",
     "httpx >=0.28.1",
-    "pydantic >=2.11.2",
+    "pydantic >=2.12.5",
     "authlib>=1.3.0",
+    "pydantic-settings>=2.12.0",
 ]
 [dependency-groups]
 dev = [
-    "pytest>=8.4.1",
+    "pytest>=9.0.0",
     "pytest-cov>=6.2.1",
-    "ruff>=0.12.7",
-    "uv-dynamic-versioning>=0.6.0",
+    "ruff>=0.14.6",
+    "uv-dynamic-versioning>=0.11.0",
     "openapi-pydantic>=0.4.1",
     "pyyaml>=6.0.0",
-    "faker>=33.1.0",
-    "polyfactory>=2.18.0",
-    "hypothesis>=6.122.3",
+    "faker>=38.2.0",
+    "polyfactory>=3.1.0",
+    "hypothesis>=6.148.3",
     "ipython>=9.7.0",
     "typer>=0.15.0",
 ]