pangea-sdk 3.8.0b1__py3-none-any.whl → 5.3.0__py3-none-any.whl

pangea/services/authn/models.py

@@ -1,10 +1,16 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
 
+from __future__ import annotations
+
 import enum
 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
 
@@ -12,9 +18,49 @@ Scopes = NewType("Scopes", List[str])
 
 
 class Profile(Dict[str, str]):
-    first_name: str
-    last_name: str
-    phone: Optional[str] = None
+    @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):
@@ -59,7 +105,7 @@ class SessionToken(PangeaResponseResult):
     identity: str
     email: str
     scopes: Optional[Scopes] = None
-    profile: Profile
+    profile: Union[Profile, Dict[str, str]]
     created_at: str
     intelligence: Optional[Intelligence] = None
 
@@ -69,7 +115,7 @@ class LoginToken(SessionToken):
 
 
 class ClientTokenCheckResult(SessionToken):
-    token: Optional[str]
+    token: Optional[str] = None
 
 
 class IDProvider(str, enum.Enum):
@@ -150,34 +196,93 @@ class UserListOrderBy(enum.Enum):
 
 
 class Authenticator(APIResponseModel):
+    """Authenticator."""
+
     id: str
+    """An ID for an authenticator."""
+
     type: str
+    """An authentication mechanism."""
+
     enabled: bool
+    """Enabled."""
+
     provider: Optional[str] = None
+    """Provider."""
+
+    provider_name: Optional[str] = None
+    """Provider name."""
+
     rpid: Optional[str] = None
+    """RPID."""
+
     phase: Optional[str] = None
+    """Phase."""
+
+    enrolling_browser: Optional[str] = None
+    """Enrolling browser."""
+
+    enrolling_ip: Optional[str] = None
+    """Enrolling IP."""
+
+    created_at: str
+    """A time in ISO-8601 format."""
+
+    updated_at: str
+    """A time in ISO-8601 format."""
+
+    state: Optional[str] = None
+    """State."""
 
 
 class User(PangeaResponseResult):
     id: str
+    """The identity of a user or a service."""
+
     email: str
-    profile: Profile
+    """An email address."""
+
+    username: str
+    """A username."""
+
+    profile: Union[Profile, Dict[str, str]]
+    """A user profile as a collection of string properties."""
+
     verified: bool
+    """True if the user's email has been verified."""
+
     disabled: bool
+    """True if the service administrator has disabled user account."""
+
     accepted_eula_id: Optional[str] = None
+    """An ID for an agreement."""
+
     accepted_privacy_policy_id: Optional[str] = None
+    """An ID for an agreement."""
+
     last_login_at: Optional[str] = None
+    """A time in ISO-8601 format."""
+
     created_at: str
+    """A time in ISO-8601 format."""
+
     login_count: int = 0
     last_login_ip: Optional[str] = None
     last_login_city: Optional[str] = None
     last_login_country: Optional[str] = None
     authenticators: List[Authenticator] = []
+    """A list of authenticators."""
 
 
 class UserCreateRequest(APIRequestModel):
     email: str
-    profile: Profile
+    """An email address."""
+
+    profile: Union[Profile, Dict[str, str]]
+    """A user profile as a collection of string properties."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserCreateResult(User):
@@ -186,7 +291,13 @@ class UserCreateResult(User):
 
 class UserDeleteRequest(APIRequestModel):
     email: Optional[str] = None
+    """An email address."""
+
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserDeleteResult(PangeaResponseResult):
@@ -289,7 +400,7 @@ class UserInviterOrderBy(enum.Enum):
 
 
 class UserInviteListFilter(APIRequestModel):
-    callback: Optional[str]
+    callback: Optional[str] = None
     callback__contains: Optional[List[str]] = None
     callback__in: Optional[List[str]] = None
     created_at: Optional[str] = None
@@ -343,7 +454,13 @@ class UserInviteDeleteResult(PangeaResponseResult):
 
 class UserProfileGetRequest(APIRequestModel):
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserProfileGetResult(User):
@@ -351,9 +468,17 @@ class UserProfileGetResult(User):
 
 
 class UserProfileUpdateRequest(APIRequestModel):
-    profile: Profile
+    profile: Union[Profile, Dict[str, str]]
+    """Updates to a user profile."""
+
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserProfileUpdateResult(User):
@@ -362,9 +487,25 @@ class UserProfileUpdateResult(User):
 
 class UserUpdateRequest(APIRequestModel):
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
     disabled: Optional[bool] = None
+    """
+    New disabled value. Disabling a user account will prevent them from logging
+    in.
+    """
+
     unlock: Optional[bool] = None
+    """
+    Unlock a user account if it has been locked out due to failed authentication
+    attempts.
+    """
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserUpdateResult(User):
@@ -386,8 +527,16 @@ class ClientJWKSResult(PangeaResponseResult):
 
 class UserAuthenticatorsDeleteRequest(APIRequestModel):
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
     authenticator_id: str
+    """An ID for an authenticator."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserAuthenticatorsDeleteResult(PangeaResponseResult):
@@ -396,11 +545,18 @@ class UserAuthenticatorsDeleteResult(PangeaResponseResult):
 
 class UserAuthenticatorsListRequest(APIRequestModel):
     email: Optional[str] = None
+    """An email address."""
+
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserAuthenticatorsListResult(PangeaResponseResult):
     authenticators: List[Authenticator] = []
+    """A list of authenticators."""
 
 
 class FlowCompleteRequest(APIRequestModel):
@@ -499,7 +655,7 @@ class FlowUpdateDataPassword(APIRequestModel):
 
 
 class FlowUpdateDataProfile(APIRequestModel):
-    profile: Profile
+    profile: Union[Profile, Dict[str, str]]
 
 
 class FlowUpdateDataProvisionalEnrollment(APIRequestModel):
@@ -621,7 +777,7 @@ class SessionItem(APIResponseModel):
     expire: str
     email: str
     scopes: Optional[Scopes] = None
-    profile: Profile
+    profile: Union[Profile, Dict[str, str]]
     created_at: str
     active_token: Optional[SessionToken] = None
 

pangea/services/authz.py

@@ -0,0 +1,400 @@
+# Copyright 2022 Pangea Cyber Corporation
+# Author: Pangea Cyber Corporation
+from __future__ import annotations
+
+import enum
+from typing import Any, Dict, List, Optional, Union
+
+from pangea.config import PangeaConfig
+from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
+from pangea.services.base import ServiceBase
+
+
+class ItemOrder(str, enum.Enum):
+    ASC = "asc"
+    DESC = "desc"
+
+    def __str__(self):
+        return str(self.value)
+
+    def __repr__(self):
+        return str(self.value)
+
+
+class TupleOrderBy(str, enum.Enum):
+    RESOURCE_TYPE = "resource_type"
+    RESOURCE_ID = "resource_id"
+    RELATION = "relation"
+    SUBJECT_TYPE = "subject_type"
+    SUBJECT_ID = "subject_id"
+    SUBJECT_ACTION = "subject_action"
+
+    def __str__(self):
+        return str(self.value)
+
+    def __repr__(self):
+        return str(self.value)
+
+
+class Resource(PangeaResponseResult):
+    type: str
+    id: Optional[str] = None
+
+
+class Subject(PangeaResponseResult):
+    type: str
+    id: Optional[str] = None
+    action: Optional[str] = None
+
+
+class Tuple(PangeaResponseResult):
+    resource: Resource
+    relation: str
+    subject: Subject
+
+
+class TupleCreateRequest(APIRequestModel):
+    tuples: List[Tuple]
+
+
+class TupleCreateResult(PangeaResponseResult):
+    pass
+
+
+class TupleListFilter(APIRequestModel):
+    resource_type: Optional[str] = None
+    resource_type__contains: Optional[List[str]] = None
+    resource_type__in: Optional[List[str]] = None
+    resource_id: Optional[str] = None
+    resource_id__contains: Optional[List[str]] = None
+    resource_id__in: Optional[List[str]] = None
+    relation: Optional[str] = None
+    relation__contains: Optional[List[str]] = None
+    relation__in: Optional[List[str]] = None
+    subject_type: Optional[str] = None
+    subject_type__contains: Optional[List[str]] = None
+    subject_type__in: Optional[List[str]] = None
+    subject_id: Optional[str] = None
+    subject_id__contains: Optional[List[str]] = None
+    subject_id__in: Optional[List[str]] = None
+    subject_action: Optional[str] = None
+    subject_action__contains: Optional[List[str]] = None
+    subject_action__in: Optional[List[str]] = None
+
+
+class TupleListRequest(APIRequestModel):
+    filter: Optional[Union[Dict, TupleListFilter]] = None
+    size: Optional[int] = None
+    last: Optional[str] = None
+    order: Optional[ItemOrder] = None
+    order_by: Optional[TupleOrderBy] = None
+
+
+class TupleListResult(PangeaResponseResult):
+    tuples: List[Tuple]
+    last: str
+    count: int
+
+
+class TupleDeleteRequest(APIRequestModel):
+    tuples: List[Tuple]
+
+
+class TupleDeleteResult(PangeaResponseResult):
+    pass
+
+
+class CheckRequest(APIRequestModel):
+    resource: Resource
+    action: str
+    subject: Subject
+    debug: Optional[bool] = None
+    attributes: Optional[Dict[str, Any]] = None
+
+
+class DebugPath(APIResponseModel):
+    type: str
+    id: str
+    action: Optional[str] = None
+
+
+class Debug(APIResponseModel):
+    path: List[DebugPath]
+
+
+class CheckResult(PangeaResponseResult):
+    schema_id: str
+    schema_version: int
+    depth: int
+    allowed: bool
+    debug: Optional[Debug] = None
+
+
+class ListResourcesRequest(APIRequestModel):
+    type: str
+    action: str
+    subject: Subject
+    attributes: Optional[Dict[str, Any]] = None
+
+
+class ListResourcesResult(PangeaResponseResult):
+    ids: List[str]
+
+
+class ListSubjectsRequest(APIRequestModel):
+    resource: Resource
+    action: str
+    attributes: Optional[Dict[str, Any]] = None
+
+
+class ListSubjectsResult(PangeaResponseResult):
+    subjects: List[Subject]
+
+
+class AuthZ(ServiceBase):
+    """AuthZ service client.
+
+    Provides methods to interact with the Pangea AuthZ Service.
+    Documentation for the AuthZ Service API can be found at
+    <https://pangea.cloud/docs/api/authz>.
+
+    Examples:
+        import os
+        from pangea.config import PangeaConfig
+        from pangea.services import AuthZ
+
+        PANGEA_TOKEN = os.getenv("PANGEA_AUTHZ_TOKEN")
+
+        authz_config = PangeaConfig(domain="aws.us.pangea.cloud")
+
+        # Setup Pangea AuthZ service client
+        authz = AuthZ(token=PANGEA_TOKEN, config=authz_config)
+    """
+
+    service_name = "authz"
+
+    def __init__(
+        self, token: str, config: PangeaConfig | None = None, logger_name: str = "pangea", config_id: str | None = None
+    ) -> None:
+        """
+        AuthZ client
+
+        Initializes a new AuthZ client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+            config_id: Configuration ID.
+
+        Examples:
+             config = PangeaConfig(domain="aws.us.pangea.cloud")
+             authz = AuthZ(token="pangea_token", config=config)
+        """
+
+        super().__init__(token, config, logger_name, config_id=config_id)
+
+    def tuple_create(self, tuples: List[Tuple]) -> PangeaResponse[TupleCreateResult]:
+        """Create tuples.
+
+        Create tuples in the AuthZ Service. The request will fail if there is no schema
+        or the tuples do not validate against the schema.
+
+        Args:
+            tuples (List[Tuple]): List of tuples to be created.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with empty result.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/tuple/create).
+
+        Examples:
+            response = authz.tuple_create(
+                tuples=[
+                    Tuple(
+                        resource=Resource(type="file", id="file_1"),
+                        relation="owner",
+                        subject=Subject(type="user", id="user_1"),
+                    )
+                ]
+            )
+        """
+
+        input_data = TupleCreateRequest(tuples=tuples)
+        return self.request.post("v1/tuple/create", TupleCreateResult, data=input_data.model_dump(exclude_none=True))
+
+    def tuple_list(
+        self,
+        filter: TupleListFilter,
+        size: Optional[int] = None,
+        last: Optional[str] = None,
+        order: Optional[ItemOrder] = None,
+        order_by: Optional[TupleOrderBy] = None,
+    ) -> PangeaResponse[TupleListResult]:
+        """List tuples.
+
+        Return a paginated list of filtered tuples. The filter is given in terms
+        of a tuple. Fill out the fields that you want to filter. If the filter
+        is empty it will return all the tuples.
+
+        Args:
+            filter (TupleListFilter): The filter for listing tuples.
+            size (Optional[int]): The size of the result set. Default is None.
+            last (Optional[str]): The last token from a previous response. Default is None.
+            order (Optional[ItemOrder]): Order results asc(ending) or desc(ending).
+            order_by (Optional[TupleOrderBy]): Which field to order results by.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with a list of tuples and the last token.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/tuple/list).
+
+        Examples:
+            authz.tuple_list(TupleListFilter(subject_type="user", subject_id="user_1"))
+        """
+        input_data = TupleListRequest(
+            filter=filter.model_dump(exclude_none=True), size=size, last=last, order=order, order_by=order_by
+        )
+        return self.request.post("v1/tuple/list", TupleListResult, data=input_data.model_dump(exclude_none=True))
+
+    def tuple_delete(self, tuples: List[Tuple]) -> PangeaResponse[TupleDeleteResult]:
+        """Delete tuples.
+
+        Delete tuples in the AuthZ Service.
+
+        Args:
+            tuples (List[Tuple]): List of tuples to be deleted.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with empty result.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/tuple/delete).
+
+        Examples:
+            response = authz.tuple_delete(
+                tuples=[
+                    Tuple(
+                        resource=Resource(type="file", id="file_1"),
+                        relation="owner",
+                        subject=Subject(type="user", id="user_1"),
+                    )
+                ]
+            )
+        """
+
+        input_data = TupleDeleteRequest(tuples=tuples)
+        return self.request.post("v1/tuple/delete", TupleDeleteResult, data=input_data.model_dump(exclude_none=True))
+
+    def check(
+        self,
+        resource: Resource,
+        action: str,
+        subject: Subject,
+        debug: Optional[bool] = None,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> PangeaResponse[CheckResult]:
+        """Perform a check request.
+
+        Check if a subject has permission to perform an action on the resource.
+
+        Args:
+            resource (Resource): The resource to check.
+            action (str): The action to check.
+            subject (Subject): The subject to check.
+            debug (Optional[bool]): Setting this value to True will provide a detailed analysis of the check.
+            attributes (Optional[Dict[str, Any]]): Additional attributes for the check.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with the result of the check.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/check).
+
+        Examples:
+            response = authz.check(
+                resource=Resource(type="file", id="file_1"),
+                action="update",
+                subject=Subject(type="user", id="user_1"),
+                debug=True,
+            )
+        """
+
+        input_data = CheckRequest(resource=resource, action=action, subject=subject, debug=debug, attributes=attributes)
+        return self.request.post("v1/check", CheckResult, data=input_data.model_dump(exclude_none=True))
+
+    def list_resources(
+        self, type: str, action: str, subject: Subject, attributes: Optional[Dict[str, Any]] = None
+    ) -> PangeaResponse[ListResourcesResult]:
+        """List resources.
+
+        Given a type, action, and subject, list all the resources in the
+        type that the subject has access to the action with.
+
+        Args:
+            type (str): The type to filter resources.
+            action (str): The action to filter resources.
+            subject (Subject): The subject to filter resources.
+            attributes (Optional[Dict[str, Any]]): A JSON object of attribute data.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with a list of resource IDs.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/list-resources).
+
+        Examples:
+            authz.list_resources(
+                type="file",
+                action="update",
+                subject=Subject(type="user", id="user_1"),
+            )
+        """
+
+        input_data = ListResourcesRequest(type=type, action=action, subject=subject, attributes=attributes)
+        return self.request.post(
+            "v1/list-resources", ListResourcesResult, data=input_data.model_dump(exclude_none=True)
+        )
+
+    def list_subjects(
+        self, resource: Resource, action: str, attributes: Optional[Dict[str, Any]] = None
+    ) -> PangeaResponse[ListSubjectsResult]:
+        """List subjects.
+
+        Given a resource and an action, return the list of subjects who have
+        access to the action for the given resource.
+
+        Args:
+            resource (Resource): The resource to filter subjects.
+            action (str): The action to filter subjects.
+            attributes (Optional[Dict[str, Any]]): A JSON object of attribute data.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with a list of subjects.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/list-subjects).
+
+        Examples:
+            response = authz.list_subjects(
+                resource=Resource(type="file", id="file_1"),
+                action="update",
+            )
+        """
+
+        input_data = ListSubjectsRequest(resource=resource, action=action, attributes=attributes)
+        return self.request.post("v1/list-subjects", ListSubjectsResult, data=input_data.model_dump(exclude_none=True))