clear-skies 2.0.3__py3-none-any.whl → 2.0.5__py3-none-any.whl

clearskies/authentication/secret_bearer.py

@@ -1,553 +0,0 @@
-import clearskies.configs
-import clearskies.decorators
-import clearskies.di
-from clearskies import autodoc
-from clearskies.authentication.authentication import Authentication
-
-
-class SecretBearer(Authentication, clearskies.di.InjectableProperties):
-    """
-    Secret Bearer performs authentication by checking against a static API key stored in either environment variables or a secret manager.
-
-    This can be used in two different ways:
-
-     1. Attached to an endpoint to enforce authentication
-     2. Attached to an API backend to specify how to authenticate to the API endpoint.
-
-    ### Authenticating Endpoints.
-
-    When attached to an endpoint this will enforce authentication.  Clients authenticate themselves by providing the secret value
-    via the `authorization` header.  In the following example we configure the secret bearer class to get the secretfrom an
-    environment variable which is set in the code itself.  Normally you wouldn't set environment variables like this,
-    but it's done here to create a self-contained example that is easy to run:
-
-    ```python
-    import os
-    import clearskies
-
-    os.environ["MY_AUTH_SECRET"] = "SUPERSECRET"
-
-    wsgi = clearskies.contexts.WsgiRef(
-        clearskies.endpoints.Callable(
-            lambda: {"hello": "world"},
-            authentication=clearskies.authentication.SecretBearer(environment_key="MY_AUTH_SECRET"),
-        )
-    )
-    wsgi()
-    ```
-    We can then call it with and without the authentication header:
-
-    ```bash
-    $ curl 'http://localhost:8080' -H 'Authorization: SUPERSECRET' | jq
-    {
-        "status": "success",
-        "error": "",
-        "data": {
-            "hello": "world"
-        },
-        "pagination": {},
-        "input_errors": {}
-    }
-
-    $ curl 'http://localhost:8080' | jq
-    {
-        "status": "client_error",
-        "error": "Not Authenticated",
-        "data": [],
-        "pagination": {},
-        "input_errors": {}
-    }
-
-    $ curl 'http://localhost:8080' -H 'Authorization: NOTTHESECRET' | jq
-    {
-        "status": "client_error",
-        "error": "Not Authenticated",
-        "data": [],
-        "pagination": {},
-        "input_errors": {}
-    }
-    ```
-
-    ### Authenticating to APIs
-
-    The secret bearer class can also be attached to an API Backend to provide authentication to remote APIs.  To
-    demonstrate, here is an example server that expects a secret token in the authorization header:
-
-    ```python
-    import os
-    import clearskies
-    from clearskies import columns
-
-    os.environ["MY_SECRET"] = "SUPERSECRET"
-
-
-    class Widget(clearskies.Model):
-        id_column_name = "id"
-        backend = clearskies.backends.MemoryBackend()
-
-        id = columns.Uuid()
-        name = columns.String()
-        category = columns.String()
-        cost = columns.Float()
-        created_at = columns.Created()
-        updated_at = columns.Updated()
-
-
-    wsgi = clearskies.contexts.WsgiRef(
-        clearskies.endpoints.RestfulApi(
-            url="widgets",
-            model_class=Widget,
-            authentication=clearskies.authentication.SecretBearer(environment_key="MY_SECRET"),
-            readable_column_names=["id", "name", "category", "cost", "created_at", "updated_at"],
-            writeable_column_names=["name", "category", "cost"],
-            sortable_column_names=["name", "category", "cost"],
-            searchable_column_names=["id", "name", "category", "cost"],
-            default_sort_column_name="name",
-        )
-    )
-    wsgi()
-    ```
-
-    Then here is a client app (you can launch the above server and then run this in a new terminal) that
-    similarly uses the secret bearer class to authenticate to the server:
-
-    ```python
-    import os
-    import clearskies
-    from clearskies import columns
-
-    os.environ["MY_SECRET"] = "SUPERSECRET"
-
-
-    class Widget(clearskies.Model):
-        id_column_name = "id"
-        backend = clearskies.backends.ApiBackend(
-            base_url="http://localhost:8080",
-            authentication=clearskies.authentication.SecretBearer(environment_key="MY_SECRET"),
-        )
-
-        id = columns.String()
-        name = columns.String()
-        category = columns.String()
-        cost = columns.Float()
-        created_at = columns.Datetime()
-        updated_at = columns.Datetime()
-
-
-    def api_demo(widgets: Widget) -> Widget:
-        thinga = widgets.create({"name": "Thinga", "category": "Doohickey", "cost": 125})
-        mabob = widgets.create({"name": "Mabob", "category": "Doohicky", "cost": 150})
-        return widgets
-
-
-    cli = clearskies.contexts.Cli(
-        clearskies.endpoints.Callable(
-            api_demo,
-            model_class=Widget,
-            return_records=True,
-            readable_column_names=["id", "name", "category", "cost", "created_at", "updated_at"],
-        ),
-        classes=[Widget],
-    )
-    cli()
-    ```
-
-    The above app declares a model class that matches the output from our server/api.  Note that the id,
-    created_at, and updated_at columns all changed types to their "plain" types.  This is very normal.  The API
-    is the one that is responsible for assigning ids and setting created/updated timestamps, so from the
-    perspective of our client, these are plain string/datetime fields.  If we used the UUID or created/updated
-    columns, then when the client called the API it would try to set all of these columns.  Since they are not
-    writeable columns, the API would return an input error.  If you launch the above server/API and then run
-    the given client script, you'll see output like this:
-
-    ```json
-    {
-        "status": "success",
-        "error": "",
-        "data": [
-            {
-                "id": "54eef01d-7c87-4959-b525-dcb9047d9692",
-                "name": "Mabob",
-                "category": "Doohicky",
-                "cost": 150.0,
-                "created_at": "2025-06-13T15:19:27+00:00",
-                "updated_at": "2025-06-13T15:19:27+00:00",
-            },
-            {
-                "id": "ed1421b8-88ad-49d2-a130-c34b4ac4dfcf",
-                "name": "Thinga",
-                "category": "Doohickey",
-                "cost": 125.0,
-                "created_at": "2025-06-13T15:19:27+00:00",
-                "updated_at": "2025-06-13T15:19:27+00:00",
-            },
-        ],
-        "pagination": {},
-        "input_errors": {},
-    }
-    ```
-    """
-
-    is_public = False
-    can_authorize = False
-
-    environment = clearskies.di.inject.Environment()
-    secrets = clearskies.di.inject.Secrets()
-
-    """
-    The path in our secret manager from which the secret should be fetched.
-
-    Of course, to use `secret_key`, you must also provide a secret manager.  The below example uses the dependency
-    injection system to create a faux secret manager to demonstrate how it works in general:
-
-    ```python
-    from types import SimpleNamespace
-    import clearskies
-
-    def fetch_secret(path):
-        if path == "/path/to/my/secret":
-            return "SUPERSECRET"
-        raise KeyError(f"Attempt to fetch non-existent secret: {path}")
-
-    fake_secret_manager = SimpleNamespace(get=fetch_secret)
-
-    wsgi = clearskies.contexts.WsgiRef(
-        clearskies.endpoints.Callable(
-            lambda: {"hello": "world"},
-            authentication=clearskies.authentication.SecretBearer(secret_key="/path/to/my/secret"),
-        ),
-        bindings={
-            "secrets": fake_secret_manager,
-        },
-    )
-    wsgi()
-    ```
-
-    And when invoked:
-
-    ```bash
-    $ curl 'http://localhost:8080/' -H "Authorization: SUPERSECRET" | jq
-    {
-        "status": "success",
-        "error": "",
-        "data": {
-            "hello": "world"
-        },
-        "pagination": {},
-        "input_errors": {}
-    }
-
-    $ curl 'http://localhost:8080/' -H "Authorization: definitely-not-the-api-key" | jq
-    {
-        "status": "client_error",
-        "error": "Not Authenticated",
-        "data": [],
-        "pagination": {},
-        "input_errors": {}
-    }
-    ```
-
-    """
-    secret_key = clearskies.configs.String(default="")
-
-    """
-    The path in our secret manager where an alternate secret can also be fetched
-
-    The alternate secret is exclusively used to authenticate incoming requests.  This allows for secret
-    rotation - Point secret_key to a new secret and alternate_secret_key to the old secret.  Both will then
-    be accepted and you can migrate your applications to only send the new secret.  Once they are all updated,
-    remove the alternate_secret_key:
-
-    ```python
-    from types import SimpleNamespace
-    import clearskies
-
-    def fetch_secret(path):
-        if path == "/path/to/my/secret":
-            return "SUPERSECRET"
-        if path == "/path/to/alternate/secret":
-            return "ALSOOKAY"
-        raise KeyError(f"Attempt to fetch non-existent secret: {path}")
-
-    fake_secret_manager = SimpleNamespace(get=fetch_secret)
-
-    wsgi = clearskies.contexts.WsgiRef(
-        clearskies.endpoints.Callable(
-            lambda: {"hello": "world"},
-            authentication=clearskies.authentication.SecretBearer(
-                secret_key="/path/to/my/secret",
-                alternate_secret_key="/path/to/alternate/secret",
-            ),
-        ),
-        bindings={
-            "secrets": fake_secret_manager,
-        },
-    )
-    wsgi()
-    ```
-
-    And when invoked:
-
-    ```bash
-    $ curl 'http://localhost:8080/' -H "Authorization: SUPERSECRET" | jq
-    {
-        "status": "success",
-        "error": "",
-        "data": {
-            "hello": "world"
-        },
-        "pagination": {},
-        "input_errors": {}
-    }
-
-    $ curl 'http://localhost:8080/' -H "Authorization: ALSOOKAY" | jq
-    {
-        "status": "success",
-        "error": "",
-        "data": {
-            "hello": "world"
-        },
-        "pagination": {},
-        "input_errors": {}
-    }
-
-    $ curl 'http://localhost:8080/' -H "Authorization: NOTTHESECRET" | jq
-    {
-        "status": "client_error",
-        "error": "Not Authenticated",
-        "data": [],
-        "pagination": {},
-        "input_errors": {}
-    }
-    ```
-
-    """
-    alternate_secret_key = clearskies.configs.String(default="")
-
-    """
-    The name of the environment variable from which we should fetch our key.
-    """
-    environment_key = clearskies.configs.String(default="")
-
-    """
-    The name of an alternate environment variable from which we should fetch our key.
-
-    This allows for secret rotation by allowing the API to accept a secret from two different
-    environment variables: an old value and a new value.  You can then migrate your client applications
-    to use the new key and, once they are all migrated, remove the old key from the application
-    configuration.  Here's an example:
-
-    ```python
-    import os
-    import clearskies
-
-    os.environ["MY_AUTH_SECRET"] = "SUPERSECRET"
-    os.environ["MY_ALT_SECRET"] = "ALSOOKAY"
-
-    wsgi = clearskies.contexts.WsgiRef(
-        clearskies.endpoints.Callable(
-            lambda: {"hello": "world"},
-            authentication=clearskies.authentication.SecretBearer(
-                environment_key="MY_AUTH_SECRET",
-                alternate_environment_key="MY_ALT_SECRET",
-            ),
-        ),
-    )
-    wsgi()
-    ```
-
-    And when invoked:
-
-    ```bash
-    $ curl 'http://localhost:8080/' -H "Authorization: SUPERSECRET" | jq
-    {
-        "status": "success",
-        "error": "",
-        "data": {
-            "hello": "world"
-        },
-        "pagination": {},
-        "input_errors": {}
-    }
-
-    $ curl 'http://localhost:8080/' -H "Authorization: ALSOOKAY" | jq
-    {
-        "status": "success",
-        "error": "",
-        "data": {
-            "hello": "world"
-        },
-        "pagination": {},
-        "input_errors": {}
-    }
-
-    $ curl 'http://localhost:8080/' -H "Authorization: NOTTHESECRET" | jq
-    {
-        "status": "client_error",
-        "error": "Not Authenticated",
-        "data": [],
-        "pagination": {},
-        "input_errors": {}
-    }
-    ```
-
-    """
-    alternate_environment_key = clearskies.configs.String(default="")
-
-    """
-    The expected prefix (if any) that should come before the secret key in the authorization header.
-
-    This applies to both the incoming authentication process and outgoing authentication headers.  Some systems
-    require a prefix before the auth token in the HTTP header (e.g. `Authorization: TOKEN [auth key here]`).
-    You can provide that prefix to `header_prefix` in order for the endpoint to require a prefix or the api backend
-    to provide such a prefix.  Note that the prefix is case-insensitive and it does not assume a space between the
-    prefix and the token (so, if you want a space, you must explicitly put it in the prefix).  Here's an example:
-
-    ```python
-    import os
-    import clearskies
-
-    os.environ["MY_AUTH_SECRET"] = "SUPERSECRET"
-
-    wsgi = clearskies.contexts.WsgiRef(
-        clearskies.endpoints.Callable(
-            lambda: {"hello": "world"},
-            authentication=clearskies.authentication.SecretBearer(
-                environment_key="MY_AUTH_SECRET",
-                header_prefix="secret-token ",
-            ),
-        ),
-    )
-    wsgi()
-    ```
-
-    And then usage:
-
-    ```bash
-    $ curl 'http://localhost:8080/' -H "Authorization: SECRET-TOKEN SUPERSECRET" | jq
-    {
-        "status": "success",
-        "error": "",
-        "data": {
-            "hello": "world"
-        },
-        "pagination": {},
-        "input_errors": {}
-    }
-
-    $ curl 'http://localhost:8080/' -H "Authorization: SUPERSECRET" | jq
-    {
-        "status": "client_error",
-        "error": "Not Authenticated",
-        "data": [],
-        "pagination": {},
-        "input_errors": {}
-    }
-    ```
-    """
-    header_prefix = clearskies.configs.String(default="")
-
-    """
-    The length of our header prefix
-    """
-    header_prefix_length = None
-
-    """
-    The name of our security scheme in the auto-generated documentation
-    """
-    documentation_security_name = clearskies.configs.String(default="ApiKey")
-
-    _secret: str = None  #  type: ignore
-    _alternate_secret: str = None  # type: ignore
-
-    @clearskies.decorators.parameters_to_properties
-    def __init__(
-        self,
-        secret_key: str = "",
-        alternate_secret_key: str = "",
-        environment_key: str = "",
-        alternate_environment_key: str = "",
-        header_prefix: str = "",
-        documentation_security_name: str = "",
-    ):
-        if not secret_key and not environment_key:
-            raise ValueError("Must set either 'secret_key' or 'environment_key' when configuring the SecretBearer")
-        self.header_prefix_length = len(header_prefix)
-        self.finalize_and_validate_configuration()
-
-    @property
-    def secret(self):
-        if not self._secret:
-            self._secret = (
-                self.secrets.get(self.secret_key) if self.secret_key else self.environment.get(self.environment_key)
-            )
-        return self._secret
-
-    def clear_credential_cache(self):
-        if self.secret_key:
-            self._secret = None  # type: ignore
-
-    @property
-    def alternate_secret(self):
-        if not self.alternate_secret_key and not self.alternate_environment_key:
-            return ""
-
-        if not self._alternate_secret:
-            self._alternate_secret = (
-                self.secrets.get(self.alternate_secret_key)
-                if self.alternate_secret_key
-                else self.environment.get(self.alternate_environment_key)
-            )
-        return self._alternate_secret
-
-    def headers(self, retry_auth=False):
-        self._configured_guard()
-        if retry_auth:
-            self.clear_credential_cache()
-        return {"Authorization": f"{self.header_prefix}{self.secret}"}
-
-    def authenticate(self, input_output):
-        self._configured_guard()
-        auth_header = input_output.request_headers.authorization
-        if not auth_header:
-            return False
-        if auth_header[: self.header_prefix_length].lower() != self.header_prefix.lower():
-            # self._logging.debug(
-            #     "Authentication failure due to prefix mismatch.  Configured prefix: "
-            #     + self._header_prefix.lower()
-            #     + ".  Found prefix: "
-            #     + auth_header[: self._header_prefix_length].lower()
-            # )
-            return False
-        provided_secret = auth_header[self.header_prefix_length :]
-        if self.secret == provided_secret:
-            # self._logging.debug("Authentication success")
-            return True
-        if self.alternate_secret and provided_secret == self._alternate_secret:
-            # self._logging.debug("Authentication success with alternate secret")
-            return True
-        # self._logging.debug("Authentication failure due to secret mismatch")
-        return False
-
-    def authorize(self, authorization):
-        raise ValueError("SecretBearer does not support authorization")
-
-    def set_headers_for_cors(self, cors):
-        cors.add_header("Authorization")
-
-    def _configured_guard(self):
-        if not self.secret:
-            raise ValueError("Attempted to use SecretBearer authentication class without providing the configuration")
-
-    def documentation_request_parameters(self):
-        return []
-
-    def documentation_security_scheme(self):
-        return {
-            "type": "apiKey",
-            "name": "authorization",
-            "in": "header",
-        }
-
-    def documentation_security_scheme_name(self):
-        return self.documentation_security_name

clearskies/autodoc/__init__.py

@@ -1,8 +0,0 @@
-from . import formats, request, response, schema
-
-__all__ = [
-    "formats",
-    "request",
-    "response",
-    "schema",
-]

clearskies/autodoc/formats/__init__.py

@@ -1,5 +0,0 @@
-from . import oai3_json
-
-__all__ = [
-    "oai3_json",
-]

clearskies/autodoc/formats/oai3_json/__init__.py

@@ -1,7 +0,0 @@
-from .oai3_json import OAI3JSON
-from .oai3_schema_resolver import OAI3SchemaResolver
-
-__all__ = [
-    "OAI3SchemaResolver",
-    "OAI3JSON",
-]

clearskies/autodoc/formats/oai3_json/oai3_json.py

@@ -1,87 +0,0 @@
-import json
-from typing import Any
-
-from .request import Request
-
-
-class OAI3JSON:
-    requests: Any = None
-    formatted: Any = None
-    models: Any = None
-    security_schemes: Any = None
-
-    def __init__(self, oai3_schema_resolver):
-        self.oai3_schema_resolver = oai3_schema_resolver
-        self.requests = []
-        self.formatted = []
-        self.models = {}
-
-    def set_requests(self, requests):
-        self.requests = requests
-        self.formatted = [self.format_request(request) for request in self.requests]
-
-    def set_components(self, components):
-        supported = ["models", "securitySchemes"]
-        for key in components.keys():
-            if key not in supported:
-                raise ValueError(
-                    f"Attempt to set unsupported OpenAPI3.0 component which is not currently supported: {key}"
-                )
-        if "models" in components:
-            self.set_models(components["models"])
-        if "securitySchemes" in components:
-            self.set_security_schemes(components["securitySchemes"])
-
-    def set_models(self, models):
-        self.models = models
-
-    def set_security_schemes(self, security_schemes):
-        self.security_schemes = security_schemes
-
-    def format_request(self, request):
-        formatted_request = Request(self.oai3_schema_resolver)
-        formatted_request.set_request(request)
-        return formatted_request
-
-    def pretty(self, root_properties=None):
-        return self.as_string(pretty=True, root_properties=root_properties)
-
-    def compact(self, root_properties=None):
-        return self.as_string(pretty=False, root_properties=root_properties)
-
-    def as_string(self, pretty=False, root_properties=None):
-        data = self.convert()
-        if root_properties is not None:
-            data = {**data, **root_properties}
-        if pretty:
-            return json.dumps(data, indent=2, sort_keys=True)
-        return json.dumps(data)
-
-    def convert(self):
-        paths: dict[str, Any] = {}
-        for request in self.formatted:
-            absolute_path = "/" + request.relative_path.lstrip("/")
-            if absolute_path not in paths:
-                paths[absolute_path] = {}
-
-            path_data = request.convert()
-            for request_method, path_doc in path_data.items():
-                if request_method in paths[absolute_path]:
-                    raise ValueError(f"Two routes had the same path and method: {absolute_path} - {request_method}")
-                paths[absolute_path][request_method] = path_doc
-
-        data: dict[str, Any] = {
-            "openapi": "3.0.0",
-            "paths": paths,
-            "components": {},
-        }
-
-        if self.models:
-            data["components"]["schemas"] = {
-                model_name: self.oai3_schema_resolver(model).convert() for (model_name, model) in self.models.items()
-            }
-
-        if self.security_schemes:
-            data["components"]["securitySchemes"] = {name: data for (name, data) in self.security_schemes.items()}
-
-        return data

clearskies/autodoc/formats/oai3_json/oai3_schema_resolver.py

@@ -1,15 +0,0 @@
-from ... import schema as raw_schema
-from . import schema as formatted_schema
-
-
-class OAI3SchemaResolver:
-    class_map = {
-        raw_schema.Array: formatted_schema.Array,
-        raw_schema.Enum: formatted_schema.Enum,
-        raw_schema.Object: formatted_schema.Object,
-    }
-
-    def __call__(self, schema_object):
-        if schema_object.__class__ in self.class_map:
-            return self.class_map[schema_object.__class__](schema_object, self)
-        return formatted_schema.Default(schema_object)