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

anncsu_sdk-0.0.1.dev28/.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.dev28/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.4
+Name: anncsu-sdk
+Version: 0.0.1.dev28
+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
 
@@ -159,38 +173,176 @@ asyncio.run(main())
 
 All ANNCSU APIs use PDND (Piattaforma Digitale Nazionale Dati) voucher-based authentication with HTTP Bearer tokens.
 
-### Basic Authentication
+### Complete Authentication Flow
+
+The SDK supports the complete PDND authentication flow:
+
+```
+┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
+│  1. Create Client   │     │  2. Exchange for    │     │  3. Use Access      │
+│     Assertion       │────▶│     Access Token    │────▶│     Token           │
+│     (JWT)           │     │     (OAuth2)        │     │     (API Calls)     │
+└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
+```
 
 ```python
+from pathlib import Path
 from anncsu.pa import Anncsu
-from anncsu.common import Security
+from anncsu.common import (
+    # Step 1: Client Assertion
+    ClientAssertionConfig,
+    create_client_assertion,
+    # Step 2: Token Exchange
+    TokenConfig,
+    get_access_token,
+    # Step 3: API Authentication
+    Security,
+)
 
-# Create security configuration with your PDND voucher
-security = Security(bearer="your-pdnd-voucher-token")
+# Step 1: Create client assertion (JWT)
+assertion_config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="auth.uat.interop.pagopa.it/client-assertion",
+    purpose_id="your-purpose-id",
+    key_path=Path("./private_key.pem"),
+)
+client_assertion = create_client_assertion(assertion_config)
 
-# Initialize SDK with security
+# Step 2: Exchange for access token
+token_config = TokenConfig(
+    client_id="your-client-id",
+    client_assertion=client_assertion,
+    token_endpoint="https://auth.uat.interop.pagopa.it/token.oauth2",
+)
+token_response = get_access_token(token_config)
+
+# Step 3: Use access token for API calls
+security = Security(bearer=token_response.access_token)
 sdk = Anncsu(security=security)
 
-# Make authenticated requests
 response = sdk.queryparam.esiste_odonimo_get_query_param(
     codcom="H501",
     denom="VklBIFJPTUE="
 )
 ```
 
+### Basic Authentication (with existing token)
+
+If you already have an access token:
+
+```python
+from anncsu.pa import Anncsu
+from anncsu.common import Security
+
+security = Security(bearer="your-access-token")
+sdk = Anncsu(security=security)
+
+response = sdk.queryparam.esiste_odonimo_get_query_param(
+    codcom="H501",
+    denom="VklBIFJPTUE="
+)
+```
+
+### Token Expiration Validation
+
+The `Security` class automatically validates token expiration when initialized. If the token is expired, it raises `TokenExpiredError` instead of letting the API return a confusing 404 error:
+
+```python
+from anncsu.common import Security, TokenExpiredError
+
+try:
+    security = Security(bearer=token_response.access_token)
+except TokenExpiredError as e:
+    print(f"Token expired at {e.expired_at}, current time: {e.current_time}")
+    # Obtain a new access token...
+    token_response = get_access_token(token_config)
+    security = Security(bearer=token_response.access_token)
+```
+
+You can also check expiration manually:
+
+```python
+# Check if token is expired
+if security.is_expired():
+    print("Token needs refresh!")
+
+# Get seconds until expiration (negative if already expired)
+ttl = security.time_until_expiration()
+if ttl and ttl < 60:
+    print(f"Token expires in {ttl} seconds, consider refreshing")
+```
+
+To skip validation (not recommended):
+
+```python
+security = Security(bearer=expired_token, validate_expiration=False)
+```
+
 ### Key Features
 
-- **PDND Voucher**: Uses PDND (Piattaforma Digitale Nazionale Dati) authentication
+- **Complete Auth Flow**: Generate assertions, exchange for tokens, authenticate API calls
+- **PDND Voucher**: Full PDND (Piattaforma Digitale Nazionale Dati) authentication support
 - **Bearer Token**: JWT format tokens in Authorization header
-- **Common Security**: Same `Security` class works across all ANNCSU APIs
+- **Sync & Async**: Both `get_access_token` and `get_access_token_async` available
+- **Error Handling**: Dedicated exceptions for token errors (`TokenRequestError`, `TokenResponseError`)
 - **Type-Safe**: Full type hints with modern Python syntax
 
+### 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, TokenConfig, get_access_token, Security
+from anncsu.pa import Anncsu
+
+# Automatically loads from environment variables or .env file
+settings = ClientAssertionSettings()
+client_assertion = create_client_assertion(settings.to_config())
+
+# Exchange for access token
+token_response = get_access_token(TokenConfig(
+    client_id=settings.issuer,
+    client_assertion=client_assertion,
+    token_endpoint="https://auth.uat.interop.pagopa.it/token.oauth2",
+))
+
+# Use with SDK
+sdk = Anncsu(security=Security(bearer=token_response.access_token))
+```
+
+#### 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 - must end with `/client-assertion` |
+| `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=auth.uat.interop.pagopa.it/client-assertion
+PDND_PURPOSE_ID=my-purpose-id
+PDND_KEY_PATH=./private_key.pem
+```
+
 ### Documentation
 
 For comprehensive security documentation including:
-- PDND voucher format and JWT structure
+- Complete authentication flow (3 steps)
+- Token exchange parameters and error handling
+- Client assertion generation
 - Token refresh strategies
-- Error handling (401/403)
 - Best practices and security checklist
 - Testing with security
 
@@ -484,6 +636,119 @@ with Anncsu(
     print(res)
 
 ```
+
+### UAT Environment Configuration
+
+When working with the UAT (User Acceptance Testing) environment, you may need to configure a different server URL and handle SSL certificate issues.
+
+#### Basic UAT Configuration
+
+```python
+from anncsu.pa import Anncsu
+from anncsu.common import Security
+
+sdk = Anncsu(
+    security=Security(bearer_auth=token_response.access_token),
+    server_url="https://modipa-uat.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1",
+)
+```
+
+#### Disabling SSL Verification (UAT Only)
+
+The UAT environment may use certificates that are not trusted by your system's certificate store. To bypass SSL verification **for testing purposes only**:
+
+```python
+import httpx
+from anncsu.pa import Anncsu
+from anncsu.common import Security
+
+# Create HTTP client with SSL verification disabled
+client = httpx.Client(verify=False)
+
+sdk = Anncsu(
+    security=Security(bearer_auth=token_response.access_token),
+    server_url="https://modipa-uat.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1",
+    client=client,
+)
+
+# Make API calls
+response = sdk.queryparam.esiste_odonimo_get_query_param(
+    codcom="H501",
+    denom="VklBIFJPTUE="
+)
+```
+
+For async operations, also configure the async client:
+
+```python
+import httpx
+from anncsu.pa import Anncsu
+from anncsu.common import Security
+
+client = httpx.Client(verify=False)
+async_client = httpx.AsyncClient(verify=False)
+
+sdk = Anncsu(
+    security=Security(bearer_auth=token_response.access_token),
+    server_url="https://modipa-uat.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1",
+    client=client,
+    async_client=async_client,
+)
+```
+
+> **Warning**: Never disable SSL verification in production! This should only be used for UAT/testing environments where the server uses self-signed or untrusted certificates.
+
+#### Complete UAT Example
+
+Here's a complete example for UAT environment with PDND authentication:
+
+```python
+import httpx
+from pathlib import Path
+from anncsu.pa import Anncsu
+from anncsu.common import (
+    ClientAssertionConfig,
+    create_client_assertion,
+    TokenConfig,
+    get_access_token,
+    Security,
+)
+
+# Step 1: Create client assertion for UAT
+assertion_config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="auth.uat.interop.pagopa.it/client-assertion",  # UAT audience
+    purpose_id="your-purpose-id",
+    key_path=Path("./private_key.pem"),
+)
+client_assertion = create_client_assertion(assertion_config)
+
+# Step 2: Exchange for access token (UAT token endpoint)
+token_config = TokenConfig(
+    client_id="your-client-id",
+    client_assertion=client_assertion,
+    token_endpoint="https://auth.uat.interop.pagopa.it/token.oauth2",  # UAT endpoint
+)
+token_response = get_access_token(token_config)
+
+# Step 3: Create SDK with UAT configuration
+client = httpx.Client(verify=False)  # Only for UAT!
+
+sdk = Anncsu(
+    security=Security(bearer_auth=token_response.access_token),
+    server_url="https://modipa-uat.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1",
+    client=client,
+)
+
+# Step 4: Make API calls
+response = sdk.queryparam.esiste_odonimo_get_query_param(
+    codcom="H501",
+    denom="VklBIFJPTUE="
+)
+print(response)
+```
 <!-- End Server Selection [server] -->
 
 <!-- Start Custom HTTP Client [http-client] -->

anncsu_sdk-0.0.1.dev21/PKG-INFO → anncsu_sdk-0.0.1.dev28/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
 
@@ -172,38 +159,176 @@ asyncio.run(main())
 
 All ANNCSU APIs use PDND (Piattaforma Digitale Nazionale Dati) voucher-based authentication with HTTP Bearer tokens.
 
-### Basic Authentication
+### Complete Authentication Flow
+
+The SDK supports the complete PDND authentication flow:
+
+```
+┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
+│  1. Create Client   │     │  2. Exchange for    │     │  3. Use Access      │
+│     Assertion       │────▶│     Access Token    │────▶│     Token           │
+│     (JWT)           │     │     (OAuth2)        │     │     (API Calls)     │
+└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
+```
 
 ```python
+from pathlib import Path
 from anncsu.pa import Anncsu
-from anncsu.common import Security
+from anncsu.common import (
+    # Step 1: Client Assertion
+    ClientAssertionConfig,
+    create_client_assertion,
+    # Step 2: Token Exchange
+    TokenConfig,
+    get_access_token,
+    # Step 3: API Authentication
+    Security,
+)
 
-# Create security configuration with your PDND voucher
-security = Security(bearer="your-pdnd-voucher-token")
+# Step 1: Create client assertion (JWT)
+assertion_config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="auth.uat.interop.pagopa.it/client-assertion",
+    purpose_id="your-purpose-id",
+    key_path=Path("./private_key.pem"),
+)
+client_assertion = create_client_assertion(assertion_config)
 
-# Initialize SDK with security
+# Step 2: Exchange for access token
+token_config = TokenConfig(
+    client_id="your-client-id",
+    client_assertion=client_assertion,
+    token_endpoint="https://auth.uat.interop.pagopa.it/token.oauth2",
+)
+token_response = get_access_token(token_config)
+
+# Step 3: Use access token for API calls
+security = Security(bearer=token_response.access_token)
 sdk = Anncsu(security=security)
 
-# Make authenticated requests
 response = sdk.queryparam.esiste_odonimo_get_query_param(
     codcom="H501",
     denom="VklBIFJPTUE="
 )
 ```
 
+### Basic Authentication (with existing token)
+
+If you already have an access token:
+
+```python
+from anncsu.pa import Anncsu
+from anncsu.common import Security
+
+security = Security(bearer="your-access-token")
+sdk = Anncsu(security=security)
+
+response = sdk.queryparam.esiste_odonimo_get_query_param(
+    codcom="H501",
+    denom="VklBIFJPTUE="
+)
+```
+
+### Token Expiration Validation
+
+The `Security` class automatically validates token expiration when initialized. If the token is expired, it raises `TokenExpiredError` instead of letting the API return a confusing 404 error:
+
+```python
+from anncsu.common import Security, TokenExpiredError
+
+try:
+    security = Security(bearer=token_response.access_token)
+except TokenExpiredError as e:
+    print(f"Token expired at {e.expired_at}, current time: {e.current_time}")
+    # Obtain a new access token...
+    token_response = get_access_token(token_config)
+    security = Security(bearer=token_response.access_token)
+```
+
+You can also check expiration manually:
+
+```python
+# Check if token is expired
+if security.is_expired():
+    print("Token needs refresh!")
+
+# Get seconds until expiration (negative if already expired)
+ttl = security.time_until_expiration()
+if ttl and ttl < 60:
+    print(f"Token expires in {ttl} seconds, consider refreshing")
+```
+
+To skip validation (not recommended):
+
+```python
+security = Security(bearer=expired_token, validate_expiration=False)
+```
+
 ### Key Features
 
-- **PDND Voucher**: Uses PDND (Piattaforma Digitale Nazionale Dati) authentication
+- **Complete Auth Flow**: Generate assertions, exchange for tokens, authenticate API calls
+- **PDND Voucher**: Full PDND (Piattaforma Digitale Nazionale Dati) authentication support
 - **Bearer Token**: JWT format tokens in Authorization header
-- **Common Security**: Same `Security` class works across all ANNCSU APIs
+- **Sync & Async**: Both `get_access_token` and `get_access_token_async` available
+- **Error Handling**: Dedicated exceptions for token errors (`TokenRequestError`, `TokenResponseError`)
 - **Type-Safe**: Full type hints with modern Python syntax
 
+### 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, TokenConfig, get_access_token, Security
+from anncsu.pa import Anncsu
+
+# Automatically loads from environment variables or .env file
+settings = ClientAssertionSettings()
+client_assertion = create_client_assertion(settings.to_config())
+
+# Exchange for access token
+token_response = get_access_token(TokenConfig(
+    client_id=settings.issuer,
+    client_assertion=client_assertion,
+    token_endpoint="https://auth.uat.interop.pagopa.it/token.oauth2",
+))
+
+# Use with SDK
+sdk = Anncsu(security=Security(bearer=token_response.access_token))
+```
+
+#### 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 - must end with `/client-assertion` |
+| `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=auth.uat.interop.pagopa.it/client-assertion
+PDND_PURPOSE_ID=my-purpose-id
+PDND_KEY_PATH=./private_key.pem
+```
+
 ### Documentation
 
 For comprehensive security documentation including:
-- PDND voucher format and JWT structure
+- Complete authentication flow (3 steps)
+- Token exchange parameters and error handling
+- Client assertion generation
 - Token refresh strategies
-- Error handling (401/403)
 - Best practices and security checklist
 - Testing with security
 
@@ -497,6 +622,119 @@ with Anncsu(
     print(res)
 
 ```
+
+### UAT Environment Configuration
+
+When working with the UAT (User Acceptance Testing) environment, you may need to configure a different server URL and handle SSL certificate issues.
+
+#### Basic UAT Configuration
+
+```python
+from anncsu.pa import Anncsu
+from anncsu.common import Security
+
+sdk = Anncsu(
+    security=Security(bearer_auth=token_response.access_token),
+    server_url="https://modipa-uat.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1",
+)
+```
+
+#### Disabling SSL Verification (UAT Only)
+
+The UAT environment may use certificates that are not trusted by your system's certificate store. To bypass SSL verification **for testing purposes only**:
+
+```python
+import httpx
+from anncsu.pa import Anncsu
+from anncsu.common import Security
+
+# Create HTTP client with SSL verification disabled
+client = httpx.Client(verify=False)
+
+sdk = Anncsu(
+    security=Security(bearer_auth=token_response.access_token),
+    server_url="https://modipa-uat.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1",
+    client=client,
+)
+
+# Make API calls
+response = sdk.queryparam.esiste_odonimo_get_query_param(
+    codcom="H501",
+    denom="VklBIFJPTUE="
+)
+```
+
+For async operations, also configure the async client:
+
+```python
+import httpx
+from anncsu.pa import Anncsu
+from anncsu.common import Security
+
+client = httpx.Client(verify=False)
+async_client = httpx.AsyncClient(verify=False)
+
+sdk = Anncsu(
+    security=Security(bearer_auth=token_response.access_token),
+    server_url="https://modipa-uat.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1",
+    client=client,
+    async_client=async_client,
+)
+```
+
+> **Warning**: Never disable SSL verification in production! This should only be used for UAT/testing environments where the server uses self-signed or untrusted certificates.
+
+#### Complete UAT Example
+
+Here's a complete example for UAT environment with PDND authentication:
+
+```python
+import httpx
+from pathlib import Path
+from anncsu.pa import Anncsu
+from anncsu.common import (
+    ClientAssertionConfig,
+    create_client_assertion,
+    TokenConfig,
+    get_access_token,
+    Security,
+)
+
+# Step 1: Create client assertion for UAT
+assertion_config = ClientAssertionConfig(
+    kid="your-key-id",
+    issuer="your-client-id",
+    subject="your-client-id",
+    audience="auth.uat.interop.pagopa.it/client-assertion",  # UAT audience
+    purpose_id="your-purpose-id",
+    key_path=Path("./private_key.pem"),
+)
+client_assertion = create_client_assertion(assertion_config)
+
+# Step 2: Exchange for access token (UAT token endpoint)
+token_config = TokenConfig(
+    client_id="your-client-id",
+    client_assertion=client_assertion,
+    token_endpoint="https://auth.uat.interop.pagopa.it/token.oauth2",  # UAT endpoint
+)
+token_response = get_access_token(token_config)
+
+# Step 3: Create SDK with UAT configuration
+client = httpx.Client(verify=False)  # Only for UAT!
+
+sdk = Anncsu(
+    security=Security(bearer_auth=token_response.access_token),
+    server_url="https://modipa-uat.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1",
+    client=client,
+)
+
+# Step 4: Make API calls
+response = sdk.queryparam.esiste_odonimo_get_query_param(
+    codcom="H501",
+    denom="VklBIFJPTUE="
+)
+print(response)
+```
 <!-- End Server Selection [server] -->
 
 <!-- Start Custom HTTP Client [http-client] -->