underscorepy 0.9.0__py3-none-any.whl

_/handlers.py

@@ -0,0 +1,45 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import os
+
+import tornado.web
+
+import _
+
+
+class Template(tornado.web.RequestHandler):
+    def initialize(self, template='index', **kwds):
+        self.kwds = kwds
+        self.template = template + '.html'
+
+    def get(self, template=None, *args):
+        template = template + '.html' if template else self.template
+        # the template name can come from the URL, so a missing one is not found
+        if not os.path.exists(os.path.join(self.get_template_path(), template)):
+            raise _.HTTPError(404)
+        self.render(template, extra=args, **self.kwds)
+
+
+class Protected(Template):
+    async def prepare(self):
+        if _.sessions is None:
+            raise _.HTTPError(500, 'No session component specified')
+
+        self.session = None
+        session_id = self.get_signed_cookie('session_id', max_age_days=1)
+        if session_id:
+            session_id = session_id.decode('utf-8')
+            self.session = await _.wait(_.sessions.load_session(session_id))
+
+    def get_current_user(self):
+        return self.session
+
+    @_.auth.current_user
+    def get(self, template=None, *args):
+        super().get(template, *args)

_/logins/__init__.py

@@ -0,0 +1,82 @@
+
+import urllib
+
+import tornado.web
+
+import _
+
+
+class Login(tornado.web.RequestHandler):
+    @classmethod
+    async def _(cls, component_name, **kwds):
+        # create a dynamic child class with kwds from the ini file
+        # add a reference to the component name accessible by the new type
+        members = _.prefix(kwds)
+        members['_component'] = component_name
+        login_cls = type(cls.__name__, (cls,), members)
+        try:
+            await login_cls.init(component_name, **kwds)
+        except TypeError as e:
+            raise _.error('%s', e)
+        _.logins[component_name] = login_cls
+        _.application._login_handler('login', login_cls)
+
+    @classmethod
+    async def init(cls, component_name, **kwds):
+        pass
+
+    @classmethod
+    async def args(cls, component_name):
+        pass
+
+    @classmethod
+    async def check(cls, username, password):
+        raise NotImplementedError
+
+    def initialize(self):
+        self.next_url = self.get_argument('next', '/')
+        self.redirect_uri = f'{self.request.protocol}://{self.request.host}/login/{self._component}?next={self.next_url}'
+
+    async def on_login_success(self, user):
+        fn = getattr(self.application, f'on_{self._component}_login_success', self.application.on_login_success)
+        try:
+            session = await _.wait(fn(self, user))
+            await _.wait(_.sessions.save_session(session))
+            self.set_signed_cookie('session_id', session['session_id'], expires_days=1)
+        except NotImplementedError:
+            raise _.HTTPError(500, 'on_login_success method not implemented') from None
+        self.redirect(self.next_url)
+
+    async def on_login_failure(self, message='Invalid Login'):
+        fn = getattr(self.application, f'on_{self._component}_login_failure', self.application.on_login_failure)
+        await _.wait(fn(self._component))
+
+        url = self.get_login_url()
+        url += "?" + urllib.parse.urlencode(dict(message=message, next_url=self.next_url))
+        self.clear_cookie('session_id')
+        self.redirect(url)
+
+
+class LoginPage(tornado.web.RequestHandler):
+    def initialize(self, template='login', **kwds):
+        self.kwds = kwds
+        self.template = template + '.html'
+
+    def get(self, template=None):
+        template = template + '.html' if template else self.template
+        message  = self.get_argument('message', None)
+        next_url = self.get_argument('next',    '/')
+        self.render(template, message=message, next_url=next_url, **self.kwds)
+
+
+class Logout(tornado.web.RequestHandler):
+    async def get(self):
+        session_id = self.get_signed_cookie('session_id', max_age_days=1)
+
+        if session_id:
+            session_id = session_id.decode('utf-8')
+            await _.wait(self.application.on_logout(session_id))
+            self.session = await _.wait(_.sessions.clear_session(session_id))
+
+        self.clear_cookie('session_id')
+        self.redirect(self.get_argument('next', '/'))

_/logins/dblogin.py

@@ -0,0 +1,230 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import asyncio
+import json
+import logging
+import typing
+
+import sqlalchemy
+
+import _
+import _.records
+
+
+class DbLogin(_.logins.Login):
+    _table    = 'users'
+    _username = 'username'
+    _password = 'password'
+
+    @classmethod
+    async def init(cls, component_name, database=None, table=None, username=None, password=None, **kwds):
+        cls._database = database
+        if database is None:
+            if 1 == len(_.databases):
+                cls._database = list(_.databases.keys())[0]
+            else:
+                raise _.error('dblogin requires a database to be specified')
+        try:
+            cls._db = _.databases[cls._database]
+        except AttributeError:
+            raise _.error('No database specified for %s', component_name)
+
+        # if only one login specified use short argument
+        prefix = f'{component_name}-' if len(_.config['logins']) > 1 else ''
+
+        _.argparser.add_argument(f'--{prefix}add-user',
+            metavar='<arg>', nargs=2,
+            help='create or update user with password'
+            )
+
+        _.argparser.add_argument(f'--{prefix}list-users',
+            action='store_true',
+            help='list users'
+            )
+
+        # create the dblogin table
+        annotations = {
+            cls._username : typing.Optional[str],
+            cls._password : typing.Optional[str],
+            }
+        columns = {
+            '__tablename__'   : cls._table,
+            '__annotations__' : annotations,
+            '__primary_key__' : cls._username,
+            cls._username : sqlalchemy.orm.mapped_column(primary_key=True, init=False),
+            cls._password : sqlalchemy.orm.mapped_column(init=False),
+            }
+
+        for col,dbtype in kwds.items():
+            if not dbtype:
+                dbtype = 'str'
+            annotations[col] = typing.Optional[__builtins__.get(dbtype)]
+            columns[col] = sqlalchemy.orm.mapped_column(init=False)
+
+        table_cls = type(cls._table, (_.records.RecordsInterface,cls._db.Base,), columns)
+
+        cls._table = table_cls
+
+        members = {
+            'component' : component_name,
+            'db'        : cls._db,
+            'table'     : cls._table,
+            'username'  : cls._username,
+            'password'  : cls._password,
+        }
+        subclass = type('DBLoginRecords', (DBLoginRecords,), _.prefix(members))
+        _.application._record_handler('logins', subclass)
+
+    @classmethod
+    async def args(cls, component_name):
+        # if only one login specified use short argument
+        prefix = f'{component_name}_' if len(_.config['logins']) > 1 else ''
+
+        add_user = getattr(_.args, f'{prefix}add_user')
+        if add_user:
+            username,password = add_user
+            password = _.auth.hash_password(password)
+
+            # the section is optional, it only adds extra columns
+            section = _.config[component_name] if _.config.has_section(component_name) else {}
+            record = dict((k,None) for k in section)
+            record.pop('database', None)
+            record.pop('table',    None)
+
+            record[cls._username] = username
+            record[cls._password] = password
+
+            user = cls._table._from_dict(**record)
+
+            callback = getattr(_.application, f'on_{component_name}_add_user', None)
+            if callback is None:
+                callback = getattr(_.application, 'on_dblogin_add_user', None)
+            if callback:
+                await _.wait(callback(component_name, user))
+
+            await cls._db.upsert(user)
+            _.application.stop()
+
+        if getattr(_.args, f'{prefix}list_users'):
+            for user in await cls._db.find(cls._table):
+                user = user._as_dict()
+                user.pop(cls._password)
+                print(', '.join(f'{k}: {v}' for k,v in user.items()))
+            _.application.stop()
+
+    @classmethod
+    async def check(cls, username, password):
+        try:
+            record = await cls._db.find_one(cls._table, username)
+        except _.error as e:
+            logging.warning('%s', e)
+            record = None
+
+        if record is None:
+            logging.warning('No user: %s', username)
+            return None
+
+        stored = record[cls._password]
+        # hashing is CPU bound so keep it off the event loop
+        if not await asyncio.to_thread(_.auth.verify_password, password, stored, username):
+            logging.warning('Bad password: %s', username)
+            return None
+
+        # transparently upgrade legacy or weaker hashes
+        if _.auth.needs_rehash(stored):
+            record[cls._password] = await asyncio.to_thread(_.auth.hash_password, password)
+            await cls._db.upsert(record)
+
+        return record
+
+    async def post(self):
+        username = self.get_argument('username', None)
+        password = self.get_argument('password', None)
+
+        if username is None or password is None:
+            raise _.HTTPError(500)
+
+        user = await self.check(username, password)
+        if user:
+            await self.on_login_success(user)
+        else:
+            await self.on_login_failure()
+
+
+class DBLoginRecords(_.handlers.Protected):
+    # READ
+    @_.auth.protected
+    async def get(self, username=None):
+        if username:
+            record = await self._db.find_one(self._table, username)
+            record = record._as_dict()
+            record.pop(self._password, None)
+            self.write(record)
+        else:
+            records = await self._db.find(self._table)
+            data = []
+            for record in records:
+                record = record._as_dict()
+                record.pop(self._password, None)
+                data.append(record)
+            self.write({'data':data})
+
+    # UPDATE
+    @_.auth.protected
+    async def put(self, username=None):
+        try:
+            data = json.loads(self.request.body)
+        except json.decoder.JSONDecodeError:
+            raise _.HTTPError(500)
+
+        username = data.get(self._username, None)
+        password = data.pop(self._password, None)
+        if not username or not password:
+            raise _.HTTPError(500)
+
+        entry = dict(_.config[self._component])
+        entry.pop('database', None)
+        entry.pop('table', None)
+        prune = list(entry.keys()) + [self._username, self._password]
+
+        for key in list(data.keys()):
+            if key not in prune:
+                data.pop(key)
+
+        user = self._table()
+        user(**data)
+
+        callback = getattr(_.application, f'on_{self._component}_add_user', None)
+        if callback is None:
+            callback = getattr(_.application, 'on_dblogin_add_user', None)
+        if callback:
+            await _.wait(callback(self._component, user))
+
+        if not user[self._password]:
+            password = await asyncio.to_thread(_.auth.hash_password, password)
+            user[self._password] = password
+
+        await self._db.insert(user)
+        self.set_status(204)
+
+    # DELETE
+    @_.auth.protected
+    async def delete(self, username=None):
+        self.set_status(204)
+        if username is None:
+            return
+
+        user = await self._db.find_one(self._table, username)
+        await self._db.delete(user)
+
+        callback = getattr(_.application, f'on_{self._component}_delete', None)
+        if callback is None:
+            callback = getattr(_.application, 'on_dblogin_delete', None)
+        if callback:
+            await _.wait(callback(self._component, username))

_/logins/facebook.py

@@ -0,0 +1,40 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import datetime
+
+import _
+
+import tornado.auth
+import tornado.web
+
+
+class Facebook(_.logins.Login, tornado.auth.FacebookGraphMixin):
+    @classmethod
+    async def init(cls, component_name, **kwds):
+        cls.extra = {"scope": "read_stream,offline_access"}
+
+    async def get(self):
+        try:
+            code = self.get_argument('code', None)
+            if not code:
+                self.authorize_redirect(
+                    redirect_uri  = self.redirect_uri,
+                    client_id     = self.client_id,
+                    extra_params  = self.extra
+                    )
+            else:
+                user = await self.get_authenticated_user(
+                    redirect_uri  = self.redirect_uri,
+                    client_id     = self.client_id,
+                    client_secret = self.client_secret,
+                    code          = code,
+                    )
+            await self.on_login_success(user)
+        except tornado.httpclient.HTTPClientError as e:
+            await self.on_login_failure(str(e))

_/logins/gitlab.py

@@ -0,0 +1,58 @@
+#
+# (c) 2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+# This is for logging into GitLab servers and serves as an example
+# of implementing an OAuth2 handler for any service that supports it
+
+# For admins go to http(s)://your.gitlab.server/admin/applications and click "New application"
+# For users  go to http(s)://your.gitlab.server/-/profile/applications
+# For groups go to http(s)://your.gitlab.server/groups/(group)/-/settings/applications
+#
+# Pick a "Name" for the application
+#
+# Set the "Redirect URI" to http(s)://your.underscore.app/login/gitlab
+# (or replace gitlab at the end with whatever unique name assigned in the ini file)
+#
+# Select Trusted and Confidential
+#
+# "read_user" is the only scope required by this login plugin
+#
+# Click "Save application"
+#
+# Copy "Application ID" as client_id and copy "Secret" as client_secret in the ini
+#
+# Click "Continue"
+#
+# Your underscore app can now authenticate via your GitLab server
+#
+
+# [logins]
+# gitlab
+#
+# [gitlab]
+# gitlab        = https://your.gitlab.server
+# client_id     = <client_id>
+# client_secret = <client_secret>
+
+
+import _
+
+from .oauth2 import OAuth2
+
+
+class GitLab(OAuth2, _.logins.Login):
+    @classmethod
+    async def init(cls, component_name, gitlab, **kwds):
+        cls.scope = ['read_user']
+
+        cls._OAUTH_AUTHORIZE_URL    = f'{gitlab}/oauth/authorize'
+        cls._OAUTH_ACCESS_TOKEN_URL = f'{gitlab}/oauth/token'
+        cls._OAUTH_USERINFO_URL     = f'{gitlab}/api/v4/user'
+        cls._OAUTH_SETTINGS_KEY     = f'{component_name}_oauth'
+
+        await super().init(component_name, **kwds)

_/logins/google.py

@@ -0,0 +1,20 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import _
+
+from .oauth2 import OAuth2
+
+
+class Google(OAuth2, _.logins.Login):
+    @classmethod
+    async def init(cls, component_name, **kwds):
+        cls.scope = ['email']
+        cls.extra = {'approval_prompt': 'auto'}
+
+        await super().init(component_name, **kwds)

_/logins/htpasswd.py

@@ -0,0 +1,47 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import os
+import hashlib
+import base64
+
+import _
+
+
+# this is opening the file and scanning it for every login, which is fine
+# for small projects with a limited number of users.
+#
+# Passwords can be managed with Apache's htpasswd program
+
+
+class Htpasswd(_.logins.Login):
+    async def post(self):
+        username = self.get_argument('username', '')
+        password = self.get_argument('password', '')
+        password = password.encode('utf-8')
+        password = b'{SHA}' + base64.b64encode(hashlib.sha1(password).digest())
+        password = password.decode('ascii')
+
+        path = _.paths(_.config.get('simple', 'path'))
+
+        fp = open(path, 'r')
+        for line in fp:
+            if not line:
+                continue
+            entry,hash = line.split(':', 1)
+
+            if entry != username:
+                continue
+
+            if hash.rstrip() != password:
+                break
+
+            await self.on_login_success(user)
+            return
+
+        await self.on_login_failure()

_/logins/oauth2.py

@@ -0,0 +1,52 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import tornado.auth
+import tornado.httpclient
+
+import _
+
+
+# for Google and Gitlab the GoogleOAuth2Mixin is a good starting point
+class OAuth2(tornado.auth.GoogleOAuth2Mixin):
+    extra = None
+
+    @classmethod
+    async def init(cls, component_name, client_id, client_secret, **kwds):
+        _.application.settings[cls._OAUTH_SETTINGS_KEY] = {
+            'key'    : client_id,
+            'secret' : client_secret,
+        }
+
+    async def get(self):
+        code = self.get_argument('code', None)
+        if not code:
+            # make the initial request to the OAuth2 service
+            self.authorize_redirect(
+                redirect_uri  = self.redirect_uri,
+                client_id     = self._client_id,
+                scope         = self.scope,
+                response_type = 'code',
+                extra_params  = self.extra
+                )
+        else:
+            try:
+                # the OAuth2 service will callback with a code
+                # pass it to the get_authenticated_user function defined
+                # in GitLabAuthMixin
+                self.oauth = await self.get_authenticated_user(
+                    redirect_uri = self.redirect_uri,
+                    code         = code,
+                    )
+                user = await self.oauth2_request(
+                    self._OAUTH_USERINFO_URL,
+                    access_token = self.oauth["access_token"]
+                    )
+                await self.on_login_success(user)
+            except tornado.httpclient.HTTPClientError as e:
+                await self.on_login_failure(str(e))

_/logins/slap.py

@@ -0,0 +1,56 @@
+#
+# (c) 2015-2023 Matthew Shaw
+#
+# Authors
+# =======
+# Matthew Shaw <mshaw.cx@gmail.com>
+#
+
+import time
+import logging
+
+import tornado.escape
+
+import _
+
+
+try:
+    import ldap
+except ImportError:
+    raise _.error('Missing LDAP module')
+
+
+class Slap(_.logins.Login):
+    @classmethod
+    async def init(cls, component_name, **kwds):
+        _.argparser.add_argument(f'--{component_name}-list-users',
+            action='store_true',
+            help='list users'
+            )
+
+    @classmethod
+    async def check(cls, username, password):
+        try:
+            dn = cls.dn.format(username)
+            ldap_server = ldap.initialize(cls.uri)
+            ldap_server.bind_s(dn, password)
+            ldap_server.unbind()
+            return True
+        except ldap.NO_SUCH_OBJECT:
+            logging.warn('Could not find record for user: %s', username)
+        except ldap.INVALID_CREDENTIALS:
+            logging.warn('Invalid credentials for user: %s', username)
+        except ldap.SERVER_DOWN:
+            logging.error('Could not connect to LDAP server: %s', cls.uri)
+        return None
+
+    async def post(self):
+        username = self.get_argument('username', '')
+        username = tornado.escape.xhtml_escape(username)
+        password = self.get_argument('password', '')
+
+        ok = await self.check(username, password)
+        if ok:
+            await self.on_login_success({'username':username})
+        else:
+            await self.on_login_failure()

_/records/Protobuf.proto

@@ -0,0 +1,21 @@
+syntax = "proto3";
+
+import "google/protobuf/descriptor.proto";
+
+
+extend google.protobuf.MessageOptions {
+    string id         = 50001;
+    bool   no_table   = 50002;
+    bool   no_handler = 50003;
+    string refs       = 50004;
+}
+
+extend google.protobuf.FieldOptions {
+    bool   pkey       = 50001;
+    bool   no_column  = 50002;
+    bool   uniq       = 50003;
+    bool   required   = 50004;
+    string ref        = 50005;
+    string paired     = 50006;
+    string subtype    = 50007;
+}