evlet 0.1.0__py3-none-any.whl

evlet/__init__.py

@@ -0,0 +1,48 @@
+"""Public APIs for models, persistence, queries, and explicit migrations."""
+
+from .app import Application
+from .database import ConflictError, Database, NotFoundError
+from .fields import (Boolean, Currency, Date, DateTime, Decimal, Email, Integer,
+                     Link, LongText, Select, Text, URL)
+from .migrations import AddField, AddIndex, CreateModel, Migration, RenameField, SchemaError
+from .models import Model, Registry, ValidationError
+
+__all__ = [
+    "AddField", "AddIndex", "Application", "Boolean", "ConflictError", "CreateModel",
+    "Currency", "Database", "Date", "DateTime", "Decimal", "Email", "Integer", "Link",
+    "LongText", "Migration", "Model", "NotFoundError", "Registry", "RenameField",
+    "SchemaError", "Select", "Text", "URL", "ValidationError",
+]
+
+from .auth import LocalAuth, User
+from .permissions import Policy, Rule
+from .business import Action, ChildTable
+
+__all__ += ["Action", "ChildTable", "LocalAuth", "Policy", "Rule", "User"]
+
+from .storage import LocalFileStorage, SQLiteStorage, StorageError
+
+__all__ += ["LocalFileStorage", "SQLiteStorage", "StorageError"]
+
+from .tenancy import Tenant, TenantApplication, TenantRegistry
+
+__all__ += ["Tenant", "TenantApplication", "TenantRegistry"]
+
+from .events import EventStore
+from .jobs import JobContext, JobQueue, JobReceipt, Task
+
+__all__ += ["EventStore", "JobContext", "JobQueue", "JobReceipt", "Task"]
+
+from .object_storage import S3Storage
+from .serverless import LambdaHTTP
+
+__all__ += ["LambdaHTTP", "S3Storage"]
+
+from .connector import ConnectorError, HTTPClient
+from .mcp import MCPServer
+
+__all__ += ["ConnectorError", "HTTPClient", "MCPServer"]
+
+from .postgres import PostgreSQLDatabase
+
+__all__ += ["PostgreSQLDatabase"]

evlet/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == '__main__':
+    main()

evlet/app.py

@@ -0,0 +1,221 @@
+"""Portable ASGI HTTP and lifespan support without a web framework dependency."""
+
+import asyncio
+import json
+import logging
+import sqlite3
+from urllib.parse import parse_qs
+
+from .database import ConflictError, NotFoundError
+from .models import ValidationError
+from .auth import AccessError
+from .business import Business, Download
+from .storage import StorageError
+
+logger = logging.getLogger(__name__)
+MAX_BODY_BYTES = 64 * 1024
+
+
+class HTTPError(Exception):
+    def __init__(self, status, message, headers=()):
+        self.status = status
+        self.message = message
+        self.headers = headers
+
+
+class Application:
+    def __init__(self, database, *, auth=None, policy=None, actions=(), children=(), attachments=(), storage=None, jobs=None, events=None):
+        self.database = database
+        self.registry = database.registry
+        if auth is None and (policy is not None or actions or children or attachments or storage is not None or jobs is not None or events is not None):
+            raise ValueError("Business features require authentication")
+        self.business = None if auth is None else Business(database, auth, policy=policy, actions=actions, children=children, attachments=attachments, storage=storage, jobs=jobs, events=events)
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "lifespan":
+            await self._lifespan(receive, send)
+            return
+        if scope["type"] == "websocket":
+            await send({"type": "websocket.close", "code": 1008})
+            return
+        if scope["type"] != "http":
+            raise ValueError("Unsupported ASGI scope")
+        headers = []
+        try:
+            if scope['path'] == '/api/_events/stream' and self.business:
+                await self._event_stream(scope, receive, send)
+                return
+            body = None
+            if scope["method"] in ("POST", "PATCH"):
+                content_type = dict(scope.get("headers", [])).get(b"content-type", b"")
+                if content_type.split(b";", 1)[0].strip().lower() != b"application/json":
+                    raise HTTPError(415, "Send application/json")
+                data = bytearray()
+                while True:
+                    event = await receive()
+                    if event["type"] == "http.disconnect":
+                        return
+                    data.extend(event.get("body", b""))
+                    maximum = 1500000 if self.business and scope['path'].endswith('/attachments') else MAX_BODY_BYTES
+                    if len(data) > maximum:
+                        raise HTTPError(413, "Request body exceeds the allowed size")
+                    if not event.get("more_body", False):
+                        break
+                try:
+                    body = json.loads(data, parse_constant=self._invalid_constant)
+                except (ValueError, UnicodeError, RecursionError) as exc:
+                    raise HTTPError(400, "Malformed JSON") from exc
+                if not isinstance(body, dict):
+                    raise HTTPError(422, "Expected a JSON object")
+            status, payload, headers = await asyncio.to_thread(self._dispatch, scope, body)
+        except AccessError as exc:
+            status, payload = exc.status, {"error": exc.message}
+        except HTTPError as exc:
+            status, payload, headers = exc.status, {"error": exc.message}, list(exc.headers)
+        except ValidationError as exc:
+            status, payload = 422, {"error": "Validation failed", "fields": exc.errors}
+        except NotFoundError:
+            status, payload = 404, {"error": "Record not found"}
+        except ConflictError as exc:
+            status, payload = 409, {"error": str(exc)}
+        except StorageError:
+            logger.exception("Attachment storage failed")
+            status, payload = 503, {"error": "Attachment temporarily unavailable"}
+        except sqlite3.OperationalError:
+            logger.exception("Database operation failed")
+            status, payload = 503, {"error": "Database temporarily unavailable"}
+        except Exception:
+            logger.exception("Unhandled request failure")
+            status, payload = 500, {"error": "Internal server error"}
+        download = isinstance(payload, Download)
+        encoded = payload.content if download else b"" if status == 204 else json.dumps(payload, ensure_ascii=True, allow_nan=False).encode("utf-8")
+        response_headers = [(b"x-content-type-options", b"nosniff"), (b"cache-control", b"no-store"), *headers]
+        if status != 204:
+            if not download:
+                response_headers.append((b"content-type", b"application/json; charset=utf-8"))
+            response_headers.append((b"content-length", str(len(encoded)).encode()))
+        await send({"type": "http.response.start", "status": status, "headers": response_headers})
+        await send({"type": "http.response.body", "body": encoded})
+
+    async def _event_stream(self, scope, receive, send):
+        page = await asyncio.to_thread(self.business.event_page, scope)
+        await send({'type': 'http.response.start', 'status': 200, 'headers': [
+            (b'content-type', b'text/event-stream'), (b'cache-control', b'no-store'),
+            (b'x-accel-buffering', b'no'), (b'x-content-type-options', b'nosniff')]})
+        async def disconnected():
+            while (await receive())['type'] != 'http.disconnect':
+                pass
+        disconnect = asyncio.create_task(disconnected())
+        try:
+            for iteration in range(25):
+                encoded = ('id: ' + page['cursor'] + '\nevent: evlet\ndata: ' + json.dumps(page) + '\n\n').encode()
+                await send({'type': 'http.response.body', 'body': encoded, 'more_body': True})
+                done, _ = await asyncio.wait({disconnect}, timeout=0.05 if page['more'] else 1)
+                if done:
+                    return
+                headers = [(key, value) for key, value in scope.get('headers', []) if key != b'last-event-id']
+                headers.append((b'last-event-id', page['cursor'].encode()))
+                try:
+                    page = await asyncio.to_thread(self.business.event_page, {**scope, 'headers': headers})
+                except AccessError:
+                    await send({'type': 'http.response.body', 'body': b'event: unavailable\ndata: {}\n\n', 'more_body': True})
+                    return
+                except Exception:
+                    logger.exception('Event stream failed')
+                    return
+        except OSError:
+            return
+        finally:
+            disconnect.cancel()
+            await asyncio.gather(disconnect, return_exceptions=True)
+            try:
+                await send({'type': 'http.response.body', 'body': b'', 'more_body': False})
+            except OSError:
+                pass
+
+    @staticmethod
+    def _invalid_constant(value):
+        raise ValueError(f"Non-finite JSON number: {value}")
+
+    @staticmethod
+    def _method(method, allowed):
+        if method not in allowed:
+            raise HTTPError(405, "Method not allowed", [
+                (b"allow", ", ".join(allowed).encode())
+            ])
+
+    def _dispatch(self, scope, body):
+        path, method = scope["path"], scope["method"]
+        if path == "/health":
+            self._method(method, ["GET"])
+            self.database.check()
+            return 200, {"status": "ok"}, []
+        if self.business:
+            return self.business.dispatch(scope, body)
+        if path == "/api/schema":
+            self._method(method, ["GET"])
+            return 200, self.registry.ui_schema(), []
+        parts = path.split("/")
+        if len(parts) not in (3, 4) or parts[:2] != ["", "api"]:
+            raise HTTPError(404, "Route not found")
+        model = self.registry.models.get(parts[2])
+        if model is None:
+            raise HTTPError(404, "Model not found")
+        if method in ('POST', 'PATCH'):
+            errors = {name: 'This field is read-only' for name in body
+                      if name in model.__fields__ and model.__fields__[name].read_only}
+            if errors:
+                raise ValidationError(errors)
+        if len(parts) == 4:
+            self._method(method, ["GET", "PATCH", "DELETE"])
+            if not parts[3].isascii() or not parts[3].isdigit() or len(parts[3]) > 19:
+                raise HTTPError(404, "Record not found")
+            record_id = int(parts[3])
+            if method == "DELETE":
+                self.database.delete(model, record_id)
+                return 204, None, []
+            record = (self.database.update(model, record_id, **body) if method == "PATCH"
+                      else self.database.get(model, record_id))
+            return 200, record.to_dict(), []
+        self._method(method, ["GET", "POST"])
+        if method == "POST":
+            record = self.database.create(model, **body)
+            location = f"/api/{parts[2]}/{record.id}".encode()
+            return 201, record.to_dict(), [(b"location", location)]
+        try:
+            if len(scope.get("query_string", b"")) > 8192:
+                raise ValueError("Query exceeds 8 KiB")
+            query = parse_qs(scope.get("query_string", b"").decode("ascii"),
+                             keep_blank_values=True, max_num_fields=10)
+            if set(query) - {"limit", "offset", "filters", "order_by", "q"} or any(len(v) != 1 for v in query.values()):
+                raise ValueError("Unknown or repeated query parameters")
+            limit = int(query.get("limit", ["50"])[0])
+            offset = int(query.get("offset", ["0"])[0])
+            filters = json.loads(query["filters"][0], parse_constant=self._invalid_constant) if "filters" in query else None
+            order_by = query["order_by"][0].split(",") if "order_by" in query else None
+        except (ValueError, UnicodeError, RecursionError) as exc:
+            raise HTTPError(422, "Use valid limit, offset, filters JSON, and order_by parameters") from exc
+        records, total = self.database.page(model, limit=limit, offset=offset, filters=filters, order_by=order_by, search=query.get("q", [""])[0])
+        return 200, {"items": [record.to_dict() for record in records],
+                     "limit": limit, "offset": offset, "total": total}, []
+
+    def initialize(self):
+        self.database.initialize()
+        if self.business:
+            self.business.initialize()
+
+    async def _lifespan(self, receive, send):
+        while True:
+            event = await receive()
+            if event["type"] == "lifespan.startup":
+                try:
+                    await asyncio.to_thread(self.initialize)
+                except Exception:
+                    logger.exception("Database initialization failed")
+                    await send({"type": "lifespan.startup.failed", "message": "Database initialization failed"})
+                    return
+                await send({"type": "lifespan.startup.complete"})
+            elif event["type"] == "lifespan.shutdown":
+                await asyncio.to_thread(self.database.close)
+                await send({"type": "lifespan.shutdown.complete"})
+                return

evlet/auth.py

@@ -0,0 +1,224 @@
+"""Local accounts and revocable cookie sessions for a single application database."""
+
+from dataclasses import dataclass
+import hashlib
+import hmac
+from http.cookies import SimpleCookie, CookieError
+import ipaddress
+import re
+import secrets
+import time
+from urllib.parse import urlsplit
+
+from .models import ValidationError
+
+ROLES = ('admin', 'editor', 'viewer')
+
+
+class AccessError(Exception):
+    def __init__(self, status, message):
+        self.status, self.message = status, message
+
+
+@dataclass(frozen=True)
+class User:
+    id: int
+    username: str
+    role: str
+
+    def public(self):
+        return {'id': self.id, 'username': self.username, 'role': self.role}
+
+
+def password_hash(password, salt=None):
+    if not isinstance(password, str) or not 15 <= len(password) <= 128:
+        raise ValidationError({'password': 'Use between 15 and 128 characters'})
+    try:
+        encoded = password.encode('utf-8')
+    except UnicodeError:
+        raise ValidationError({'password': 'Use valid Unicode text'})
+    salt = secrets.token_hex(16) if salt is None else salt
+    digest = hashlib.scrypt(encoded, salt=bytes.fromhex(salt),
+                            n=2**17, r=8, p=1, maxmem=256 * 1024 * 1024).hex()
+    return f'scrypt:{salt}:{digest}'
+
+
+class LocalAuth:
+    def __init__(self, database, *, origins, secure_cookies=True, allow_setup=False, cookie_name='evlet_session'):
+        if cookie_name not in ('evlet_session', '__Host-evlet_session') or (cookie_name.startswith('__Host-') and not secure_cookies):
+            raise ValueError('Invalid session cookie configuration')
+        self.cookie_name = cookie_name
+        self.database = database
+        self.origins = frozenset(origins)
+        if not self.origins:
+            raise ValueError('Configure explicit browser origins')
+        for origin in self.origins:
+            url = urlsplit(origin)
+            if url.scheme not in ('http', 'https') or not url.netloc or url.path or url.query or url.fragment or url.username:
+                raise ValueError('Use exact HTTP origins without paths')
+            if not secure_cookies and url.hostname not in ('localhost', '127.0.0.1', '::1') and not (url.hostname or '').endswith('.localhost'):
+                raise ValueError('Insecure cookies are limited to loopback development origins')
+        self.hosts = {urlsplit(origin).netloc.encode() for origin in self.origins}
+        self.secure_cookies = secure_cookies
+        self.allow_setup = allow_setup
+
+    def initialize(self):
+        with self.database.transaction() as tx:
+            tx.connection.execute('CREATE TABLE IF NOT EXISTS evlet_users (id INTEGER PRIMARY KEY AUTOINCREMENT, username TEXT NOT NULL UNIQUE, password TEXT NOT NULL, role TEXT NOT NULL, active INTEGER NOT NULL DEFAULT 1)')
+            tx.connection.execute('CREATE TABLE IF NOT EXISTS evlet_sessions (token TEXT PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES evlet_users(id) ON DELETE CASCADE, csrf TEXT NOT NULL, expires INTEGER NOT NULL)')
+            tx.connection.execute('CREATE TABLE IF NOT EXISTS evlet_login_limits (client TEXT PRIMARY KEY, attempts INTEGER NOT NULL, resets INTEGER NOT NULL)')
+
+            tx.connection.execute('CREATE INDEX IF NOT EXISTS evlet_session_user ON evlet_sessions(user_id)')
+            tx.connection.execute('CREATE INDEX IF NOT EXISTS evlet_session_expiry ON evlet_sessions(expires)')
+            tx.connection.execute('CREATE INDEX IF NOT EXISTS evlet_login_reset ON evlet_login_limits(resets)')
+
+    def guard(self, scope):
+        protected = {b'host', b'origin', b'cookie', b'x-csrf-token', b'x-evlet-request', b'sec-fetch-site'}
+        seen = set()
+        for key, _ in scope.get('headers', []):
+            key = key.lower()
+            if key in protected and key in seen:
+                raise AccessError(403, 'Repeated security header')
+            seen.add(key)
+        headers = dict(scope.get('headers', []))
+        if headers.get(b'host') not in self.hosts:
+            raise AccessError(403, 'Unrecognized host')
+        origin = headers.get(b'origin')
+        if origin is not None and origin.decode('latin1') not in self.origins:
+            raise AccessError(403, 'Unrecognized origin')
+        if headers.get(b'sec-fetch-site') == b'cross-site':
+            raise AccessError(403, 'Cross-site request rejected')
+        if scope['method'] not in ('GET', 'HEAD') and headers.get(b'x-evlet-request') != b'1':
+            raise AccessError(403, 'Missing request protection header')
+
+    def token(self, scope):
+        cookie = SimpleCookie()
+        try:
+            cookie.load(dict(scope.get('headers', [])).get(b'cookie', b'').decode('latin1'))
+            value = cookie.get(self.cookie_name)
+            token = value.value if value else ''
+            return hashlib.sha256(token.encode()).hexdigest()
+        except (CookieError, UnicodeError):
+            return ''
+
+    def session(self, scope):
+        with self.database._connection() as connection:
+            row = connection.execute('SELECT u.id, u.username, u.role, s.csrf FROM evlet_sessions s JOIN evlet_users u ON u.id=s.user_id WHERE s.token=? AND s.expires>? AND u.active=1',
+                                     (self.token(scope), int(time.time()))).fetchone()
+        if row is None:
+            raise AccessError(401, 'Sign in to continue')
+        if scope['method'] not in ('GET', 'HEAD'):
+            supplied = dict(scope.get('headers', [])).get(b'x-csrf-token', b'')
+            if not hmac.compare_digest(supplied, row['csrf'].encode('ascii')):
+                raise AccessError(403, 'Invalid request token')
+        return User(row['id'], row['username'], row['role']), row['csrf']
+
+    @staticmethod
+    def account_values(body):
+        if set(body) - {'username', 'password', 'role'}:
+            raise ValidationError({'_form': 'Unknown account field'})
+        name = body.get('username', '')
+        role = body.get('role', 'viewer')
+        if not isinstance(name, str) or not re.fullmatch(r'[a-zA-Z0-9_.-]{3,64}', name):
+            raise ValidationError({'username': 'Use 3 to 64 letters, numbers, dots, hyphens, or underscores'})
+        if role not in ROLES:
+            raise ValidationError({'role': 'Choose admin, editor, or viewer'})
+        return name.lower(), password_hash(body.get('password')), role
+
+    def create_user(self, **values):
+        name, password, role = self.account_values(values)
+        with self.database.transaction() as tx:
+            user_id = tx.connection.execute('INSERT INTO evlet_users(username,password,role) VALUES (?,?,?)', (name, password, role)).lastrowid
+        return User(user_id, name, role)
+
+    def setup_needed(self):
+        with self.database._connection() as connection:
+            return not connection.execute('SELECT 1 FROM evlet_users LIMIT 1').fetchone()
+
+    def setup(self, scope, body):
+        try:
+            loopback = ipaddress.ip_address(scope.get('client', ('',))[0]).is_loopback
+        except ValueError:
+            loopback = False
+        if not self.allow_setup or not loopback or not self.setup_needed():
+            raise AccessError(403, 'Initial setup is unavailable')
+        name, password, _ = self.account_values({**body, 'role': 'admin'})
+        with self.database.transaction() as tx:
+            if tx.connection.execute('SELECT 1 FROM evlet_users LIMIT 1').fetchone():
+                raise AccessError(409, 'An administrator already exists')
+            tx.connection.execute('INSERT INTO evlet_users(username,password,role) VALUES (?,?,?)', (name, password, 'admin'))
+
+    def login(self, scope, body):
+        if set(body) != {'username', 'password'} or not all(isinstance(body[k], str) for k in body):
+            raise AccessError(401, 'Invalid username or password')
+        now = int(time.time())
+        client = hashlib.sha256(scope.get('client', ('unknown',))[0].encode()).hexdigest()
+        with self.database.transaction() as tx:
+            tx.connection.execute('DELETE FROM evlet_login_limits WHERE resets<=?', (now,))
+            tx.connection.execute('DELETE FROM evlet_sessions WHERE expires<=?', (now,))
+            row = tx.connection.execute('SELECT attempts FROM evlet_login_limits WHERE client=?', (client,)).fetchone()
+            if row and row['attempts'] >= 10:
+                raise AccessError(429, 'Too many sign-in attempts. Try again in 15 minutes.')
+            tx.connection.execute('INSERT INTO evlet_login_limits VALUES (?,1,?) ON CONFLICT(client) DO UPDATE SET attempts=evlet_login_limits.attempts+1', (client, now + 900))
+            account = tx.connection.execute('SELECT * FROM evlet_users WHERE username=?', (body['username'].lower(),)).fetchone()
+        stored = account['password'] if account else 'scrypt:' + '00' * 16 + ':' + '00' * 64
+        try:
+            candidate = password_hash(body['password'], stored.split(':')[1])
+        except (ValueError, UnicodeError):
+            candidate = ''
+        if not hmac.compare_digest(candidate, stored) or not account or not account['active']:
+            raise AccessError(401, 'Invalid username or password')
+        token, csrf = secrets.token_urlsafe(32), secrets.token_hex(32)
+        with self.database.transaction() as tx:
+            # A password/role change during hashing must not revive an old login.
+            current = tx.connection.execute('SELECT * FROM evlet_users WHERE id=?', (account['id'],)).fetchone()
+            if not current or not current['active'] or current['password'] != stored or current['role'] != account['role']:
+                raise AccessError(401, 'Invalid username or password')
+            tx.connection.execute('DELETE FROM evlet_login_limits WHERE client=?', (client,))
+            tx.connection.execute('DELETE FROM evlet_sessions WHERE token=?', (self.token(scope),))
+            tx.connection.execute('INSERT INTO evlet_sessions VALUES (?,?,?,?)', (hashlib.sha256(token.encode()).hexdigest(), account['id'], csrf, now + 28800))
+        return {'user': User(account['id'], account['username'], account['role']).public(), 'csrf': csrf}, [self.cookie(token)]
+
+    def cookie(self, token):
+        value = f'{self.cookie_name}={token}; HttpOnly; SameSite=Strict; Path=/; Max-Age={28800 if token else 0}'
+        if self.secure_cookies:
+            value += '; Secure'
+        return b'set-cookie', value.encode()
+
+    def logout(self, scope):
+        with self.database.transaction() as tx:
+            tx.connection.execute('DELETE FROM evlet_sessions WHERE token=?', (self.token(scope),))
+        return [self.cookie('')]
+
+    def users(self):
+        return self.user_page()['items']
+
+    def user_page(self, offset=0):
+        if type(offset) is not int or not 0 <= offset <= 2**63-1:
+            raise ValidationError({'offset': 'Use a nonnegative offset'})
+        with self.database._connection() as connection:
+            connection.execute('BEGIN')
+            items = [dict(row) for row in connection.execute('SELECT id,username,role,active FROM evlet_users ORDER BY id LIMIT 100 OFFSET ?', (offset,))]
+            total = connection.execute('SELECT count(*) FROM evlet_users').fetchone()[0]
+            return {'items': items, 'total': total, 'offset': offset, 'limit': 100}
+
+    def update_user(self, user_id, body):
+        if not body or set(body) - {'role', 'active', 'password'}:
+            raise ValidationError({'_form': 'Use role, active, or password'})
+        if 'role' in body and body['role'] not in ROLES:
+            raise ValidationError({'role': 'Unknown role'})
+        if 'active' in body and type(body['active']) is not bool:
+            raise ValidationError({'active': 'Use true or false'})
+        changes = dict(body)
+        if 'password' in changes:
+            changes['password'] = password_hash(changes['password'])
+        with self.database.transaction() as tx:
+            row = tx.connection.execute('SELECT * FROM evlet_users WHERE id=?', (user_id,)).fetchone()
+            if not row:
+                raise AccessError(404, 'Account not found')
+            if row['role'] == 'admin' and row['active'] and (changes.get('role', 'admin') != 'admin' or not changes.get('active', True)):
+                if tx.connection.execute("SELECT count(*) FROM evlet_users WHERE role='admin' AND active=1").fetchone()[0] == 1:
+                    raise AccessError(409, 'Keep at least one active administrator')
+            for key, value in changes.items():
+                tx.connection.execute(f'UPDATE evlet_users SET {key}=? WHERE id=?', (value, user_id))
+            tx.connection.execute('DELETE FROM evlet_sessions WHERE user_id=?', (user_id,))