totvs-dta-utils 1.4.30__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. dta_utils_python/__init__.py +72 -0
  2. dta_utils_python/apikeys/__init__.py +25 -0
  3. dta_utils_python/apikeys/apikeys.py +203 -0
  4. dta_utils_python/audit/__init__.py +8 -0
  5. dta_utils_python/audit/audit.py +38 -0
  6. dta_utils_python/audit/request_context.py +93 -0
  7. dta_utils_python/auth/__init__.py +94 -0
  8. dta_utils_python/auth/authorization.py +187 -0
  9. dta_utils_python/auth/cache.py +187 -0
  10. dta_utils_python/auth/constants.py +44 -0
  11. dta_utils_python/auth/exceptions.py +10 -0
  12. dta_utils_python/auth/expiry.py +15 -0
  13. dta_utils_python/auth/jwt.py +323 -0
  14. dta_utils_python/base/__init__.py +52 -0
  15. dta_utils_python/base/api.py +287 -0
  16. dta_utils_python/cloud_tasks/__init__.py +54 -0
  17. dta_utils_python/cloud_tasks/client.py +126 -0
  18. dta_utils_python/cloud_tasks/exceptions.py +16 -0
  19. dta_utils_python/cloud_tasks/models.py +75 -0
  20. dta_utils_python/cloud_tasks/retention.py +70 -0
  21. dta_utils_python/config/__init__.py +1 -0
  22. dta_utils_python/config/app.py +7 -0
  23. dta_utils_python/config/audit.py +13 -0
  24. dta_utils_python/config/loader.py +7 -0
  25. dta_utils_python/error_handling/README.md +303 -0
  26. dta_utils_python/error_handling/__init__.py +54 -0
  27. dta_utils_python/error_handling/constants.py +6 -0
  28. dta_utils_python/error_handling/exceptions.py +109 -0
  29. dta_utils_python/error_handling/handlers.py +226 -0
  30. dta_utils_python/error_handling/models.py +62 -0
  31. dta_utils_python/healthcheck/__init__.py +27 -0
  32. dta_utils_python/healthcheck/healthcheck.py +104 -0
  33. dta_utils_python/pubsub/__init__.py +22 -0
  34. dta_utils_python/pubsub/client.py +298 -0
  35. dta_utils_python/pubsub/exceptions.py +14 -0
  36. dta_utils_python/pubsub/models.py +62 -0
  37. dta_utils_python/pubsub/oidc.py +54 -0
  38. dta_utils_python/secrets/__init__.py +1 -0
  39. dta_utils_python/secrets/secrets.py +465 -0
  40. totvs_dta_utils-1.4.30.dist-info/METADATA +329 -0
  41. totvs_dta_utils-1.4.30.dist-info/RECORD +42 -0
  42. totvs_dta_utils-1.4.30.dist-info/WHEEL +4 -0
@@ -0,0 +1,72 @@
1
+ from .secrets import DtaSecrets # noqa: F401, E261, E501
2
+ from .apikeys import DtaApiKeys # noqa: F401, E261, E501
3
+ from .base import DtaClient # noqa: F401, E261, E501
4
+
5
+ try:
6
+ from .audit import ( # noqa: F401, E261, E501
7
+ extract_client_ip,
8
+ log_audit_event,
9
+ resolve_user_id,
10
+ )
11
+ except ImportError as e:
12
+ missing = getattr(e, "name", None)
13
+ optional_deps = {"dta_observability", "pydantic_settings", "pydantic"}
14
+ if missing in optional_deps:
15
+ pass
16
+ else:
17
+ raise
18
+
19
+ try:
20
+ from .cloud_tasks import ( # noqa: F401, E261, E501
21
+ CloudTaskAlreadyExistsError,
22
+ CloudTaskCreationError,
23
+ CloudTasksClient,
24
+ CloudTasksConfig,
25
+ CloudTasksError,
26
+ HttpTaskRequest,
27
+ OidcConfig,
28
+ )
29
+ except ImportError:
30
+ pass # extra cloud_tasks não instalado
31
+
32
+ try:
33
+ from .pubsub import ( # noqa: F401, E261, E501
34
+ PubSubConfig,
35
+ PubSubConfigError,
36
+ PubSubError,
37
+ PubSubPublishError,
38
+ PubSubPublisher,
39
+ PubSubPulledMessage,
40
+ PubSubSubscribeError,
41
+ PubSubSubscriber,
42
+ PubSubSubscriptionConfig,
43
+ verify_push_token,
44
+ )
45
+ except ImportError:
46
+ pass # extra pubsub não instalado
47
+
48
+ try:
49
+ from .error_handling import ( # noqa: F401, E261, E501
50
+ DTABusinessLogicError,
51
+ DTAConfigurationError,
52
+ DTAConflictError,
53
+ DTAException,
54
+ DTAInternalError,
55
+ DTAIOError,
56
+ DTANotFoundError,
57
+ DTAPermissionError,
58
+ DTAValidationError,
59
+ ErrorDetail,
60
+ ErrorResponse,
61
+ GENERIC_CLIENT_ERROR_CODE,
62
+ GENERIC_INTERNAL_ERROR_CODE,
63
+ GENERIC_VALIDATION_ERROR_CODE,
64
+ setup_exception_handlers,
65
+ )
66
+ except ImportError as e:
67
+ missing = getattr(e, "name", None)
68
+ optional_deps = {"fastapi", "pydantic", "starlette"}
69
+ if missing in optional_deps:
70
+ pass
71
+ else:
72
+ raise
@@ -0,0 +1,25 @@
1
+ from .apikeys import (
2
+ DtaApiKeys,
3
+ FlowScope,
4
+ KBScope,
5
+ AgentScope,
6
+ JobScope,
7
+ ApiKeyScope,
8
+ DtaKeyScope,
9
+ DtaPlanScope,
10
+ ProjectScope,
11
+ UserScope,
12
+ )
13
+
14
+ __all__ = [
15
+ "DtaApiKeys",
16
+ "FlowScope",
17
+ "KBScope",
18
+ "AgentScope",
19
+ "JobScope",
20
+ "ApiKeyScope",
21
+ "DtaKeyScope",
22
+ "DtaPlanScope",
23
+ "ProjectScope",
24
+ "UserScope",
25
+ ]
@@ -0,0 +1,203 @@
1
+ import os
2
+ import requests
3
+ from http import HTTPMethod, HTTPStatus
4
+ from typing import Any, Dict, Optional, Text, Tuple
5
+
6
+
7
+ class DtaApiKeys:
8
+ def __init__(self, project: str = None, organization: str = None) -> None:
9
+ self.project = project
10
+ self.organization = organization
11
+
12
+ def validate(
13
+ self, apikey: str, scope: str, related_id: Optional[str] = None
14
+ ) -> bool:
15
+ """
16
+ Validates an API key against a specific scope.
17
+
18
+ Args:
19
+ apikey (str): The API key to validate.
20
+ scope (str): The scope to validate against.
21
+ related_id (Optional[str], optional): An optional related ID.
22
+
23
+ Returns:
24
+ bool: True if the API key is valid for the specified scope,
25
+ False otherwise.
26
+ """
27
+ if not self.project or not apikey or not scope:
28
+ return False
29
+
30
+ json_payload = {"related_id": related_id} if related_id else {}
31
+ headers = {"X-DTA-API-Key": apikey, "X-DTA-Scope": scope}
32
+ validate_data = self.__ask(
33
+ f"/tenants/{self.project}/apikey/validate",
34
+ json=json_payload,
35
+ method=HTTPMethod.POST,
36
+ headers=headers,
37
+ )
38
+ if validate_data.status_code == HTTPStatus.OK:
39
+ return True
40
+ return False
41
+
42
+ def __ask(
43
+ self,
44
+ resource: str,
45
+ payload: dict = None,
46
+ json: dict = None,
47
+ method: str = HTTPMethod.GET,
48
+ headers: dict = None,
49
+ ) -> Any:
50
+ """
51
+ Makes a request to a specified resource with an optional payload.
52
+
53
+ Args:
54
+ resource (str): The resource endpoint to request.
55
+ payload (dict, optional): The data to send with the request.
56
+ Defaults to an empty dictionary.
57
+
58
+ Returns:
59
+ Any: The response from the request.
60
+
61
+ Notes:
62
+ If the instance is in production mode, '/production' is appended
63
+ to the resource URL.
64
+ """
65
+ service_url, default_headers = self.__service_builder()
66
+ all_headers = default_headers.copy()
67
+ if headers:
68
+ all_headers.update(headers)
69
+ secret_response = requests.request(
70
+ method, service_url + resource, headers=all_headers, data=payload, json=json
71
+ )
72
+ return secret_response
73
+
74
+ def __service_builder(self) -> Tuple[Text, Dict]:
75
+ """
76
+ This method constructs the service URL from the environment variable
77
+ `DTA_SECRETS_URL` and creates the necessary headers using the
78
+ `DtaServiceHeader` class.
79
+
80
+ Raises:
81
+ DtaSecretsError: If the `DTA_INTEGRATION_URL` environment variable
82
+ is not set or is an empty string.
83
+ """
84
+ headers = {
85
+ "Content-Type": "application/json",
86
+ }
87
+ service_url = os.environ.get("DTA_INTEGRATION_URL", os.environ.get("DTA_URL"))
88
+ if not service_url or not isinstance(service_url, str):
89
+ raise DtaApiKeyError(
90
+ "`DTA_INTEGRATION_URL` is not set or it has an invalid value."
91
+ )
92
+ if service_url.endswith("/"):
93
+ service_url = service_url[:-1]
94
+ if self.organization:
95
+ service_url = service_url.replace("{DTA_ORGANIZATION}", self.organization)
96
+ return service_url, headers
97
+
98
+
99
+ class DtaApiKeyError(Exception):
100
+ def __init__(self, message: str) -> None:
101
+ super().__init__(message)
102
+ self.message = message
103
+
104
+
105
+ class DTAScopes:
106
+ """
107
+ This class is a base class for the scopes used in the DTA API keys."""
108
+
109
+ pass
110
+
111
+
112
+ # Services scopes
113
+
114
+
115
+ class FlowScope(DTAScopes):
116
+ ALIAS: str = "flow"
117
+ PREFIX: str = f"{ALIAS}:"
118
+
119
+ RUN: str = f"{PREFIX}run"
120
+ CREATE: str = f"{PREFIX}create"
121
+ READ: str = f"{PREFIX}read"
122
+ UPDATE: str = f"{PREFIX}update"
123
+ DELETE: str = f"{PREFIX}delete"
124
+
125
+
126
+ class KBScope(DTAScopes):
127
+ ALIAS: str = "kb"
128
+ PREFIX: str = f"{ALIAS}:"
129
+
130
+ RUN: str = f"{PREFIX}run"
131
+ CREATE: str = f"{PREFIX}create"
132
+ READ: str = f"{PREFIX}read"
133
+ UPDATE: str = f"{PREFIX}update"
134
+ DELETE: str = f"{PREFIX}delete"
135
+
136
+
137
+ class AgentScope(DTAScopes):
138
+ ALIAS: str = "agent"
139
+ PREFIX: str = f"{ALIAS}:"
140
+
141
+ RUN: str = f"{PREFIX}run"
142
+ CREATE: str = f"{PREFIX}create"
143
+ READ: str = f"{PREFIX}read"
144
+ UPDATE: str = f"{PREFIX}update"
145
+ DELETE: str = f"{PREFIX}delete"
146
+
147
+
148
+
149
+ # API Base scopes
150
+
151
+
152
+ class JobScope(DTAScopes):
153
+ ALIAS: str = "job"
154
+ PREFIX: str = f"{ALIAS}:"
155
+
156
+ CREATE: str = f"{PREFIX}create"
157
+ READ: str = f"{PREFIX}read"
158
+ UPDATE: str = f"{PREFIX}update"
159
+ DELETE: str = f"{PREFIX}delete"
160
+
161
+
162
+ class ApiKeyScope(DTAScopes):
163
+ ALIAS: str = "api_key"
164
+ PREFIX: str = f"{ALIAS}:"
165
+
166
+ CREATE: str = f"{PREFIX}create"
167
+ READ: str = f"{PREFIX}read"
168
+ UPDATE: str = f"{PREFIX}update"
169
+ DELETE: str = f"{PREFIX}delete"
170
+
171
+
172
+ class DtaKeyScope(DTAScopes):
173
+ ALIAS: str = "dta_key"
174
+ PREFIX: str = f"{ALIAS}:"
175
+
176
+ CREATE: str = f"{PREFIX}create"
177
+ READ: str = f"{PREFIX}read"
178
+ UPDATE: str = f"{PREFIX}update"
179
+ DELETE: str = f"{PREFIX}delete"
180
+
181
+
182
+ class DtaPlanScope(DTAScopes):
183
+ ALIAS: str = "plan"
184
+ PREFIX: str = f"{ALIAS}:"
185
+
186
+ READ: str = f"{PREFIX}read"
187
+
188
+
189
+ class ProjectScope(DTAScopes):
190
+ ALIAS: str = "project"
191
+ PREFIX: str = f"{ALIAS}:"
192
+
193
+ READ: str = f"{PREFIX}read"
194
+
195
+
196
+ class UserScope(DTAScopes):
197
+ ALIAS: str = "user"
198
+ PREFIX: str = f"{ALIAS}:"
199
+
200
+ CREATE: str = f"{PREFIX}create"
201
+ READ: str = f"{PREFIX}read"
202
+ UPDATE: str = f"{PREFIX}update"
203
+ DELETE: str = f"{PREFIX}delete"
@@ -0,0 +1,8 @@
1
+ from .audit import log_audit_event
2
+ from .request_context import extract_client_ip, resolve_user_id
3
+
4
+ __all__ = [
5
+ "extract_client_ip",
6
+ "log_audit_event",
7
+ "resolve_user_id",
8
+ ]
@@ -0,0 +1,38 @@
1
+ from dta_observability import get_logger
2
+
3
+ audit_logger = get_logger("audit")
4
+
5
+
6
+ from dta_utils_python.config import get_settings
7
+
8
+
9
+ def log_audit_event(
10
+ path: str,
11
+ method: str,
12
+ client_ip: str | None,
13
+ client_ip_source: str | None,
14
+ user_id: str | None,
15
+ context: dict[str, object] | None = None,
16
+ ) -> None:
17
+ try:
18
+ settings = get_settings()
19
+ audit_cfg = getattr(settings, "audit", None)
20
+ if not audit_cfg or not getattr(audit_cfg, "enabled", False):
21
+ return
22
+ ignored_paths = getattr(audit_cfg, "ignored_paths", ["/healthcheck"])
23
+ if any(path == p or path.startswith(p + "/") for p in ignored_paths):
24
+ return
25
+ payload = {
26
+ "logger": "audit",
27
+ "path": path,
28
+ "method": method,
29
+ "client_ip": client_ip,
30
+ "client_ip_source": client_ip_source,
31
+ "user_id": user_id,
32
+ }
33
+ if context:
34
+ context_prefixed = {f"ctx_{k}": v for k, v in context.items()}
35
+ payload.update(context_prefixed)
36
+ audit_logger.info("http_request_audited", extra=payload)
37
+ except Exception:
38
+ return
@@ -0,0 +1,93 @@
1
+ """Helpers that derive audit fields from an incoming HTTP request.
2
+
3
+ This module has no runtime dependency on ``fastapi`` or ``dta_observability``;
4
+ ``fastapi.Request`` is referenced only under ``TYPE_CHECKING``.
5
+ """
6
+
7
+ import logging
8
+ from collections.abc import Mapping
9
+ from typing import TYPE_CHECKING
10
+
11
+ if TYPE_CHECKING:
12
+ from fastapi import Request
13
+
14
+
15
+ _logger = logging.getLogger(__name__)
16
+
17
+
18
+ def _get_header(headers: Mapping[str, str], name: str) -> str | None:
19
+ """Return a header value by case-insensitive name, or None if absent."""
20
+ target = name.lower()
21
+ for key, value in headers.items():
22
+ if key.lower() == target:
23
+ return value
24
+ return None
25
+
26
+
27
+ def extract_client_ip(
28
+ headers: Mapping[str, str],
29
+ ) -> tuple[str | None, str | None]:
30
+ """Return ``(client_ip, source_header)`` from proxy headers.
31
+
32
+ Reads the first (leftmost) entry of ``X-Forwarded-For``; if that yields no
33
+ usable token, falls back to ``X-Real-IP``. Both lookups are
34
+ case-insensitive. No IP-format validation is performed.
35
+
36
+ Returns:
37
+ - ``(ip, "X-Forwarded-For")`` when an IP is found in ``X-Forwarded-For``.
38
+ - ``(ip, "X-Real-IP")`` when falling back to ``X-Real-IP``.
39
+ - ``(None, None)`` when neither header yields a usable token.
40
+
41
+ The ``source`` element lets audit-log consumers distinguish entries with a
42
+ proxy-trusted IP from entries where the IP came from a client-controllable
43
+ header (and may have been forged). Callers must still ensure that
44
+ ``X-Forwarded-For`` is only honoured when the request transited a trusted
45
+ proxy that overwrites or appends to that header.
46
+ """
47
+ forwarded = _get_header(headers, "X-Forwarded-For")
48
+ if forwarded:
49
+ for token in forwarded.split(","):
50
+ token = token.strip()
51
+ if token:
52
+ return token, "X-Forwarded-For"
53
+
54
+ real_ip = _get_header(headers, "X-Real-IP")
55
+ if real_ip:
56
+ real_ip = real_ip.strip()
57
+ if real_ip:
58
+ return real_ip, "X-Real-IP"
59
+
60
+ return None, None
61
+
62
+
63
+ def resolve_user_id(request: "Request") -> str:
64
+ """Resolve the audit user identity from a request.
65
+
66
+ Returns, in order of precedence:
67
+ 1. ``request.state.identifier`` (the authenticated user's email) when it
68
+ is truthy and not the ``"external_integration"`` sentinel;
69
+ 2. a masked API key (``"sk-pr...23456"``) read from the
70
+ ``x-dta-api-key`` header, or the ``apiKey`` query parameter when the
71
+ header is absent, when that key is longer than 10 characters;
72
+ 3. the ``"visitor"`` sentinel otherwise.
73
+
74
+ Never raises — any failure yields ``"visitor"`` and emits a WARNING-level
75
+ log entry with the traceback so an unexpected failure is observable rather
76
+ than silently masked. Ported from dta-base ``src/helpers/audit_helper.py``.
77
+ """
78
+ try:
79
+ identifier = getattr(request.state, "identifier", None)
80
+ if identifier and identifier != "external_integration":
81
+ return identifier
82
+ api_key = request.headers.get(
83
+ "x-dta-api-key", request.query_params.get("apiKey")
84
+ )
85
+ if api_key and len(str(api_key)) > 10:
86
+ return f"{str(api_key)[:5]}...{str(api_key)[-5:]}"
87
+ return "visitor"
88
+ except Exception:
89
+ _logger.warning(
90
+ "resolve_user_id failed unexpectedly; returning 'visitor'",
91
+ exc_info=True,
92
+ )
93
+ return "visitor"
@@ -0,0 +1,94 @@
1
+ """
2
+ Centralized authentication and JWT handling for DTA services.
3
+
4
+ Supports:
5
+ - DTA JWT (current): HS256, issuer dta.totvs.ai.
6
+ - Identity JWT (new): RS256 with kid, validated via JWKS.
7
+ - Shared Redis JWT cache: get/set/delete and get_identity_user_from_cache
8
+ (all services share the same Redis instance for Identity token cache).
9
+ - Local development override (Identity): when DTA_ENVIRONMENT is "development"/"local"
10
+ and DTA_ROLE_USER is set, get_identity_user_from_cache validates the JWT via JWKS
11
+ and resolves tenant/role via env vars (DTA_TOTVS_TENANT_ID/DTA_TENANT_NAME, DTA_ROLE_USER).
12
+
13
+ Usage:
14
+ from dta_utils_python.auth import (
15
+ detect_jwt_type,
16
+ validate_dta_jwt,
17
+ validate_identity_jwt,
18
+ normalize_user_data,
19
+ validate_and_normalize,
20
+ is_identity_token_expired,
21
+ get_jwt_cached,
22
+ set_jwt_cached,
23
+ delete_jwt_cached,
24
+ get_identity_user_from_cache,
25
+ authorize,
26
+ authorize_with_token,
27
+ is_identity_super_user,
28
+ DTARoles,
29
+ DTAAuthMethods,
30
+ RAC_STUDIO_NAME_TO_DTA_ROLE,
31
+ DTA_ISSUER,
32
+ AuthError,
33
+ )
34
+ """
35
+
36
+ from .cache import (
37
+ delete_jwt_cached,
38
+ get_identity_user_from_cache,
39
+ get_jwt_cached,
40
+ set_jwt_cached,
41
+ )
42
+ from .constants import (
43
+ DTA_ISSUER,
44
+ DTA_STUDIO_ROLE_NAMES,
45
+ DTAAuthMethods,
46
+ DTARoles,
47
+ RAC_PERMISSIONS_MAPPING,
48
+ RAC_STUDIO_NAME_TO_DTA_ROLE,
49
+ )
50
+ from .authorization import authorize, authorize_with_token, is_identity_super_user
51
+ from .exceptions import AuthError
52
+ from .expiry import is_identity_token_expired
53
+ from .jwt import (
54
+ DEFAULT_JWKS_BASE_URL,
55
+ IDENTITY_JWT_AUDIENCE,
56
+ detect_jwt_type,
57
+ get_jwks_public_key,
58
+ normalize_user_data,
59
+ validate_and_normalize,
60
+ validate_dta_jwt,
61
+ validate_identity_jwt,
62
+ )
63
+
64
+ __all__ = [
65
+ # Authorization (shared across services)
66
+ "authorize",
67
+ "authorize_with_token",
68
+ "is_identity_super_user",
69
+ # Cache (shared Redis)
70
+ "delete_jwt_cached",
71
+ "get_identity_user_from_cache",
72
+ "get_jwt_cached",
73
+ "set_jwt_cached",
74
+ # Constants
75
+ "DTA_ISSUER",
76
+ "DTA_STUDIO_ROLE_NAMES",
77
+ "DTAAuthMethods",
78
+ "DTARoles",
79
+ "RAC_PERMISSIONS_MAPPING",
80
+ "RAC_STUDIO_NAME_TO_DTA_ROLE",
81
+ # JWT
82
+ "DEFAULT_JWKS_BASE_URL",
83
+ "IDENTITY_JWT_AUDIENCE",
84
+ "detect_jwt_type",
85
+ "get_jwks_public_key",
86
+ "normalize_user_data",
87
+ "validate_and_normalize",
88
+ "validate_dta_jwt",
89
+ "validate_identity_jwt",
90
+ # Expiry
91
+ "is_identity_token_expired",
92
+ # Exceptions
93
+ "AuthError",
94
+ ]