pycrossauth 0.0.2__py3-none-any.whl

crossauth_backend/common/interfaces.py

@@ -0,0 +1,287 @@
+# Copyright (c) 2024 Matthew Baker.  All rights reserved.  Licenced under the Apache Licence 2.0.  See LICENSE file
+from typing import Any, Dict, Optional, TypedDict, NotRequired
+import json
+from datetime import datetime
+from nulltype import NullType
+from crossauth_backend.common.logger import CrossauthLogger, j
+
+class Key(TypedDict):
+    """
+    A key (eg session ID, email reset token) as stored in a database table.
+ 
+    The fields defined here are the ones used by Crossauth.  You may add
+    others.
+    """
+
+    value : str
+    """ The value of the keykey.
+     In a cookie, the value part of cookiename=value; options... 
+     """
+
+    created : datetime
+    """ The datetime/time the key was created, in local time on the server """
+
+    expires : datetime | NullType
+    """ The datetime/time the key expires """
+
+    userid : NotRequired[str | int | NullType]
+    """ the user this key is for (or undefined for an anonymous session ID)
+     
+     It accepts the value null as usually this is the value stored in the
+     database, rather than undefined.  Some functions need to differentiate
+     between a null value as opposed to the value not being defined (eg for
+     a partial updatetime).
+     """
+
+    lastactive : NotRequired[datetime]
+    """ The datetime/time key was last used (eg last time a request was made
+     with this value as a session ID)
+     """
+
+    data : NotRequired[str]
+    """ Additional key-specific data (eg new email address for email change).
+     
+     While application specific, any data Crossauth puts in this field
+     is a strified JSON, with its own key so it can co-exist with
+     other data.
+     """
+
+class PartialKey(TypedDict, total = False):
+    """
+    Same as :class:`crossauth_backend.Key` but all fields are NotRequired
+    """
+
+    value : str
+    created : datetime
+    expires : datetime | NullType
+    userid : Optional[str | int | NullType]
+    lastactive : Optional[datetime]
+    data : Optional[str]
+
+
+class ApiKey(Key):
+    """
+    An API key is a str that can be used in place of a username and 
+    password.  These are not automatically created, like OAuth access tokens.
+    """
+
+    name : str
+    """ A name for the key, unique to the user """
+
+def get_json_data(key: Key) -> Dict[str, Any]:
+    """
+    Parses the data field in the key as a JSON object
+
+    :param crossauth_backend.Key key: the key to extract the data field from
+
+    :return: the data as dict
+    """
+    if ("data" not in key):
+        return {}
+    try:
+        return json.loads(key["data"])
+    except json.JSONDecodeError:
+        CrossauthLogger.logger().warn(j({"msg": "data in key is not JSON"}))
+        return {}
+
+class UserInputFields(TypedDict):
+    """
+    Describes a user as fetched from the user storage (eg, database table),
+    excluding auto-generated fields such as an auto-generated ID
+
+    This is extendible with additional fields - provide them to the 
+    :class:`UserStorage` class as `extraFields`.
+
+    You may want to do this if you want to pass additional user data back to the 
+    caller, eg real name.
+
+    The fields defined here are the ones used by Crossauth.  You may add
+    others.
+    """
+
+    username : str
+    """The username.  This may be an email address or anything else,
+    application-specific.
+    """
+
+    state : str
+    """
+    You are free to define your own states.  The ones Crossauth recognises
+    are defined in :class:`UserState`.
+    """
+
+    email : NotRequired[str]
+    """
+    You can optionally include an email address field in your user table.
+    If your username is an email address, you do not need a separate field.
+    """
+
+    admin : NotRequired[bool]
+    """
+    Whether or not the user has administrator priviledges (and can acess
+    admin-only functions).
+    """
+
+    factor1 : str
+    """
+    Factor for primary authentication.
+
+    Should match the name of an authenticator
+    """
+
+    factor2 : NotRequired[str]
+    """
+    Factor for second factor authentication.
+
+    Should match the name of an authenticator
+    """
+
+
+class PartialUserInputFields(TypedDict, total=False):
+    """
+    Same as UserInputFields but all fields are not required
+    """
+
+    username : str
+    state : str
+    email : NotRequired[str]
+    admin : NotRequired[bool]
+    factor1 : NotRequired[str]
+    factor2 : NotRequired[str]
+
+class PartialUser(PartialUserInputFields, total=False):
+    """
+    Same as User but all fields are not required
+    """
+    id : str | int
+
+
+class User(UserInputFields):
+    """
+    This adds ID to :class:`UserInputFields`.  
+
+    If your `username` field is
+    unique and immutable, you can omit ID (passing username anywhere an ID)
+    is expected.  However, if you want users to be able to change their username,
+    you should include ID field and make that immutable instead.
+    """
+
+    """ ID fied, which may be auto-generated """
+    id : str | int
+
+class UserSecretsInputFields(TypedDict, total=False):
+    """
+    Secrets, such as a password, are not in the User object to prevent them
+    accidentally being leaked to the frontend.  All functions that return
+    secrets return them in this separate object.
+
+    The fields in this class are the ones that are not autogenerated by the
+    database.
+    """
+
+    password : str
+    totpsecret : str
+    otp: str
+    expiry: int
+
+class PartialUserSecrets(UserSecretsInputFields, total=False):
+    """
+    Same as UserSecrets except all fields are NotRequired
+    """
+
+    userid : str|int
+
+
+class UserSecrets(UserSecretsInputFields):
+    """
+    This adds the user ID toi :class:`UserSecretsInputFields`.
+    """
+
+    userid : str|int
+
+class OAuthClient(TypedDict):
+    """
+    OAuth client data as stored in a database table
+    """
+
+    client_id : str
+    """The client_id, which is auto-generated and immutable """
+
+    confidential : bool
+    """Whether or not the client is confidential (and can therefore
+    keep the client secret secret) """
+
+    client_name : str
+    """
+    A user-friendly name for the client (not used as part of the OAuth
+    API).
+    """
+
+    client_secret : NotRequired[str|NullType]
+    """
+    Client secret, which is autogenerated.  
+    
+    If there is no client secret, it should be set to `undefined`.
+    
+    This field allows `null` as well as `undefined` this is used, for 
+    example, when partially updating a client and you specifically 
+    want to set the secret to undefined, as opposed to just not wishing
+    to change the value.  Other than that, this value is always either
+    a str or `undefined`.
+    """
+
+    redirect_uri : list[str]
+    """
+    An array of value redirect URIs for the client.
+    """
+
+    valid_flow : list[str]
+    """
+    An array of OAuth flows allowed for this client.  
+    
+    See :class:`OAuthFlows`.
+    """
+
+
+    userid : NotRequired[str|int|NullType]
+    """
+    ID of the user who owns this client, which may be `undefined`
+    for not being owned by a specific user.  
+    
+    This field allows `null` as well as `undefined` this is used, for 
+    example, when partially updating a client and you specifically 
+    want to set the user ID to undefined, as opposed to just not wishing
+    to change the value.  Other than that, this value is always either
+    a str or number (depending on the ID type in your user storage)
+    or `undefined`.
+    """
+
+class UserState:
+    """
+    These are used valiues for `state` in a :class:`crossauth_backend.User` object
+    """
+
+    active = "active"
+    disabled = "disabled"
+    awaiting_two_factor_setup = "awaitingtwofactorsetup"
+    awaiting_email_verification = "awaitingemailverification"
+    password_change_needed = "passwordchangeneeded"
+    password_reset_needed = "passwordresetneeded"
+    factor2_reset_needed = "factor2resetneeded"
+    password_and_factor2_reset_needed = "passwordandfactor2resetneeded"
+
+class KeyPrefix:
+    """
+    These are used prefixes for keye in a key storage entry
+    """
+
+    session = "s:"
+    password_reset_token = "p:"
+    email_verification_token = "e:"
+    api_key = "api:"
+    authorization_code = "authz:"
+    access_token = "access:"
+    refresh_token = "refresh:"
+    mfa_token = "omfa:"
+    device_code = "dc:"
+    user_code = "uc:"

crossauth_backend/common/jwt.py

@@ -0,0 +1,41 @@
+# Copyright (c) 2024 Matthew Baker.  All rights reserved.  Licenced under the Apache Licence 2.0.  See LICENSE file
+import json
+import base64
+from typing import Dict, Optional, Any
+
+from crossauth_backend.common.error import CrossauthError, ErrorCode
+from crossauth_backend.common.logger import CrossauthLogger, j
+
+class JWT:
+    """
+    Encapsulates the payload of a JWT, with both the token and
+    decoded JSON payload.
+    """
+
+    def __init__(self, token: Optional[str] = None, payload: Dict[str, Any] = {}):
+        """
+        Constructor. Pass either `token` or `payload`.
+        
+        Args:
+            token: the string JWT token - the payload will be parsed from it
+            payload: the JSON payload. The payload will be set but not
+                     the string `token`.
+        """
+        self.token: Optional[str] = token
+        
+        if payload:
+            self.payload = payload
+        elif self.token:
+            parts = self.token.split(".")
+            if len(parts) != 3:
+                raise CrossauthError(ErrorCode.InvalidToken, "JWT not in correct format")
+            try:
+                self.payload = json.loads(base64.urlsafe_b64decode(parts[1] + '==').decode('utf-8'))
+            except Exception as e:
+                CrossauthLogger.logger().error(j({"err": str(e)}))
+                if len(parts) != 3:
+                    raise CrossauthError(ErrorCode.InvalidToken, "JWT payload not in correct format")
+                json_string = base64.urlsafe_b64decode(parts[1] + '==').decode('utf-8')
+                self.payload = json.loads(json_string)
+        else:
+            self.payload = {}

crossauth_backend/common/logger.py

@@ -0,0 +1,202 @@
+# Copyright (c) 2024 Matthew Baker.  All rights reserved.  Licenced under the Apache Licence 2.0.  See LICENSE file
+from .. import CrossauthError
+
+import json
+import os
+from typing import Any, Dict, Mapping
+import traceback
+
+class CrossauthLoggerInterface:
+    """
+    You can implement your own logger.  Crossauth only needs these functions
+    and variables to be present.
+    """
+
+    def error(self, output: Any) -> None:
+        """ Report a message at error level """
+        pass
+
+    def warn(self, output: Any) -> None:
+        """ Report a message at warning level """
+        pass
+
+    def info(self, output: Any) -> None:
+        """ Report a message at info level """
+        pass
+
+    def debug(self, output: Any) -> None:
+        """ Report a message at debug level """
+        pass
+
+    NoLogging = 0
+    Error = 1
+    Warn = 2
+    Info = 3
+    Debug = 4
+
+    level: int = NoLogging
+
+class CrossauthLogger(CrossauthLoggerInterface):
+    """ 
+    A very simple logging class with no dependencies.
+    
+    Logs to console. 
+    
+    The logging API is designed so that you can replace this with other common loggers, eg Pino.
+    To change it, use the global :func:`CrossauthLogger.set_logger` function.  This has a parameter to tell 
+    Crossauth whether your logger accepts JSON input or not.
+    
+    When writing logs, we use the helper function :func:`j` to send JSON to the logger if it is
+    supprted, and a stringified JSON otherwise.
+    
+    **Crossauth logs**
+    
+    All Crossauth log messages are JSON (or stringified JSON, depending on whether the logger supports
+    JSON input - this one does).  The following fields may be present depending on context
+    (`msg` is always present):
+    
+    - `msg` : main contents of the log
+    - `err` : an error object.  If a subclass of Error, it wil contain at least `message` and
+                a stack trace in `stack`.  If the error is of type :class:`crossauth_backend.CrossauthError` 
+                it also will also contain `code` and `http_status`.
+    - `hashedSessionCookie` : for security reasons, session cookies are not included in logs.
+                                However, so that errors can be correlated with each other, a hash
+                                of it is included in errors originating from a session.
+    - `hashedCsrfCookie`    : for security reasons, csrf cookies are not included in logs.
+                                However, so that errors can be correlated with each other, a hash
+                                of it is included in errors originating from a session.
+    - `user` : username
+    - `emailMessageId` : internal id of any email that is sent
+    - `email` : email address
+    - `userid` : sometimes provided in addition to username, or when username not available
+    - `hahedApiKey` : a hash of an API key.  The unhashed version is not logged for security,
+                        but a hash of it is logged for correlation purposes.
+    - `header`      : an HTTP header that relates to an error (eg `Authorization`), only if
+                        it is non-secret or invalid
+    - `accessTokenHash` : hash of the JTI of an access token.  For security reasons, the 
+                            unhashed version is not logged.
+    - `method`: request method (GET, PUT etc)
+    - `url` : relevant URL
+    - `ip`  : relevant IP address           
+    - `scope` : OAuth scope
+    - `error_code` : Crossauth error code
+    - `error_code_name` : String version of Crossauth error code
+    - `http_status` : HTTP status that will be returned
+    - `port` port service is running on (only for starting a service)
+    - `prefix` prefix for endpoints (only when starting a service)
+    - `authorized` whether or not a valid OAuth access token was provided
+    """
+
+    levelName = ["NONE", "ERROR", "WARN", "INFO", "DEBUG"]
+
+    _instance : CrossauthLoggerInterface
+
+    @staticmethod
+    def logger() -> CrossauthLoggerInterface:
+        """ Returns the static logger instance"""
+        global _crossauth_logger, _crossauth_logger_accepts_json
+        return _crossauth_logger
+
+    def __init__(self, level: int|None = None):
+        """
+        Constructor
+
+        :param int|None level the level to report to
+
+        """
+        if level is not None:
+            self.level = level
+        elif "CROSSAUTH_LOG_LEVEL" in os.environ:
+            level_name = os.environ["CROSSAUTH_LOG_LEVEL"].upper()
+            if level_name in CrossauthLogger.levelName:
+                self.level = CrossauthLogger.levelName.index(level_name)
+            else:
+                self.level = CrossauthLogger.Error
+        else:
+            self.level = CrossauthLogger.Error
+        CrossauthLogger.rossauth_logger_accepts_json = True
+
+    def set_level(self, level: int) -> None:
+        """ Set the level to report down to """
+        self.level = level
+
+    def _log(self, level: int, output: Any) -> None:
+        if level <= self.level:
+            if isinstance(output, str):
+                print(f"Crossauth {CrossauthLogger.levelName[level]} {self._current_time_iso()} {output}")
+            else:
+                print(json.dumps({"level": CrossauthLogger.levelName[level], "time": self._current_time_iso(), **output}))
+
+    def error(self, output: Any) -> None:
+        """ Log an error """
+        self._log(CrossauthLogger.Error, output)
+
+    def warn(self, output: Any) -> None:
+        """ Log a warning """
+        self._log(CrossauthLogger.Warn, output)
+
+    def info(self, output: Any) -> None:
+        """ Log an info message """
+        self._log(CrossauthLogger.Info, output)
+
+    def debug(self, output: Any) -> None:
+        """ Log a debug message """
+        self._log(CrossauthLogger.Debug, output)
+
+    @staticmethod
+    def set_logger(logger: CrossauthLoggerInterface, accepts_json: bool) -> None:
+        """ Set the static logger instance """
+        global _crossauth_logger, _crossauth_logger_accepts_json
+        _crossauth_logger = logger
+        _crossauth_logger_accepts_json = accepts_json
+
+    @staticmethod
+    def _current_time_iso() -> str:
+        from datetime import datetime
+        return datetime.now().isoformat()
+
+
+def j(arg: Mapping[str, Any] | str) -> Dict[str, Any] | str:
+    """ Helper function that returns JSON if the error log supports it,
+        otherwise a string """
+    global _crossauth_logger_accepts_json
+    argcopy : Mapping[str,Any] = {}
+    if (type(arg) == str):
+        argcopy = {"msg": arg}
+    elif (isinstance(arg, Mapping)):
+        argcopy = {**arg}
+    if isinstance(arg, dict) and "cerr" in arg and isinstance(arg["cerr"], CrossauthError):
+        argcopy["error_code"] = arg["cerr"].code.value
+        argcopy["error_code_name"] = arg["cerr"].code_name
+        argcopy["http_status"] = arg["cerr"].http_status
+        if "msg" not in argcopy:
+            argcopy["msg"] = argcopy["cerr"].message
+
+    if isinstance(arg, dict) and "err" in arg and isinstance(arg["err"], CrossauthError):
+        argcopy["error_code"] = arg["err"].code.value
+        argcopy["error_code_name"] = arg["err"].code_name
+        argcopy["http_status"] = arg["err"].http_status
+        if "msg" not in argcopy:
+            if ("cerr" in argcopy):
+                argcopy["msg"] = argcopy["cerr"].message
+            elif ("err" in argcopy):
+                argcopy["msg"] = argcopy["err"].message
+        argcopy["stack"] = str(traceback.format_exception(arg["err"]))
+
+    elif isinstance(arg, dict) and "err" in arg and isinstance(arg["err"], Exception):
+        argcopy["stack"] = str(traceback.format_exception(arg["err"]))
+        if "msg" not in argcopy:
+            argcopy["msg"]  = str(str(arg["err"]))
+
+    if ("err" in argcopy): del argcopy["err"]
+    if ("cerr" in argcopy): del argcopy["cerr"]
+
+    if (type(arg) == str):
+        return arg
+    if (_crossauth_logger_accepts_json):
+        return argcopy
+    return json.dumps(argcopy)
+
+
+_crossauth_logger = CrossauthLogger(None)
+_crossauth_logger_accepts_json = True