pangea-sdk 6.1.1__py3-none-any.whl → 6.2.0__py3-none-any.whl

pangea/services/ai_guard.py

@@ -1,6 +1,10 @@
 from __future__ import annotations
 
-from typing import Any, Dict, Generic, List, Literal, Optional, TypeVar, overload
+from collections.abc import Sequence
+from typing import Generic, Literal, Optional, overload
+
+from pydantic import BaseModel, ConfigDict
+from typing_extensions import TypeVar
 
 from pangea.config import PangeaConfig
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
@@ -17,6 +21,13 @@ MaliciousEntityAction = Literal["report", "defang", "disabled", "block"]
 PiiEntityAction = Literal["disabled", "report", "block", "mask", "partial_masking", "replacement", "hash", "fpe"]
 
 
+class Message(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    role: str
+    content: str
+
+
 class CodeDetectionOverride(APIRequestModel):
     disabled: Optional[bool] = None
     action: Optional[Literal["report", "block"]] = None
@@ -24,14 +35,14 @@ class CodeDetectionOverride(APIRequestModel):
 
 class LanguageDetectionOverride(APIRequestModel):
     disabled: Optional[bool] = None
-    allow: Optional[List[str]] = None
-    block: Optional[List[str]] = None
-    report: Optional[List[str]] = None
+    allow: Optional[list[str]] = None
+    block: Optional[list[str]] = None
+    report: Optional[list[str]] = None
 
 
 class TopicDetectionOverride(APIRequestModel):
     disabled: Optional[bool] = None
-    block: Optional[List[str]] = None
+    block: Optional[list[str]] = None
 
 
 class PromptInjectionOverride(APIRequestModel):
@@ -179,7 +190,7 @@ class PromptInjectionResult(APIResponseModel):
     action: str
     """The action taken by this Detector"""
 
-    analyzer_responses: List[AnalyzerResponse]
+    analyzer_responses: list[AnalyzerResponse]
     """Triggered prompt injection analyzers."""
 
 
@@ -192,20 +203,20 @@ class PiiEntity(APIResponseModel):
 
 
 class PiiEntityResult(APIResponseModel):
-    entities: List[PiiEntity]
+    entities: list[PiiEntity]
     """Detected redaction rules."""
 
 
 class MaliciousEntity(APIResponseModel):
     type: str
     value: str
-    action: str
+    action: Optional[str] = None
     start_pos: Optional[int] = None
-    raw: Optional[Dict[str, Any]] = None
+    raw: Optional[dict[str, object]] = None
 
 
 class MaliciousEntityResult(APIResponseModel):
-    entities: List[MaliciousEntity]
+    entities: list[MaliciousEntity]
     """Detected harmful items."""
 
 
@@ -215,11 +226,11 @@ class CustomEntity(APIResponseModel):
     action: str
     """The action taken on this Entity"""
     start_pos: Optional[int] = None
-    raw: Optional[Dict[str, Any]] = None
+    raw: Optional[dict[str, object]] = None
 
 
 class CustomEntityResult(APIResponseModel):
-    entities: List[CustomEntity]
+    entities: list[CustomEntity]
     """Detected redaction rules."""
 
 
@@ -233,7 +244,7 @@ class SecretsEntity(APIResponseModel):
 
 
 class SecretsEntityResult(APIResponseModel):
-    entities: List[SecretsEntity]
+    entities: list[SecretsEntity]
     """Detected redaction rules."""
 
 
@@ -266,22 +277,22 @@ class TextGuardDetectors(APIResponseModel):
     prompt_injection: Optional[TextGuardDetector[PromptInjectionResult]] = None
     pii_entity: Optional[TextGuardDetector[PiiEntityResult]] = None
     malicious_entity: Optional[TextGuardDetector[MaliciousEntityResult]] = None
-    custom_entity: Optional[TextGuardDetector[Any]] = None
+    custom_entity: Optional[TextGuardDetector[object]] = None
     secrets_detection: Optional[TextGuardDetector[SecretsEntityResult]] = None
-    profanity_and_toxicity: Optional[TextGuardDetector[Any]] = None
+    profanity_and_toxicity: Optional[TextGuardDetector[object]] = None
     language_detection: Optional[TextGuardDetector[LanguageDetectionResult]] = None
     topic_detection: Optional[TextGuardDetector[TopicDetectionResult]] = None
     code_detection: Optional[TextGuardDetector[CodeDetectionResult]] = None
 
 
-class TextGuardResult(PangeaResponseResult, Generic[_T]):
+class TextGuardResult(PangeaResponseResult):
     detectors: TextGuardDetectors
     """Result of the recipe analyzing and input prompt."""
 
     prompt_text: Optional[str] = None
     """Updated prompt text, if applicable."""
 
-    prompt_messages: Optional[_T] = None
+    prompt_messages: Optional[object] = None
     """Updated structured prompt, if applicable."""
 
     blocked: bool
@@ -345,7 +356,7 @@ class AIGuard(ServiceBase):
         debug: bool | None = None,
         overrides: Overrides | None = None,
         log_fields: LogFields | None = None,
-    ) -> PangeaResponse[TextGuardResult[None]]:
+    ) -> PangeaResponse[TextGuardResult]:
         """
         Text Guard for scanning LLM inputs and outputs
 
@@ -373,12 +384,12 @@ class AIGuard(ServiceBase):
     def guard_text(
         self,
         *,
-        messages: _T,
+        messages: Sequence[Message],
         recipe: str | None = None,
         debug: bool | None = None,
         overrides: Overrides | None = None,
         log_fields: LogFields | None = None,
-    ) -> PangeaResponse[TextGuardResult[_T]]:
+    ) -> PangeaResponse[TextGuardResult]:
         """
         Text Guard for scanning LLM inputs and outputs
 
@@ -400,19 +411,19 @@ class AIGuard(ServiceBase):
             log_field: Additional fields to include in activity log
 
         Examples:
-            response = ai_guard.guard_text(messages=[{"role": "user", "content": "hello world"}])
+            response = ai_guard.guard_text(messages=[Message(role="user", content="hello world")])
         """
 
-    def guard_text(  # type: ignore[misc]
+    def guard_text(
         self,
         text: str | None = None,
         *,
-        messages: _T | None = None,
+        messages: Sequence[Message] | None = None,
         recipe: str | None = None,
         debug: bool | None = None,
         overrides: Overrides | None = None,
         log_fields: LogFields | None = None,
-    ) -> PangeaResponse[TextGuardResult[None]]:
+    ) -> PangeaResponse[TextGuardResult]:
         """
         Text Guard for scanning LLM inputs and outputs
 

pangea/services/audit/audit.py

@@ -1,9 +1,14 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Modernize.
+# ruff: noqa: UP006, UP035
+
 from __future__ import annotations
 
 import datetime
 import json
+from collections.abc import Mapping
 from typing import Any, Dict, Iterable, List, Optional, Sequence, Set, Tuple, Union
 
 import pangea.exceptions as pexc
@@ -55,7 +60,7 @@ from pangea.utils import canonicalize_nested_json
 
 class AuditBase:
     def __init__(
-        self, private_key_file: str = "", public_key_info: dict[str, str] = {}, tenant_id: str | None = None
+        self, private_key_file: str = "", public_key_info: Mapping[str, str] = {}, tenant_id: str | None = None
     ) -> None:
         self.pub_roots: Dict[int, PublishedRoot] = {}
         self.buffer_data: Optional[str] = None
@@ -90,7 +95,7 @@ class AuditBase:
         return input  # type: ignore[return-value]
 
     def _process_log(self, event: dict, sign_local: bool) -> LogEvent:
-        if event.get("tenant_id", None) is None and self.tenant_id:
+        if event.get("tenant_id") is None and self.tenant_id:
             event["tenant_id"] = self.tenant_id
 
         event = {k: v for k, v in event.items() if v is not None}
@@ -221,10 +226,7 @@ class AuditBase:
         tree_sizes.add(result.root.size)
         tree_sizes.difference_update(self.pub_roots.keys())
 
-        if tree_sizes:
-            arweave_roots = get_arweave_published_roots(result.root.tree_name, tree_sizes)
-        else:
-            arweave_roots = {}
+        arweave_roots = get_arweave_published_roots(result.root.tree_name, tree_sizes) if tree_sizes else {}
 
         return tree_sizes, arweave_roots
 
@@ -336,6 +338,7 @@ class AuditBase:
         public_key = get_public_key(audit_envelope.public_key)
 
         if audit_envelope and audit_envelope.signature and public_key:
+            assert audit_envelope.event
             v = Verifier()
             verification = v.verify_signature(
                 audit_envelope.signature,
@@ -385,7 +388,7 @@ class Audit(ServiceBase, AuditBase):
         token: str,
         config: PangeaConfig | None = None,
         private_key_file: str = "",
-        public_key_info: dict[str, str] = {},
+        public_key_info: Mapping[str, str] = {},
         tenant_id: str | None = None,
         logger_name: str = "pangea",
         config_id: str | None = None,

pangea/services/audit/models.py

@@ -1,11 +1,18 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Modernize.
+# ruff: noqa: UP006, UP035
+
 from __future__ import annotations
 
 import datetime
 import enum
 from typing import Any, Dict, List, Optional, Sequence, Union
 
+from pydantic import Field
+from typing_extensions import Annotated
+
 from pangea.response import APIRequestModel, APIResponseModel, PangeaDateTime, PangeaResponseResult
 
 
@@ -113,20 +120,25 @@ class Event(Dict[str, Any]):
 
 
 class EventEnvelope(APIResponseModel):
-    """
-    Contain extra information about an event.
+    event: Optional[dict[str, Any]] = None
 
-    Arguments:
-    event -- Event describing auditable activity.
-    signature -- An optional client-side signature for forgery protection.
-    public_key -- The base64-encoded ed25519 public key used for the signature, if one is provided
-    received_at -- A server-supplied timestamp
+    signature: Optional[str] = None
+    """
+    This is the signature of the hash of the canonicalized event that can be
+    verified with the public key provided in the public_key field. Signatures
+    cannot be used with the redaction feature turned on. If redaction is
+    required, the user needs to perform redaction before computing the signature
+    that is to be sent with the message. The SDK facilitates this for users.
     """
 
-    event: Dict[str, Any]
-    signature: Optional[str] = None
     public_key: Optional[str] = None
-    received_at: PangeaDateTime
+    """
+    The base64-encoded ed25519 public key used for the signature, if one is
+    provided
+    """
+
+    received_at: Optional[PangeaDateTime] = None
+    """A Pangea provided timestamp of when the event was received."""
 
 
 class LogRequest(APIRequestModel):
@@ -177,21 +189,28 @@ class LogBulkRequest(APIRequestModel):
 
 
 class LogResult(PangeaResponseResult):
+    envelope: Optional[EventEnvelope] = None
     """
-    Result class after an audit log action
-
-    envelope -- Event envelope information.
-    hash -- Event envelope hash.
-    unpublished_root -- The current unpublished root.
-    membership_proof -- A proof for verifying the unpublished root.
-    consistency_proof -- If prev_root was present in the request, this proof verifies that the new unpublished root is a continuation of the prev_root
+    The sealed envelope containing the event that was logged. Includes event
+    metadata such as optional client-side signature details and server-added
+    timestamps.
     """
 
-    envelope: Optional[EventEnvelope] = None
-    hash: str
+    hash: Annotated[Optional[str], Field(max_length=64, min_length=64)] = None
+    """The hash of the event data."""
+
     unpublished_root: Optional[str] = None
+    """The current unpublished root."""
+
     membership_proof: Optional[str] = None
+    """A proof for verifying that the buffer_root contains the received event"""
+
     consistency_proof: Optional[List[str]] = None
+    """
+    If prev_buffer_root was present in the request, this proof verifies that the
+    new unpublished root is a continuation of prev_unpublished_root
+    """
+
     consistency_verification: EventVerification = EventVerification.NONE
     membership_verification: EventVerification = EventVerification.NONE
     signature_verification: EventVerification = EventVerification.NONE
@@ -354,29 +373,47 @@ class RootResult(PangeaResponseResult):
 
 
 class SearchEvent(APIResponseModel):
+    envelope: EventEnvelope
+
+    membership_proof: Optional[str] = None
+    """A cryptographic proof that the record has been persisted in the log"""
+
+    hash: Annotated[Optional[str], Field(max_length=64, min_length=64)] = None
+    """The record's hash"""
+
+    published: Optional[bool] = None
+    """
+    If true, a root has been published after this event. If false, there is no
+    published root for this event
     """
-    Event information received after a search request
 
-    Arguments:
-    envelope -- Event related information.
-    hash -- The record's hash.
-    leaf_index -- The index of the leaf of the Merkle Tree where this record was inserted.
-    membership_proof -- A cryptographic proof that the record has been persisted in the log.
-    consistency_verification -- Consistency verification calculated if required.
-    membership_verification -- Membership verification calculated if required.
-    signature_verification -- Signature verification calculated if required.
-    fpe_context -- The context data needed to decrypt secure audit events that have been redacted with format preserving encryption.
+    imported: Optional[bool] = None
+    """
+    If true, the even was imported manually and not logged by the standard
+    procedure. Some features such as tamper proofing may not be available
     """
 
-    envelope: EventEnvelope
-    hash: str
-    membership_proof: Optional[str] = None
-    published: Optional[bool] = None
     leaf_index: Optional[int] = None
+    """
+    The index of the leaf of the Merkle Tree where this record was inserted or
+    null if published=false
+    """
+
+    valid_signature: Optional[bool] = None
+    """
+    Result of the verification of the Vault signature, if the event was signed
+    and the parameter `verify_signature` is `true`
+    """
+
+    fpe_context: Optional[str] = None
+    """
+    The context data needed to decrypt secure audit events that have been
+    redacted with format preserving encryption.
+    """
+
     consistency_verification: EventVerification = EventVerification.NONE
     membership_verification: EventVerification = EventVerification.NONE
     signature_verification: EventVerification = EventVerification.NONE
-    fpe_context: Optional[str] = None
 
 
 class SearchResultOutput(PangeaResponseResult):

pangea/services/audit/signing.py

@@ -81,7 +81,7 @@ class Signer:
                 with open(self.private_key_file, "rb") as file:
                     file_bytes = file.read()
             except FileNotFoundError:
-                raise Exception(f"Error: Failed opening private key file {self.private_key_file}")
+                raise Exception(f"Error: Failed opening private key file {self.private_key_file}") from None
 
             privkey = self._decode_private_key(file_bytes)
             for cls, signer in signers.items():

pangea/services/audit/util.py

@@ -1,5 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Modernize.
+# ruff: noqa: UP006, UP035
+
+from __future__ import annotations
+
 import base64
 import json
 import logging
@@ -155,9 +161,9 @@ def verify_membership_proof(node_hash: Hash, root_hash: Hash, proof: MembershipP
 def normalize_log(data: dict) -> dict:
     ans = {}
     for key in data:
-        if type(data[key]) == datetime:
+        if isinstance(data[key], datetime):
             ans[key] = format_datetime(data[key])
-        elif type(data[key]) == dict:
+        elif isinstance(data[key], dict):
             ans[key] = normalize_log(data[key])  # type: ignore[assignment]
         else:
             ans[key] = data[key]
@@ -223,9 +229,7 @@ def get_arweave_published_roots(tree_name: str, tree_sizes: Collection[int]) ->
             }
         }
     }
-    """.replace(
-        "{tree_sizes}", ", ".join(f'"{tree_size}"' for tree_size in tree_sizes)
-    ).replace(
+    """.replace("{tree_sizes}", ", ".join(f'"{tree_size}"' for tree_size in tree_sizes)).replace(
         "{tree_name}", tree_name
     )
 
@@ -273,8 +277,4 @@ def verify_consistency_proof(new_root: Hash, prev_root: Hash, proof: Consistency
         return False
 
     logger.debug("Verifying the proofs for the new root")
-    for item in proof:
-        if not verify_membership_proof(item.node_hash, new_root, item.proof):
-            return False
-
-    return True
+    return all(verify_membership_proof(item.node_hash, new_root, item.proof) for item in proof)

pangea/services/authn/authn.py

@@ -1,7 +1,12 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Modernize.
+# ruff: noqa: UP006, UP035
+
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import Dict, List, Literal, Optional, Union
 
 import pangea.services.authn.models as m
@@ -477,7 +482,7 @@ class AuthN(ServiceBase):
         def create(
             self,
             email: str,
-            profile: m.Profile,
+            profile: Mapping[str, str],
             *,
             username: str | None = None,
         ) -> PangeaResponse[m.UserCreateResult]:
@@ -864,7 +869,7 @@ class AuthN(ServiceBase):
 
             def update(
                 self,
-                profile: m.Profile,
+                profile: Mapping[str, str],
                 id: str | None = None,
                 email: str | None = None,
                 *,
@@ -991,7 +996,10 @@ class AuthN(ServiceBase):
             return self.request.post("v2/flow/complete", m.FlowCompleteResult, data=input.model_dump(exclude_none=True))
 
         def restart(
-            self, flow_id: str, choice: m.FlowChoice, data: m.FlowRestartData = {}
+            self,
+            flow_id: str,
+            choice: m.FlowChoice,
+            data: m.FlowRestartData = {},  # noqa: B006
         ) -> PangeaResponse[m.FlowRestartResult]:
             """
             Restart a sign-up/sign-in flow
@@ -1062,7 +1070,10 @@ class AuthN(ServiceBase):
             return self.request.post("v2/flow/start", m.FlowStartResult, data=input.model_dump(exclude_none=True))
 
         def update(
-            self, flow_id: str, choice: m.FlowChoice, data: m.FlowUpdateData = {}
+            self,
+            flow_id: str,
+            choice: m.FlowChoice,
+            data: m.FlowUpdateData = {},  # noqa: B006
         ) -> PangeaResponse[m.FlowUpdateResult]:
             """
             Update a sign-up/sign-in flow

pangea/services/authn/models.py

@@ -1,68 +1,22 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
 
+# TODO: Modernize.
+# ruff: noqa: UP006, UP035
+
 from __future__ import annotations
 
 import enum
+from collections.abc import Mapping
 from typing import Dict, List, NewType, Optional, Union
-from warnings import warn
-
-from typing_extensions import deprecated
 
 import pangea.services.intel as im
-from pangea.deprecated import pangea_deprecated
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponseResult
 from pangea.services.vault.models.common import JWK, JWKec, JWKrsa
 
 Scopes = NewType("Scopes", List[str])
 
 
-class Profile(Dict[str, str]):
-    @property
-    def first_name(self) -> str:
-        warn(
-            '`Profile.first_name` is deprecated. Use `Profile["first_name"]` instead.', DeprecationWarning, stacklevel=2
-        )
-        return self["first_name"]
-
-    @first_name.setter
-    def first_name(self, value: str) -> None:
-        warn(
-            '`Profile.first_name` is deprecated. Use `Profile["first_name"]` instead.', DeprecationWarning, stacklevel=2
-        )
-        self["first_name"] = value
-
-    @property
-    def last_name(self) -> str:
-        warn('`Profile.last_name` is deprecated. Use `Profile["last_name"]` instead.', DeprecationWarning, stacklevel=2)
-        return self["last_name"]
-
-    @last_name.setter
-    def last_name(self, value: str) -> None:
-        warn('`Profile.last_name` is deprecated. Use `Profile["last_name"]` instead.', DeprecationWarning, stacklevel=2)
-        self["last_name"] = value
-
-    @property
-    def phone(self) -> str:
-        warn('`Profile.phone` is deprecated. Use `Profile["phone"]` instead.', DeprecationWarning, stacklevel=2)
-        return self["phone"]
-
-    @phone.setter
-    def phone(self, value: str) -> None:
-        warn('`Profile.phone` is deprecated. Use `Profile["phone"]` instead.', DeprecationWarning, stacklevel=2)
-        self["phone"] = value
-
-    @deprecated("`Profile.model_dump()` is deprecated. `Profile` is already a `dict[str, str]`.")
-    @pangea_deprecated(reason="`Profile` is already a `dict[str, str]`.")
-    def model_dump(self, *, exclude_none: bool = False) -> dict[str, str]:
-        warn(
-            "`Profile.model_dump()` is deprecated. `Profile` is already a `dict[str, str]`.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self
-
-
 class ClientPasswordChangeRequest(APIRequestModel):
     token: str
     old_password: str
@@ -105,7 +59,7 @@ class SessionToken(PangeaResponseResult):
     identity: str
     email: str
     scopes: Optional[Scopes] = None
-    profile: Union[Profile, Dict[str, str]]
+    profile: dict[str, str]
     created_at: str
     intelligence: Optional[Intelligence] = None
 
@@ -245,7 +199,7 @@ class User(PangeaResponseResult):
     username: str
     """A username."""
 
-    profile: Union[Profile, Dict[str, str]]
+    profile: dict[str, str]
     """A user profile as a collection of string properties."""
 
     verified: bool
@@ -278,7 +232,7 @@ class UserCreateRequest(APIRequestModel):
     email: str
     """An email address."""
 
-    profile: Union[Profile, Dict[str, str]]
+    profile: Mapping[str, str]
     """A user profile as a collection of string properties."""
 
     username: Optional[str] = None
@@ -468,7 +422,7 @@ class UserProfileGetResult(User):
 
 
 class UserProfileUpdateRequest(APIRequestModel):
-    profile: Union[Profile, Dict[str, str]]
+    profile: Mapping[str, str]
     """Updates to a user profile."""
 
     id: Optional[str] = None
@@ -655,7 +609,7 @@ class FlowUpdateDataPassword(APIRequestModel):
 
 
 class FlowUpdateDataProfile(APIRequestModel):
-    profile: Union[Profile, Dict[str, str]]
+    profile: dict[str, str]
 
 
 class FlowUpdateDataProvisionalEnrollment(APIRequestModel):
@@ -777,7 +731,7 @@ class SessionItem(APIResponseModel):
     expire: str
     email: str
     scopes: Optional[Scopes] = None
-    profile: Union[Profile, Dict[str, str]]
+    profile: dict[str, str]
     created_at: str
     active_token: Optional[SessionToken] = None
 

pangea/services/authz.py

@@ -1,5 +1,9 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Use `list` instead of `List`.
+# ruff: noqa: UP006, UP035
+
 from __future__ import annotations
 
 import enum

pangea/services/base.py

@@ -1,10 +1,14 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Modernize.
+# ruff: noqa: UP006, UP035
+
 from __future__ import annotations
 
 import copy
 import logging
-from typing import Dict, Optional, Type, Union
+from typing import Optional, Type, Union
 
 from typing_extensions import TypeVar
 
@@ -17,7 +21,7 @@ from pangea.response import AttachedFile, PangeaResponse, PangeaResponseResult
 TResult = TypeVar("TResult", bound=PangeaResponseResult, default=PangeaResponseResult)
 
 
-class ServiceBase(object):
+class ServiceBase:
     service_name: str = "base"
 
     def __init__(
@@ -43,8 +47,7 @@ class ServiceBase(object):
         self._token = token
         self.config_id: Optional[str] = config_id
         self._request: Optional[Union[PangeaRequest, PangeaRequestAsync]] = None
-        extra_headers: Dict = {}
-        self.request.set_extra_headers(extra_headers)
+        self.request.set_extra_headers({})
 
     @property
     def token(self) -> str:

pangea/services/embargo.py

@@ -1,5 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Use `list` instead of `List`.
+# ruff: noqa: UP006, UP035
+
+from __future__ import annotations
+
 from typing import Any, Dict, List
 
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult