datamasque-python 1.1.3__py3-none-any.whl → 1.1.5__py3-none-any.whl

datamasque/client/base.py

@@ -21,6 +21,7 @@ from datamasque.client.exceptions import (
     DataMasqueTransportError,
 )
 from datamasque.client.models.dm_instance import DataMasqueInstanceConfig
+from datamasque.client.spcs import install_spcs_gateway_auth
 
 logger = logging.getLogger(__name__)
 
@@ -137,6 +138,8 @@ class BaseClient:
         self.verify_ssl = connection_config.verify_ssl
         self.token_source = connection_config.token_source
         self._session = _build_session(self.verify_ssl)
+        if connection_config.spcs_pat:
+            install_spcs_gateway_auth(self._session, connection_config.spcs_pat)
 
     @contextmanager
     def _maybe_suppress_insecure_warning(self) -> Iterator[None]:

datamasque/client/exceptions.py

@@ -84,6 +84,22 @@ class IfmAuthError(DataMasqueIfmError):
     """Raised when the IFM client cannot obtain or refresh a JWT (e.g. invalid credentials, missing scope)."""
 
 
+class SpcsGatewayAuthError(DataMasqueException):
+    """
+    Raised when a Snowflake SPCS app gateway rejects the configured `spcs_pat`.
+
+    The message includes the Snowflake-provided detail, request id,
+    and a hint at the likely cause
+    (for example an expired token, or a network policy that excludes your IP).
+
+    Deliberately a direct subclass of `DataMasqueException` rather than
+    `DataMasqueApiError`:
+    the client's 401 re-authenticate-and-retry path keys off `DataMasqueApiError`,
+    so keeping this outside that subtree
+    ensures a gateway rejection aborts immediately instead of looping.
+    """
+
+
 class RunNotCancellableError(DataMasqueUserError):
     """
     Raised when `cancel_run` is called against a run that is no longer eligible for cancellation.

datamasque/client/models/connection.py

@@ -48,6 +48,7 @@ class DatabaseType(Enum):
     databricks_lakebase = "databricks_lakebase"
     databricks = "databricks"
     informix = "informix"
+    saphana = "saphana"
 
 
 class SnowflakeStageLocation(str, Enum):
@@ -56,6 +57,7 @@ class SnowflakeStageLocation(str, Enum):
     local = "local"  # Not supported for production use
     aws_s3 = "aws_s3"
     azure_blob_storage = "azure_blob_storage"
+    spcs = "spcs"  # DataMasque running inside Snowflake SPCS; staged on the container's own storage
 
 
 class SseSelection(Enum):
@@ -233,10 +235,14 @@ class SnowflakeConnectionConfig(ConnectionConfig):
     """
 
     database: str
-    user: str
-    snowflake_account_id: str
-    snowflake_warehouse: str
-    snowflake_storage_integration_name: str
+    # Optional because DataMasque-in-SPCS connections leave these unset: the agent uses the
+    # container's OAuth token + SNOWFLAKE_HOST/SNOWFLAKE_ACCOUNT env and the app-owned QUERY_WAREHOUSE,
+    # so user/account/storage-integration/warehouse are null for stage_location=spcs. Mirrors the app's
+    # canonical model (agent .../schemas/connection/connection.py), which types these `| None = None`.
+    user: Optional[str] = None
+    snowflake_account_id: Optional[str] = None
+    snowflake_warehouse: Optional[str] = None
+    snowflake_storage_integration_name: Optional[str] = None
     host: str = ""
     port: Optional[int] = None
     db_schema: Optional[str] = Field(default=None, alias="schema")

datamasque/client/models/dm_instance.py

@@ -20,6 +20,11 @@ class DataMasqueInstanceConfig(BaseModel):
     the client prepends it with `Token ` when sending the `Authorization` header.
     The client calls `token_source` on each authentication attempt,
     so the callable is free to fetch and refresh tokens out-of-band (e.g. from a secrets manager).
+
+    `spcs_pat` is an optional Snowflake Programmatic Access Token
+    for reaching a DataMasque instance hosted on Snowpark Container Services (SPCS).
+    It layers underneath whichever DataMasque auth method
+    (`password` or `token_source`) you choose.
     """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
@@ -29,6 +34,14 @@ class DataMasqueInstanceConfig(BaseModel):
     password: Optional[str] = None
     verify_ssl: bool = True
     token_source: Optional[Callable[[], str]] = None
+    spcs_pat: Optional[str] = None
+    """Snowflake Programmatic Access Token
+    for a DataMasque instance hosted on Snowpark Container Services (SPCS),
+    where `base_url` ends in `.snowflakecomputing.app`.
+
+    Create the token in Snowsight (User profile → Programmatic access tokens)
+    for an account that can reach the SPCS app.
+    Leave unset for instances that are not hosted on SPCS."""
 
     @model_validator(mode="after")
     def _validate_auth_source(self) -> "DataMasqueInstanceConfig":

datamasque/client/spcs.py

@@ -0,0 +1,179 @@
+"""
+Snowflake SPCS app gateway authentication for `DataMasqueClient`.
+
+When a DataMasque instance is hosted on Snowpark Container Services (SPCS),
+its app ingress (`*.snowflakecomputing.app`) fronts every request
+with a Snowflake gateway that must be cleared first.
+We authenticate to the gateway with a Programmatic Access Token (PAT),
+sent on `X-SF-SPCS-Authorization: Snowflake Token="<PAT>"`.
+The gateway accepts the PAT on this alternate header
+and strips it before forwarding to the container,
+so DataMasque's own `Authorization: Token <key>` flow rides through untouched.
+
+`install_spcs_gateway_auth` attaches this behaviour to a client's `requests.Session`:
+it sets the header on the session
+(so it is sent on every request, including the unauthenticated login)
+and registers a response hook
+that turns a gateway-originated rejection into a clear `SpcsGatewayAuthError`.
+"""
+
+import re
+from typing import Any, Optional
+
+import requests
+
+from datamasque.client.exceptions import SpcsGatewayAuthError
+
+SPCS_GATEWAY_AUTH_HEADER = "X-SF-SPCS-Authorization"
+
+# Body-shape discriminators for SPCS gateway error responses.
+# The gateway emits JSON with `responseType` (ERROR_<UPPER_SNAKE>), `requestId`
+# (canonical UUID), and `detail` (free text). All three must be present and
+# match these patterns for the body to count as gateway-originated.
+_GATEWAY_RESPONSE_TYPE_RE = re.compile(r"^ERROR_[A-Z][A-Z0-9_]+$")
+_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+
+# Header-shape discriminators for "this response transited a Snowflake SPCS
+# gateway". The Server header and the `sfc-ss-` cookie name prefix both appear
+# on every gateway-handled response (success and error alike) and aren't
+# plausible to spoof by accident.
+_SPCS_GATEWAY_SERVER_VALUE = "_"
+_SPCS_COOKIE_PREFIX = "sfc-ss-"
+
+
+def _has_spcs_gateway_header_signature(response: requests.Response) -> bool:
+    """
+    True if at least one header-level Snowflake gateway marker is present.
+
+    Looks for either `Server: _` (the gateway's literal Server header value)
+    or any `Set-Cookie` carrying the `sfc-ss-` cookie name prefix.
+    Either is sufficient — both indicate the response was emitted by,
+    or transited, Snowflake's SPCS ingress.
+    """
+    if response.headers.get("server", "").strip() == _SPCS_GATEWAY_SERVER_VALUE:
+        return True
+    # `Set-Cookie` may appear multiple times; `requests` flattens duplicates
+    # via a comma-separated value in `.headers`, but our prefix substring
+    # check is order- and count-insensitive.
+    return _SPCS_COOKIE_PREFIX in response.headers.get("set-cookie", "")
+
+
+def _is_spcs_gateway_error_body(response: requests.Response) -> Optional[dict]:
+    """
+    Return the parsed body iff it is a structurally-valid gateway error.
+
+    All four conditions must hold:
+      1. The body parses as JSON and is a dict.
+      2. Keys `responseType`, `requestId`, `detail` are all present and string-typed.
+      3. `responseType` matches `^ERROR_<UPPER_SNAKE>$`.
+      4. `requestId` is a canonical 8-4-4-4-12 UUID.
+
+    Returns the parsed dict (truthy) on match, `None` on miss.
+    """
+    try:
+        data = response.json()
+    except ValueError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    response_type = data.get("responseType")
+    request_id = data.get("requestId")
+    detail = data.get("detail")
+    if not (isinstance(response_type, str) and isinstance(request_id, str) and isinstance(detail, str)):
+        return None
+    if _GATEWAY_RESPONSE_TYPE_RE.match(response_type) and _UUID_RE.match(request_id):
+        return data
+    return None
+
+
+def _hint_for_gateway_detail(detail: str) -> str:
+    """Map common Snowflake gateway `detail` strings to a one-line cause hint."""
+    d = (detail or "").lower()
+    if "network policy" in d:
+        return (
+            "PAT requires a network policy attached to the user (or account) "
+            "that permits your current public IP. Run `CREATE NETWORK POLICY "
+            "... ALLOWED_IP_LIST = ('<your.ip>/32')` and `ALTER USER <pat-user> "
+            "SET NETWORK_POLICY = <policy>`."
+        )
+    if "invalid" in d and "token" in d:
+        return (
+            "PAT is malformed, expired, or revoked. Create a new PAT in Snowsight "
+            "(User profile -> Programmatic access tokens) and update `spcs_pat`."
+        )
+    if "expired" in d:
+        return "PAT has expired. Create a fresh one in Snowsight and update `spcs_pat`."
+    if "authentication" in d or "unauthorized" in d:
+        return (
+            "Generic auth rejection. Verify the PAT was created by a user that "
+            "has access to this SPCS app, and that any account-level network "
+            "policy includes your current public IP."
+        )
+    return "Unknown gateway rejection — see the Snowflake `detail` string above and the Snowflake PAT docs."
+
+
+def _check_spcs_gateway_response(response: requests.Response) -> None:
+    """
+    Raise `SpcsGatewayAuthError` iff `response` is a gateway-originated rejection.
+
+    Two-layer discriminator — both must hold:
+      * **Body originated at the gateway**:
+        strict shape match on the JSON body
+        (multiple fields, typed, with format constraints)
+        via `_is_spcs_gateway_error_body`.
+      * **Response transited an SPCS gateway**:
+        header signature confirms via `_has_spcs_gateway_header_signature`.
+
+    Either layer alone could in principle false-positive on an unrelated upstream
+    that happened to emit one of those signals;
+    the conjunction is what makes the check robust.
+    Legitimate DataMasque 401s (DRF `{"detail": "..."}`)
+    have the gateway header signature but fail the body shape —
+    so they correctly flow through
+    to the client's normal re-auth-and-retry path untouched.
+    """
+    if response.status_code not in (401, 403):
+        return
+    if not _has_spcs_gateway_header_signature(response):
+        return
+    data = _is_spcs_gateway_error_body(response)
+    if data is None:
+        return
+
+    response_type = data["responseType"]
+    request_id = data["requestId"]
+    detail = data["detail"]
+    hint = _hint_for_gateway_detail(detail)
+    raise SpcsGatewayAuthError(
+        f"SPCS gateway rejected the PAT (HTTP {response.status_code}, "
+        f"{response_type}). The request never reached DataMasque.\n"
+        f'  Snowflake said:   "{detail}"\n'
+        f"  Snowflake reqId:  {request_id}\n"
+        f"  Likely cause:     {hint}\n"
+        f"  Fix in Snowsight on the account hosting this SPCS app, then retry."
+    )
+
+
+def _spcs_gateway_response_hook(response: requests.Response, *args: Any, **kwargs: Any) -> None:
+    """`requests` response hook: raise on a gateway-originated auth rejection."""
+    _check_spcs_gateway_response(response)
+
+
+def install_spcs_gateway_auth(session: requests.Session, pat: str) -> None:
+    """
+    Configure `session` to authenticate to a Snowflake SPCS app gateway.
+
+    Sets the `X-SF-SPCS-Authorization` header on the session
+    (so it rides on every request, including the unauthenticated login)
+    and registers a response hook
+    that raises `SpcsGatewayAuthError` on a gateway rejection.
+
+    Scoping is automatic:
+    the client's session only ever talks to its own `base_url`,
+    so there is no need to match per-request hosts.
+    """
+    session.headers[SPCS_GATEWAY_AUTH_HEADER] = f'Snowflake Token="{pat}"'
+    session.hooks["response"].append(_spcs_gateway_response_hook)

{datamasque_python-1.1.3.dist-info → datamasque_python-1.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datamasque-python
-Version: 1.1.3
+Version: 1.1.5
 Summary: Official Python client for the DataMasque data-masking API.
 Project-URL: Homepage, https://datamasque.com/
 Project-URL: Documentation, https://datamasque-python.readthedocs.io/
@@ -74,6 +74,11 @@ Authentication is performed on the first request if ``authenticate()`` is not ca
 and is automatically retried once on a 401 response.
 ``client.healthcheck()`` is available as a lightweight readiness probe that does not consume credentials.
 
+For a DataMasque instance hosted on Snowpark Container Services (SPCS)
+(a ``*.snowflakecomputing.app`` ``base_url``),
+pass a Snowflake Programmatic Access Token as ``spcs_pat`` on ``DataMasqueInstanceConfig``.
+See the `usage docs <https://datamasque-python.readthedocs.io/en/latest/usage.html>`_ for details.
+
 Error handling
 ==============
 

{datamasque_python-1.1.3.dist-info → datamasque_python-1.1.5.dist-info}/RECORD

@@ -1,10 +1,10 @@
 datamasque/client/__init__.py,sha256=bW7Iy-iNxpaYgc_X035KAL-hmOVgr8YcYh5s398zawo,6378
-datamasque/client/base.py,sha256=vP1LuYbqq6U8NAEJWnwNrdt_Fa2wjQTJXHf0gSFO79c,14115
+datamasque/client/base.py,sha256=cXU4dluL9e1N1F2pV48iIvebv6OHt7Kh4Ka2y9vkOPo,14296
 datamasque/client/connections.py,sha256=EFinx8fJRme0mTxuWY3d29UnmUFbsQhMaUQT0Ma2PK4,2885
 datamasque/client/discovery.py,sha256=MTDiif6YWkv64hHXZ8YJxtRhoeKIvQVfjNYvjCIZCXE,21261
 datamasque/client/discovery_configs.py,sha256=G-W-X_KizjjQLa-Rb6ixLjlkxbkCe4WGCOfYZrGtxIk,6420
 datamasque/client/dmclient.py,sha256=tA7V8GEQmnsalTHUZch8YmIUynYw2ldK-mmUGbofFL4,1650
-datamasque/client/exceptions.py,sha256=Tx7tE6i1X_oemR3EOJC97_sihZiToHqGuOQmWWxs_BE,3131
+datamasque/client/exceptions.py,sha256=YpM_vhnl31_02KQmx-NPP2AxR3gKYcmcxyb_35G9HVw,3755
 datamasque/client/files.py,sha256=vc2tZgT8RdwuCObIQ7H-Qjb80H1PBFqD0nG5Y1tOA_o,3503
 datamasque/client/ifm.py,sha256=uIMxpLIPvDiDO1m4bxezixNIUFIFY0MXWRMQNvTbpTA,11858
 datamasque/client/license.py,sha256=pluYaSU168OC6_laB9bM9H3Vuuxs8wa9gujCJvtoJCk,1392
@@ -13,13 +13,14 @@ datamasque/client/ruleset_libraries.py,sha256=bMUMBHdxjDyFOziw9LMRy5xChPvHvCjpjA
 datamasque/client/rulesets.py,sha256=Fsnsv-uAhF1DBnLI-pRpOrWJ7aCSZspcuU1r0RYTzUc,2655
 datamasque/client/runs.py,sha256=l_JpYgelqsDKW_O6LtsHC60IMXHG9ak_RwVnuvJKE1I,7703
 datamasque/client/settings.py,sha256=Ui8AyR2XdoW8MZ9FIrGn2jm8DLzUGWIL8i2DOTvu7hc,2898
+datamasque/client/spcs.py,sha256=geHrBQ6WLWsMGpSMV8hmK5SFAwftrOU0DXkrR2orOmo,7532
 datamasque/client/users.py,sha256=VCUo2CJyOw4-aO_3mp_w_0BcSoa6-h1HcReMcAMyumw,3701
 datamasque/client/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-datamasque/client/models/connection.py,sha256=Mh7MyTQmF0bllu0rurnFXmbiiq7Htc4bTwK5WQiPXSk,16823
+datamasque/client/models/connection.py,sha256=CPT2wF1dVMs-N8Jca7hUhegtRk_mxPKU8XhWV43C0xE,17419
 datamasque/client/models/data_selection.py,sha256=406yyUZ5NmLBSql2lYM1gsTWY5GWmnutmF-DjznAoLc,1904
 datamasque/client/models/discovery.py,sha256=WHSIkFebQ5m47K_BdxY1lvCeeF23q_BbZan7Ryuh5vY,13198
 datamasque/client/models/discovery_config.py,sha256=1CHMgSxMXuarPGfRcz9wX7jeZLn1SDw0UEe-L5naE54,1917
-datamasque/client/models/dm_instance.py,sha256=yjjpHZJTFhJp3lAinTEffgKrxnadrJys1EuhO77wQcA,1561
+datamasque/client/models/dm_instance.py,sha256=6h0WNlI1qt6jkrYFapIvuSJFkhRCcwbpx0PLG5NsrGw,2219
 datamasque/client/models/files.py,sha256=7hG3Q1-XYb1PF88l3ppsmBp2tjNtvQvv-RNTrOa7Nts,2784
 datamasque/client/models/git.py,sha256=F0KdMFe2vMyL-9tp3SGKGeOlbD1gbcjQn0jpOzNzybc,1782
 datamasque/client/models/ifm.py,sha256=j0Ef2BZYTk6MNZO6HS6mW0qWs1_wWD9PlUP_Y6WyBQI,5563
@@ -30,7 +31,7 @@ datamasque/client/models/ruleset_library.py,sha256=5UbL_M47mgPedo8xt4q5crUh4aeOV
 datamasque/client/models/runs.py,sha256=UtPMGCJFLFP1f2nyVGAbl3A5_wAONrRNJ63y43Hbpi0,6213
 datamasque/client/models/status.py,sha256=UUEDHd3CQZA1Mf-1LyhAiE4COuCWvAz5oJx5ECVIwp4,2868
 datamasque/client/models/user.py,sha256=UGAUzgJkf78m24_zFXXoA99zdut48BXkX_ivV8yq1Vc,2043
-datamasque_python-1.1.3.dist-info/METADATA,sha256=1OFcE21laJ8mFsaUCuJaGFssUJFsZzsDen7tpW59gUA,4187
-datamasque_python-1.1.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-datamasque_python-1.1.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-datamasque_python-1.1.3.dist-info/RECORD,,
+datamasque_python-1.1.5.dist-info/METADATA,sha256=UHqtyZNncrDXlTzz0C9pFVFqzOJpPXpC1ku7lEwYlhM,4497
+datamasque_python-1.1.5.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+datamasque_python-1.1.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+datamasque_python-1.1.5.dist-info/RECORD,,