anncsu-sdk 0.0.9.dev13__tar.gz → 0.0.9.dev14__tar.gz

{anncsu_sdk-0.0.9.dev13 → anncsu_sdk-0.0.9.dev14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anncsu-sdk
-Version: 0.0.9.dev13
+Version: 0.0.9.dev14
 Summary: ANNCSU Software Development Kit for API consumption
 Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
 License-File: LICENSE

{anncsu_sdk-0.0.9.dev13 → anncsu_sdk-0.0.9.dev14}/docs/CLI.md

@@ -904,12 +904,12 @@ Supports resumable multi-day execution with `--resume` to respect the daily limi
 
 ```bash
 # First run (day 1): process up to 4000 records
+# --production auto-selects the production token endpoint.
 anncsu coordinate duckdb-batch-update \
   --db ~/Downloads/anncsu_anagni/A269.duckdb \
   --source-table deoverlapped_geocoded_anncsu_prepared \
   --codcom A269 \
   --production \
-  --token-endpoint https://auth.interop.pagopa.it/token.oauth2 \
   --max-records 4000
 
 # Day 2: resume with same run ID
@@ -918,7 +918,6 @@ anncsu coordinate duckdb-batch-update \
   --source-table deoverlapped_geocoded_anncsu_prepared \
   --codcom A269 \
   --production \
-  --token-endpoint https://auth.interop.pagopa.it/token.oauth2 \
   --max-records 4000 \
   --resume 20260319_140554
 
@@ -928,7 +927,6 @@ anncsu coordinate duckdb-batch-update \
   --source-table deoverlapped_geocoded_anncsu_prepared \
   --codcom A269 \
   --production \
-  --token-endpoint https://auth.interop.pagopa.it/token.oauth2 \
   --resume 20260319_140554
 ```
 
@@ -1683,9 +1681,8 @@ Search streets (odonimi) in a municipality by partial name.
 # Search streets in Scanno (I501)
 anncsu pa odonimo --codcom I501 --denom "VklBIFJPTUE="
 
-# Production environment
-anncsu pa odonimo --codcom I501 --denom "VklBIFJPTUE=" --production \
-  --token-endpoint https://auth.interop.pagopa.it/token.oauth2
+# Production environment (--production auto-selects the production token endpoint)
+anncsu pa odonimo --codcom I501 --denom "VklBIFJPTUE=" --production
 
 # JSON output
 anncsu pa odonimo --codcom I501 --denom "VklBIFJPTUE=" --json
@@ -1715,8 +1712,7 @@ Lookup a single access point by its national progressive number. Returns complet
 anncsu pa accesso --prognazacc 28586543
 
 # Production with JSON output
-anncsu pa accesso --prognazacc 28586543 --production \
-  --token-endpoint https://auth.interop.pagopa.it/token.oauth2 --json
+anncsu pa accesso --prognazacc 28586543 --production --json
 
 # See raw API response on stderr
 anncsu pa accesso --prognazacc 28586543 --raw
@@ -1774,8 +1770,7 @@ anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE="
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --accparz "1"
 
 # Production with JSON output
-anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production \
-  --token-endpoint https://auth.interop.pagopa.it/token.oauth2 --json
+anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 ```
 
 **Options:**
@@ -2185,6 +2180,8 @@ The ANNCSU APIs are exposed through the GovWay gateway on two environments. Each
 | UAT (Validation) | `https://auth.uat.interop.pagopa.it/token.oauth2` | `https://modipa-val.agenziaentrate.it/govway/rest/in` |
 | Production | `https://auth.interop.pagopa.it/token.oauth2` | `https://modipa.agenziaentrate.gov.it/govway/rest/in` |
 
+> **Note on `--token-endpoint`**: every CLI command that supports `--validation/--production` picks the token endpoint automatically based on that flag if `--token-endpoint` is omitted. You can still pass `--token-endpoint` explicitly — the CLI then validates that it matches the selected environment and exits with an error if it does not (preventing the silent `015-0008 Unable to generate a token` failure when the two diverge).
+
 ### API Types and GovWay Paths
 
 Each API type corresponds to a distinct PDND e-service with its own GovWay path and purpose ID:

{anncsu_sdk-0.0.9.dev13 → anncsu_sdk-0.0.9.dev14}/src/anncsu/cli/commands/accesso.py

@@ -34,6 +34,7 @@ from anncsu.accessi.models.richiestaoperazione import (
     Richiesta,
 )
 from anncsu.accessi.models.validated import ValidatedAccesso
+from anncsu.cli.commands.constants import _resolve_token_endpoint
 from anncsu.cli.models import (
     AccessoDryRunResult,
     AccessoOperationResult,
@@ -58,9 +59,6 @@ accesso_app = typer.Typer(
 console = Console()
 error_console = Console(stderr=True)
 
-# Default token endpoint for UAT (matches the pattern used in coordinate.py).
-DEFAULT_TOKEN_ENDPOINT = "https://auth.uat.interop.pagopa.it/token.oauth2"
-
 # Default server URLs for the Accessi e-service.
 # The OAS spec lists path ``AgenziaEntrate/anncsuaccessi/v1`` but real
 # GovWay paths often differ — voucher audience auto-discovery corrects the
@@ -1121,9 +1119,16 @@ def insert(
         ),
     ] = None,
     token_endpoint: Annotated[
-        str,
-        typer.Option("--token-endpoint", "-e", help="PDND token endpoint URL."),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+        str | None,
+        typer.Option(
+            "--token-endpoint",
+            "-e",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
+        ),
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option(
@@ -1188,6 +1193,7 @@ def insert(
         data_valid_amm=data_valid_amm,
     )
 
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
     resolved_server = _resolve_server_url(server_url, validation_env)
 
     if dry_run:
@@ -1310,9 +1316,16 @@ def update(
         ),
     ] = None,
     token_endpoint: Annotated[
-        str,
-        typer.Option("--token-endpoint", "-e", help="PDND token endpoint URL."),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+        str | None,
+        typer.Option(
+            "--token-endpoint",
+            "-e",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
+        ),
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option("--server-url", "-s", help="API server URL."),
@@ -1354,6 +1367,10 @@ def update(
             --progr-civico 1370588 --numero 12
     """
     # Resolve progr_civico either explicitly or via PA lookup.
+    # Resolve token endpoint up-front: --auto-resolve below also uses it
+    # (via PA consultation SDK), so it must be the right environment.
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
+
     if auto_resolve:
         if not civico:
             error_console.print(
@@ -1471,9 +1488,16 @@ def delete(
         ),
     ] = None,
     token_endpoint: Annotated[
-        str,
-        typer.Option("--token-endpoint", "-e", help="PDND token endpoint URL."),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+        str | None,
+        typer.Option(
+            "--token-endpoint",
+            "-e",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
+        ),
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option("--server-url", "-s", help="API server URL."),
@@ -1519,6 +1543,10 @@ def delete(
         anncsu accesso delete --codcom A062 --prognaz 2000449 \\
             --progr-civico 1370588
     """
+    # Resolve token endpoint up-front: --auto-resolve below also uses it
+    # (via PA consultation SDK), so it must be the right environment.
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
+
     # Resolve progr_civico either explicitly or via PA lookup.
     if auto_resolve:
         if not civico:
@@ -1583,9 +1611,16 @@ def delete(
 @accesso_app.command("status")
 def status(
     token_endpoint: Annotated[
-        str,
-        typer.Option("--token-endpoint", "-e", help="PDND token endpoint URL."),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+        str | None,
+        typer.Option(
+            "--token-endpoint",
+            "-e",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
+        ),
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option("--server-url", "-s", help="API server URL."),
@@ -1609,6 +1644,7 @@ def status(
     ] = False,
 ) -> None:
     """Check the Accessi API health (GET ``/status``)."""
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
     resolved_url = _resolve_server_url(server_url, validation_env)
     # status is a GET, no ModI signature needed → omit modi_audience.
     sdk, _ = _get_sdk(

{anncsu_sdk-0.0.9.dev13 → anncsu_sdk-0.0.9.dev14}/src/anncsu/cli/commands/auth.py

@@ -12,6 +12,7 @@ import typer
 from rich.console import Console
 from rich.table import Table
 
+from anncsu.cli.commands.constants import _resolve_token_endpoint
 from anncsu.cli.models import AuthStatus, CurlOutput, LoginResult, TokenStatus
 from anncsu.common import PDNDAuthManager
 from anncsu.common.config import APIType, ClientAssertionSettings
@@ -567,13 +568,16 @@ def curl_command(
         ),
     ],
     token_endpoint: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--token-endpoint",
             "-e",
-            help="PDND token endpoint URL.",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
         ),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+    ] = None,
     validation_env: Annotated[
         bool,
         typer.Option(
@@ -668,6 +672,7 @@ def curl_command(
 
     api_type = _get_api_type()
     env_name = "validation" if validation_env else "production"
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
     curl_warnings: list[str] = []
 
     if endpoint is not None and api_type != APIType.PA:

{anncsu_sdk-0.0.9.dev13 → anncsu_sdk-0.0.9.dev14}/src/anncsu/cli/commands/bulk.py

@@ -19,6 +19,7 @@ from rich.progress import (
 )
 from rich.table import Table
 
+from anncsu.cli.commands.constants import _resolve_token_endpoint
 from anncsu.common.session import get_config_dir
 from anncsu.coordinate.bulk.db import BulkDB
 from anncsu.coordinate.bulk.executor import (
@@ -234,9 +235,16 @@ def bulk_update(
         ),
     ],
     token_endpoint: Annotated[
-        str,
-        typer.Option("--token-endpoint", "-e", help="PDND token endpoint URL."),
-    ] = "https://auth.uat.interop.pagopa.it/token.oauth2",
+        str | None,
+        typer.Option(
+            "--token-endpoint",
+            "-e",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
+        ),
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option("--server-url", "-s", help="API server URL."),
@@ -271,6 +279,7 @@ def bulk_update(
         anncsu coordinate bulk update input.csv --max-records 1000
         anncsu coordinate bulk update input.csv --json
     """
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
     coord_server, _ = _resolve_servers(validation_env, server_url)
 
     try:
@@ -451,9 +460,16 @@ def bulk_dry_run(
         typer.Option("--max-records", "-n", help="Maximum records to test."),
     ] = 10,
     token_endpoint: Annotated[
-        str,
-        typer.Option("--token-endpoint", "-e", help="PDND token endpoint URL."),
-    ] = "https://auth.uat.interop.pagopa.it/token.oauth2",
+        str | None,
+        typer.Option(
+            "--token-endpoint",
+            "-e",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
+        ),
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option("--server-url", "-s", help="API server URL."),
@@ -486,6 +502,7 @@ def bulk_dry_run(
     """
     from anncsu.coordinate.bulk.dryrun import BulkDryRunner
 
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
     coord_server, consult_server = _resolve_servers(validation_env, server_url)
 
     try:
@@ -632,9 +649,16 @@ def resume(
         typer.Argument(help="Run ID to resume."),
     ],
     token_endpoint: Annotated[
-        str,
-        typer.Option("--token-endpoint", "-e", help="PDND token endpoint URL."),
-    ] = "https://auth.uat.interop.pagopa.it/token.oauth2",
+        str | None,
+        typer.Option(
+            "--token-endpoint",
+            "-e",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
+        ),
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option("--server-url", "-s", help="API server URL."),
@@ -666,6 +690,7 @@ def resume(
     Example:
         anncsu coordinate bulk resume abc123-def456
     """
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
     coord_server, _ = _resolve_servers(validation_env, server_url)
 
     db_file = _find_db_for_run(run_id)

anncsu_sdk-0.0.9.dev14/src/anncsu/cli/commands/constants.py

@@ -0,0 +1,74 @@
+# SPDX-FileCopyrightText: 2025-present Geobeyond <info@geobeyond.it>
+# SPDX-License-Identifier: MIT
+"""Shared constants and helpers for CLI commands."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+# PDND token endpoints
+UAT_TOKEN_ENDPOINT = "https://auth.uat.interop.pagopa.it/token.oauth2"
+PROD_TOKEN_ENDPOINT = "https://auth.interop.pagopa.it/token.oauth2"
+
+# Backward-compatible alias used by callers that imported the old name.
+DEFAULT_TOKEN_ENDPOINT = UAT_TOKEN_ENDPOINT
+
+# Default server URLs for coordinate API
+# Note: Uses AgenziaEntrate-PDND path and anncsu-aggiornamento-coordinate endpoint
+SERVERS = {
+    "production": "https://modipa.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-aggiornamento-coordinate/v1",
+    "validation": "https://modipa-val.agenziaentrate.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-aggiornamento-coordinate/v1",
+}
+
+
+_error_console = Console(stderr=True)
+
+
+def _is_uat_endpoint(token_endpoint: str) -> bool:
+    """True if the endpoint URL points to the UAT PDND environment.
+
+    The UAT host contains the ``.uat.`` segment; production does not.
+    """
+    return ".uat." in token_endpoint
+
+
+def _resolve_token_endpoint(token_endpoint: str | None, validation_env: bool) -> str:
+    """Resolve the PDND token endpoint based on the environment flag.
+
+    Behavior:
+
+    * If ``token_endpoint`` is ``None`` (user did not pass ``--token-endpoint``),
+      return the default for ``validation_env``: UAT when True, production when
+      False.
+    * If ``token_endpoint`` is set, validate that its environment matches
+      ``validation_env``. On mismatch, print an error and raise ``typer.Exit(1)``
+      so the user gets an explicit parameter validation error instead of an
+      opaque 015-0008 from PDND at runtime.
+    """
+    if token_endpoint is None:
+        return UAT_TOKEN_ENDPOINT if validation_env else PROD_TOKEN_ENDPOINT
+
+    endpoint_is_uat = _is_uat_endpoint(token_endpoint)
+
+    if validation_env and not endpoint_is_uat:
+        _error_console.print(
+            "[red]Error:[/red] environment mismatch — "
+            "--validation was selected but --token-endpoint points to "
+            f"a non-UAT host ({token_endpoint}). "
+            "Pass --production for the production endpoint, or omit "
+            "--token-endpoint to use the UAT default."
+        )
+        raise typer.Exit(1)
+
+    if not validation_env and endpoint_is_uat:
+        _error_console.print(
+            "[red]Error:[/red] environment mismatch — "
+            "--production was selected but --token-endpoint points to "
+            f"the UAT host ({token_endpoint}). "
+            "Pass --validation for the UAT endpoint, or omit "
+            "--token-endpoint to use the production default."
+        )
+        raise typer.Exit(1)
+
+    return token_endpoint

{anncsu_sdk-0.0.9.dev13 → anncsu_sdk-0.0.9.dev14}/src/anncsu/cli/commands/coordinate.py

@@ -20,7 +20,11 @@ from rich.progress import (
 from rich.table import Table
 
 from anncsu.cli.commands.bulk import bulk_app
-from anncsu.cli.commands.constants import DEFAULT_TOKEN_ENDPOINT, SERVERS
+from anncsu.cli.commands.constants import (
+    DEFAULT_TOKEN_ENDPOINT,
+    SERVERS,
+    _resolve_token_endpoint,
+)
 from anncsu.cli.models import (
     CoordinateStatusResult,
     CoordinateUpdateResult,
@@ -386,13 +390,16 @@ def update(
         ),
     ] = None,
     token_endpoint: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--token-endpoint",
             "-e",
-            help="PDND token endpoint URL.",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
         ),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option(
@@ -432,6 +439,7 @@ def update(
     # Determine server URL
     if server_url is None:
         server_url = SERVERS["validation"] if validation_env else SERVERS["production"]
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
 
     # Create SDK with ModI hook (modi_audience is the API base URL)
     # The hook automatically adds Digest, Agid-JWT-Signature, and
@@ -547,13 +555,16 @@ def dry_run(
         ),
     ] = None,
     token_endpoint: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--token-endpoint",
             "-e",
-            help="PDND token endpoint URL.",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
         ),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option(
@@ -662,6 +673,10 @@ def dry_run(
         )
         raise typer.Exit(1) from None
 
+    # Resolve token endpoint up-front: it's used by both the consult and
+    # the coordinate SDKs below, so it must be set before any SDK init.
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
+
     # Determine server URLs
     coord_server = server_url or (
         SERVERS["validation"] if validation_env else SERVERS["production"]
@@ -1120,6 +1135,7 @@ def duckdb_batch_update(
     # Determine server URL
     if server_url is None:
         server_url = SERVERS["validation"] if validation_env else SERVERS["production"]
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
 
     # Create results table
     _create_results_table(db_path)
@@ -1420,13 +1436,16 @@ def duckdb_batch_update(
 @coordinate_app.command("status")
 def status(
     token_endpoint: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--token-endpoint",
             "-e",
-            help="PDND token endpoint URL.",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
         ),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option(
@@ -1467,6 +1486,7 @@ def status(
     # Determine server URL
     if server_url is None:
         server_url = SERVERS["validation"] if validation_env else SERVERS["production"]
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
 
     # Create SDK (no ModI needed for status - GET request, hook will skip it)
     sdk, _ = _get_sdk(

{anncsu_sdk-0.0.9.dev13 → anncsu_sdk-0.0.9.dev14}/src/anncsu/cli/commands/pa.py

@@ -10,9 +10,9 @@ import typer
 from rich.console import Console
 from rich.table import Table
 
+from anncsu.cli.commands.constants import _resolve_token_endpoint
 from anncsu.cli.commands.coordinate import (
     CONSULT_SERVERS,
-    DEFAULT_TOKEN_ENDPOINT,
     _get_consult_sdk,
 )
 
@@ -63,13 +63,16 @@ def odonimo(
         ),
     ] = None,
     token_endpoint: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--token-endpoint",
             "-e",
-            help="PDND token endpoint URL.",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
         ),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option(
@@ -128,6 +131,7 @@ def odonimo(
             if validation_env
             else CONSULT_SERVERS["production"]
         )
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
 
     sdk = _get_consult_sdk(
         token_endpoint=token_endpoint,
@@ -226,13 +230,16 @@ def accesso(
         ),
     ],
     token_endpoint: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--token-endpoint",
             "-e",
-            help="PDND token endpoint URL.",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
         ),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option(
@@ -279,6 +286,7 @@ def accesso(
             if validation_env
             else CONSULT_SERVERS["production"]
         )
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
 
     sdk = _get_consult_sdk(
         token_endpoint=token_endpoint,
@@ -368,13 +376,16 @@ def accessi(
         ),
     ] = None,
     token_endpoint: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--token-endpoint",
             "-e",
-            help="PDND token endpoint URL.",
+            help=(
+                "PDND token endpoint URL. If omitted, defaults to UAT or "
+                "production based on --validation/--production."
+            ),
         ),
-    ] = DEFAULT_TOKEN_ENDPOINT,
+    ] = None,
     server_url: Annotated[
         str | None,
         typer.Option(
@@ -421,6 +432,7 @@ def accessi(
             if validation_env
             else CONSULT_SERVERS["production"]
         )
+    token_endpoint = _resolve_token_endpoint(token_endpoint, validation_env)
 
     sdk = _get_consult_sdk(
         token_endpoint=token_endpoint,

anncsu_sdk-0.0.9.dev14/tests/cli/test_token_endpoint_resolution.py

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: 2025-present Geobeyond <info@geobeyond.it>
+# SPDX-License-Identifier: MIT
+"""Tests for the ``_resolve_token_endpoint`` helper.
+
+Maps the ``--validation/--production`` flag to the corresponding PDND token
+endpoint when the user does not pass ``--token-endpoint`` explicitly, and
+validates the match (exit 1 on mismatch) when both are provided.
+"""
+
+from __future__ import annotations
+
+import pytest
+import typer
+
+
+UAT = "https://auth.uat.interop.pagopa.it/token.oauth2"
+PROD = "https://auth.interop.pagopa.it/token.oauth2"
+
+
+class TestResolveTokenEndpointDefaults:
+    """When ``token_endpoint is None``, pick the default per environment."""
+
+    def test_validation_default_returns_uat(self) -> None:
+        from anncsu.cli.commands.constants import _resolve_token_endpoint
+
+        assert _resolve_token_endpoint(None, validation_env=True) == UAT
+
+    def test_production_default_returns_prod(self) -> None:
+        from anncsu.cli.commands.constants import _resolve_token_endpoint
+
+        assert _resolve_token_endpoint(None, validation_env=False) == PROD
+
+
+class TestResolveTokenEndpointExplicitMatch:
+    """When the explicit endpoint matches the environment flag, accept it."""
+
+    def test_validation_with_explicit_uat_endpoint_ok(self) -> None:
+        from anncsu.cli.commands.constants import _resolve_token_endpoint
+
+        assert _resolve_token_endpoint(UAT, validation_env=True) == UAT
+
+    def test_production_with_explicit_prod_endpoint_ok(self) -> None:
+        from anncsu.cli.commands.constants import _resolve_token_endpoint
+
+        assert _resolve_token_endpoint(PROD, validation_env=False) == PROD
+
+
+class TestResolveTokenEndpointExplicitMismatch:
+    """When the explicit endpoint conflicts with the environment flag, exit 1."""
+
+    def test_validation_with_explicit_prod_endpoint_errors(self, capsys) -> None:
+        from anncsu.cli.commands.constants import _resolve_token_endpoint
+
+        with pytest.raises(typer.Exit) as exc_info:
+            _resolve_token_endpoint(PROD, validation_env=True)
+        assert exc_info.value.exit_code == 1
+        # Error message must mention both --validation and the production
+        # endpoint, so the user can fix the invocation without guessing.
+        captured = capsys.readouterr()
+        combined = (captured.out + captured.err).lower()
+        assert "mismatch" in combined or "conflict" in combined
+        assert "--validation" in combined or "validation" in combined
+
+    def test_production_with_explicit_uat_endpoint_errors(self, capsys) -> None:
+        from anncsu.cli.commands.constants import _resolve_token_endpoint
+
+        with pytest.raises(typer.Exit) as exc_info:
+            _resolve_token_endpoint(UAT, validation_env=False)
+        assert exc_info.value.exit_code == 1
+        captured = capsys.readouterr()
+        combined = (captured.out + captured.err).lower()
+        assert "mismatch" in combined or "conflict" in combined
+        assert "--production" in combined or "production" in combined