stkit 17.0.0__py3-none-any.whl

stk/security.py

@@ -0,0 +1,145 @@
+"""Host controls for all routes and server-side session transitions."""
+
+import secrets
+from datetime import datetime
+from urllib.parse import urlsplit
+
+from quart import abort, current_app, g, request, session
+from quart_security import SecurityState, current_user
+from quart_security.breach import password_is_breached
+from quart_security.password import validate_password
+from sqlalchemy import delete, select
+
+from stk.user.models import Session
+
+
+def csrf_exempt(view):
+    """Skip the CSRF token check for this view, e.g. a third-party webhook.
+
+    The view must authenticate the request itself (e.g. an HMAC signature).
+    Host, API body, and pagination checks still apply. Place it below the
+    route decorator: ``@bp.post("/webhook")`` then ``@csrf_exempt``.
+    """
+    view._stk_csrf_exempt = True
+    return view
+
+
+def register_security_controls(app):
+    @app.before_request
+    async def protect_request():
+        public_url = app.config.get("STK_PUBLIC_URL")
+        if (
+            public_url
+            and request.path != "/health"
+            and request.host != urlsplit(public_url).netloc
+        ):
+            abort(400, description="Invalid host")
+        g.previous_auth_token = session.get("_id")
+        g.previous_second_factor = session.get("tf_user_id")
+        exempt = getattr(
+            current_app.view_functions.get(request.endpoint), "_stk_csrf_exempt", False
+        )
+        if request.method in {"POST", "PUT", "PATCH", "DELETE"}:
+            expected = session.get("_csrf_token")
+            supplied = request.headers.get("X-CSRFToken")
+            if not supplied:
+                supplied = (await request.form).get("csrf_token")
+            if not supplied:
+                body = await request.get_json(silent=True)
+                supplied = body.get("csrf_token") if isinstance(body, dict) else None
+            if not exempt and (
+                not isinstance(expected, str)
+                or not isinstance(supplied, str)
+                or not secrets.compare_digest(expected, supplied)
+            ):
+                abort(400, description="Invalid CSRF token")
+            if request.path.startswith("/api/") and request.method in {
+                "POST",
+                "PUT",
+                "PATCH",
+            }:
+                body = await request.get_json(silent=True)
+                if not isinstance(body, dict) or (
+                    "item" in body and not isinstance(body["item"], dict)
+                ):
+                    abort(400, description="Expected a JSON object")
+        if request.path.startswith("/api/"):
+            for name, low, high in (("page", 1, 100000), ("per_page", 1, 100)):
+                if name in request.args:
+                    try:
+                        value = int(request.args[name])
+                    except ValueError:
+                        abort(400, description="Invalid pagination")
+                    if not low <= value <= high:
+                        abort(400, description="Invalid pagination")
+
+    @app.after_request
+    async def synchronize_session(response):
+        if session.get("_csrf_token") or session.get("_id"):
+            response.headers.setdefault("Cache-Control", "private, no-store")
+        response.headers.setdefault("X-Content-Type-Options", "nosniff")
+        response.headers.setdefault("X-Frame-Options", "DENY")
+        response.headers.setdefault("Referrer-Policy", "same-origin")
+        response.headers.setdefault(
+            "Content-Security-Policy",
+            "frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+        )
+        if "previous_auth_token" not in g:
+            return response
+        previous = g.get("previous_auth_token")
+        token = session.get("_id")
+        if previous != token or g.get("previous_second_factor") != session.get(
+            "tf_user_id"
+        ):
+            interface = app.session_interface
+            if hasattr(session, "sid"):
+                await interface.delete(key=interface.key_prefix + session.sid, app=app)
+                session.sid = secrets.token_urlsafe(32)
+                session.modified = True
+            db = g.get("db_session")
+            if db is not None:
+                old = None
+                if previous and previous != token:
+                    await db.execute(
+                        delete(SecurityState).where(SecurityState.token == previous)
+                    )
+                    old = await db.scalar(
+                        select(Session).where(Session.session_token == previous)
+                    )
+                    if old:
+                        old.is_active = False
+                if token and current_user.is_authenticated:
+                    record = await db.scalar(
+                        select(Session).where(Session.session_token == token)
+                    )
+                    if record is None:
+                        record = await Session.create_session(
+                            current_user.id,
+                            token,
+                            request.remote_addr,
+                            meta=old.meta if old else None,
+                        )
+                    record.expires_at = datetime.now() + app.permanent_session_lifetime
+                await db.commit()
+        return response
+
+
+async def check_password_policy(password):
+    from quart import current_app
+
+    if not isinstance(password, str) or len(password) > 1024:
+        abort(400, description="Invalid password")
+    errors = validate_password(
+        password, min_length=current_app.config["SECURITY_PASSWORD_LENGTH_MIN"]
+    )
+    if errors:
+        abort(400, description=errors[0])
+    if current_app.config.get("SECURITY_PASSWORD_BREACH_CHECK", True):
+        breached = await password_is_breached(
+            password,
+            count_min=current_app.config.get("SECURITY_PASSWORD_BREACH_COUNT_MIN", 1),
+        )
+        if breached:
+            abort(
+                400, description="Choose a password that has not appeared in a breach"
+            )

stk/settings.py

@@ -0,0 +1,147 @@
+import importlib.util
+import os
+from datetime import timedelta
+
+from dotenv import find_dotenv, load_dotenv
+
+# Detect optional dependencies (installed via --extra full)
+REDIS_AVAILABLE = importlib.util.find_spec("redis") is not None
+
+# The app's .env, found from the working directory: stk itself may live in site-packages.
+load_dotenv(find_dotenv(usecwd=True))
+
+# Session configuration - computed at module level
+_redis_url = os.environ.get("REDIS_URL") or os.environ.get("REDIS_SESSION")
+if REDIS_AVAILABLE and _redis_url:
+    _SESSION_TYPE = "redis"
+else:
+    # No server-side sessions — Quart's built-in cookie sessions will be used
+    _SESSION_TYPE = None
+
+
+class Config:
+    # Checked when the app is built, so importing stk needs no environment.
+    SECRET_KEY = os.environ.get("SECRET_KEY")
+    # Product name and sign-in copy; apps set these instead of editing templates
+    APP_NAME = os.environ.get("APP_NAME", "stk")
+    APP_TAGLINE = os.environ.get("APP_TAGLINE", "Secure. Scalable. Swift.")
+    APP_DESCRIPTION = os.environ.get("APP_DESCRIPTION", "")
+
+    # Unset means SQLite at instance/stk.db, next to the app's package.
+    SQLALCHEMY_DATABASE_URI = os.environ.get("SQLALCHEMY_DATABASE_URI")
+
+    STK_PUBLIC_URL = os.environ.get("STK_PUBLIC_URL")
+
+    # security
+    SECURITY_REGISTERABLE = (
+        os.environ.get("SECURITY_REGISTERABLE", "False").lower() == "true"
+    )
+    SECURITY_RECOVERABLE = False
+    SECURITY_CONFIRMABLE = False
+    SECURITY_CHANGEABLE = True
+    SECURITY_TRACKABLE = True
+    SECURITY_PASSWORD_HASH = "argon2"
+    SECURITY_PASSWORD_SALT = os.environ.get("SECURITY_PASSWORD_SALT")
+    # quart-security handles email normalization internally
+
+    SECURITY_POST_LOGIN_VIEW = "/dashboard"
+    SECURITY_POST_CONFIRM_VIEW = "/dashboard"
+    SECURITY_POST_REGISTER_VIEW = "/login"
+
+    SECURITY_MULTI_FACTOR_RECOVERY_CODES = True
+    SECURITY_MULTI_FACTOR_RECOVERY_CODES_N = 3
+
+    SECURITY_TWO_FACTOR_ENABLED_METHODS = ["authenticator"]
+    SECURITY_TWO_FACTOR = True
+    _totp_keys = os.environ.get("SECURITY_TOTP_ENCRYPTION_KEYS")
+    SECURITY_TOTP_ENCRYPTION_KEYS = _totp_keys.split(",") if _totp_keys else None
+    SECURITY_API_ENABLED_METHODS = ["session"]
+
+    SECURITY_FRESHNESS = timedelta(minutes=60)
+    SECURITY_FRESHNESS_GRACE_PERIOD = timedelta(minutes=60)
+    SECURITY_PASSWORD_LENGTH_MIN = 12
+
+    SECURITY_TOTP_ISSUER = "stk"
+
+    SECURITY_WAN_RP_ID = os.environ.get("SECURITY_WAN_RP_ID")
+    SECURITY_WAN_EXPECTED_ORIGIN = os.environ.get("SECURITY_WAN_EXPECTED_ORIGIN")
+    SECURITY_WEBAUTHN = True
+    SECURITY_WAN_ALLOW_AS_FIRST_FACTOR = True
+    SECURITY_WAN_ALLOW_AS_MULTI_FACTOR = True
+
+    # Session configuration (quart-session for Redis, Quart cookie sessions otherwise)
+    SESSION_TYPE = _SESSION_TYPE
+    SESSION_URI = _redis_url  # quart-session auto-creates async redis from URI
+    SESSION_KEY_PREFIX = "session:"
+    # quart-session's signer emits a bytes cookie value that modern werkzeug
+    # rejects (500 on login); random session ids don't need signing
+    SESSION_USE_SIGNER = False
+    PERMANENT_SESSION_LIFETIME = 3600
+    SESSION_COOKIE_SECURE = (
+        os.environ.get("SESSION_COOKIE_SECURE", "True").lower() == "true"
+    )
+    SECURITY_COOKIE_SECURE = SESSION_COOKIE_SECURE
+    SESSION_COOKIE_HTTPONLY = (
+        os.environ.get("SESSION_COOKIE_HTTPONLY", "True").lower() == "true"
+    )
+    SESSION_COOKIE_SAMESITE = os.environ.get("SESSION_COOKIE_SAMESITE", "Lax")
+
+    # Session management
+    DISABLE_MULTIPLE_SESSIONS = (
+        os.environ.get("DISABLE_MULTIPLE_SESSIONS", "False").lower() == "true"
+    )
+    # Test-only browser session handoff for agent-driven development.
+    STK_ENV = os.environ.get("STK_ENV", "production")
+    STK_ENABLE_AGENT_LOGIN = (
+        os.environ.get("STK_ENABLE_AGENT_LOGIN", "False").lower() == "true"
+        or os.environ.get("STK_ENABLE_AGENT_LOGIN") == "1"
+    )
+    STK_AGENT_LOGIN_MAX_TTL_SECONDS = int(
+        os.environ.get("STK_AGENT_LOGIN_MAX_TTL_SECONDS", "60")
+    )
+
+    # Email settings (used by aiosmtplib via AsyncMailUtil)
+    MAIL_SERVER = os.environ.get("MAIL_SERVER")
+    MAIL_PORT = 465
+    MAIL_USE_SSL = True
+    MAIL_USERNAME = os.environ.get("MAIL_USERNAME")
+    MAIL_PASSWORD = os.environ.get("MAIL_PASSWORD")
+    SECURITY_EMAIL_SENDER = os.environ.get("SECURITY_EMAIL_SENDER", "info@domain.com")
+    SECURITY_SEND_PASSWORD_CHANGE_EMAIL = False
+
+    # Google OAuth Settings
+    GOOGLE_AUTH_ENABLED = (
+        os.environ.get("GOOGLE_AUTH_ENABLED", "False").lower() == "true"
+    )
+    GOOGLE_OAUTH_CLIENT_ID = os.environ.get("GOOGLE_OAUTH_CLIENT_ID")
+    GOOGLE_OAUTH_CLIENT_SECRET = os.environ.get("GOOGLE_OAUTH_CLIENT_SECRET")
+    GOOGLE_OAUTH_REDIRECT_URI = os.environ.get(
+        "GOOGLE_OAUTH_REDIRECT_URI"
+    )  # Let the OAuth handler construct it dynamically
+    OAUTHLIB_INSECURE_TRANSPORT = os.environ.get("OAUTHLIB_INSECURE_TRANSPORT", "0")
+
+    # GitHub OAuth Settings
+    GITHUB_AUTH_ENABLED = (
+        os.environ.get("GITHUB_AUTH_ENABLED", "False").lower() == "true"
+    )
+    GITHUB_OAUTH_CLIENT_ID = os.environ.get("GITHUB_OAUTH_CLIENT_ID")
+    GITHUB_OAUTH_CLIENT_SECRET = os.environ.get("GITHUB_OAUTH_CLIENT_SECRET")
+
+
+class TestingConfig(Config):
+    """Base for test configs. `.env` loads at import, so without these pins a
+    developer's Redis, mail, OAuth, or agent login settings reach every test."""
+
+    TESTING = True
+    SQLALCHEMY_DATABASE_URI = "sqlite+aiosqlite:///:memory:"
+    SESSION_TYPE = None
+    SESSION_URI = None
+    SECURITY_COOKIE_SECURE = False
+    SECURITY_PASSWORD_BREACH_CHECK = False
+    SECURITY_REGISTERABLE = False
+    QUART_RATE_LIMITER_ENABLED = False
+    DISABLE_MULTIPLE_SESSIONS = False
+    STK_ENABLE_AGENT_LOGIN = False
+    MAIL_SERVER = None
+    GOOGLE_AUTH_ENABLED = False
+    GITHUB_AUTH_ENABLED = False

stk/shell.py

@@ -0,0 +1,284 @@
+"""Async REPL for stk: live app, live DB session, top-level await."""
+
+from __future__ import annotations
+
+import ast
+import asyncio
+import atexit
+import code
+import inspect
+import sys
+import types
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from quart import g
+from rich.console import Console
+from sqlalchemy import delete, func, select, text, update
+from sqlalchemy.exc import PendingRollbackError, SQLAlchemyError
+
+import stk.extensions as ext
+from stk.migrations import import_model_modules
+
+console = Console()
+
+
+def history_file(app) -> Path:
+    """The REPL history, kept with the app's instance data."""
+    return Path(app.instance_path) / ".stk_shell_history"
+
+
+BANNER_HELPERS = [
+    ("find(Model, **kw)", "list rows matching equality filters"),
+    ("first(Model, **kw)", "first row matching equality filters"),
+    ("count(Model, **kw)", "row count"),
+    ("sql('select 1')", "run raw SQL, return rows"),
+    ("routes('user')", "print routes, optionally filtered"),
+    ("db", "live AsyncSession (also g.db_session)"),
+]
+
+
+def discover_models() -> dict[str, type]:
+    """Return every mapped model class keyed by class name."""
+    import_model_modules()
+    return {
+        mapper.class_.__name__: mapper.class_ for mapper in ext.Base.registry.mappers
+    }
+
+
+def build_namespace(app, db) -> dict:
+    """Build the shell namespace: app, session, models, query helpers."""
+    from stk.cli.reports import build_routes_report
+
+    async def execute(statement, params=None):
+        """Run a statement; never leave the session poisoned by an earlier failure."""
+        try:
+            return await db.execute(statement, params)
+        except PendingRollbackError:
+            # The failure was already reported where it happened; recover silently.
+            await db.rollback()
+            return await db.execute(statement, params)
+        except SQLAlchemyError:
+            await db.rollback()
+            raise
+
+    async def find(model, **filters):
+        return (await execute(select(model).filter_by(**filters))).scalars().all()
+
+    async def first(model, **filters):
+        stmt = select(model).filter_by(**filters).limit(1)
+        return (await execute(stmt)).scalars().first()
+
+    async def count(model, **filters):
+        stmt = select(func.count()).select_from(model).filter_by(**filters)
+        return (await execute(stmt)).scalar_one()
+
+    async def sql(statement, **params):
+        result = await execute(
+            text(statement) if isinstance(statement, str) else statement, params
+        )
+        return result.all() if result.returns_rows else result.rowcount
+
+    def routes(pattern=None):
+        for route in build_routes_report(app):
+            if (
+                pattern
+                and pattern not in route["rule"]
+                and pattern not in route["endpoint"]
+            ):
+                continue
+            methods = ",".join(route["methods"])
+            lock = "[yellow]auth[/]" if route["auth"]["required"] else "[dim]open[/]"
+            console.print(
+                f"[dim]{methods:14}[/]{route['rule']:44} {lock:16} [cyan]{route['endpoint']}[/]",
+                soft_wrap=True,
+            )
+
+    namespace = {
+        "app": app,
+        "db": db,
+        "ext": ext,
+        "select": select,
+        "func": func,
+        "text": text,
+        "delete": delete,
+        "update": update,
+        "datetime": datetime,
+        "timedelta": timedelta,
+        "find": find,
+        "first": first,
+        "count": count,
+        "sql": sql,
+        "execute": execute,
+        "routes": routes,
+    }
+    namespace.update(discover_models())
+    return namespace
+
+
+def print_banner(models) -> None:
+    console.print(f"\n[bold]stk shell[/] [dim]python {sys.version.split()[0]}[/]")
+    console.print(f"[dim]db:[/] {_masked_database_url()}")
+    console.print(f"[dim]models:[/] {', '.join(models)}")
+    for name, description in BANNER_HELPERS:
+        console.print(f"  [green]{name:22}[/] [dim]{description}[/]")
+    console.print(
+        "[dim]top-level await works. tab completes, F2 opens the menu, ctrl-d exits.[/]\n"
+    )
+
+
+def _masked_database_url() -> str:
+    from sqlalchemy.engine import make_url
+
+    from stk.settings import Config
+
+    return make_url(Config.SQLALCHEMY_DATABASE_URI).render_as_string(hide_password=True)
+
+
+def _setup_readline(namespace, history: Path) -> None:
+    """Tab completion and persistent history, best effort."""
+    try:
+        import readline
+        import rlcompleter
+    except ImportError:  # pragma: no cover - windows / no readline build
+        return
+
+    readline.set_completer(rlcompleter.Completer(namespace).complete)
+    readline.parse_and_bind(
+        "bind ^I rl_complete"
+        if "libedit" in getattr(readline, "__doc__", "")
+        else "tab: complete"
+    )
+    readline.set_history_length(2000)
+    try:
+        history.parent.mkdir(parents=True, exist_ok=True)
+        if history.exists():
+            readline.read_history_file(str(history))
+    except OSError:  # unreadable history is not worth failing the shell over
+        return
+    atexit.register(readline.write_history_file, str(history))
+
+
+def _configure_repl(repl) -> None:
+    """Syntax highlighting, fish-style suggestions, completion as you type."""
+    repl.use_code_colorscheme("monokai")
+    repl.complete_while_typing = True
+    repl.enable_fuzzy_completion = True
+    repl.enable_auto_suggest = True
+    repl.enable_history_search = True
+    repl.show_signature = True
+    repl.show_docstring = True
+    repl.highlight_matching_parenthesis = True
+    repl.confirm_exit = False
+
+
+async def _run_ptpython(app, db, namespace) -> None:
+    """Full-screen REPL. User code is awaited in this task, so `g` stays bound."""
+    from ptpython.repl import embed
+
+    history = history_file(app)
+    history.parent.mkdir(parents=True, exist_ok=True)
+    async with app.app_context():
+        g.db_session = db
+        await embed(
+            globals=namespace,
+            title="stk shell",
+            history_filename=str(history),
+            configure=_configure_repl,
+            patch_stdout=True,
+            return_asyncio_coroutine=True,
+        )
+
+
+def _ptpython_usable() -> bool:
+    if not sys.stdin.isatty():
+        return False
+    try:
+        import ptpython  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def build_awaiter(app, db, loop):
+    """Await a coroutine inside a fresh app context, like a request would."""
+
+    def await_(coro):
+        async def _wrapped():
+            async with app.app_context():
+                g.db_session = db
+                return await coro
+
+        return loop.run_until_complete(_wrapped())
+
+    return await_
+
+
+class AsyncConsole(code.InteractiveConsole):
+    """InteractiveConsole that awaits top-level coroutines on a shared loop."""
+
+    def __init__(self, namespace, await_):
+        super().__init__(namespace)
+        self.await_ = await_
+        self.compile.compiler.flags |= ast.PyCF_ALLOW_TOP_LEVEL_AWAIT
+
+    def runcode(self, code_obj):
+        try:
+            result = types.FunctionType(code_obj, self.locals)()
+            if inspect.iscoroutine(result):
+                self.await_(result)
+        except SystemExit:
+            raise
+        except BaseException:
+            self.showtraceback()
+
+
+def run_shell(app, source: str | None = None) -> None:
+    """Start the REPL, or execute `source` and print its result."""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    db = ext.async_session_factory()
+    namespace = build_namespace(app, db)
+
+    try:
+        if source is not None:
+            _run_source(build_awaiter(app, db, loop), namespace, source)
+            return
+
+        print_banner(sorted(discover_models()))
+        if _ptpython_usable():
+            loop.run_until_complete(_run_ptpython(app, db, namespace))
+            return
+        _setup_readline(namespace, history_file(app))
+        AsyncConsole(namespace, build_awaiter(app, db, loop)).interact(
+            banner="", exitmsg=""
+        )
+    finally:
+        loop.run_until_complete(db.close())
+        if ext.engine:
+            loop.run_until_complete(ext.engine.dispose())
+        loop.close()
+
+
+def _run_source(await_, namespace, source: str) -> None:
+    """Execute one-shot source with top-level await; print the last expression."""
+    block = ast.parse(source, mode="exec")
+    last = (
+        block.body.pop()
+        if block.body and isinstance(block.body[-1], ast.Expr)
+        else None
+    )
+
+    def run(node, mode):
+        code_obj = compile(
+            node, "<stk shell>", mode, flags=ast.PyCF_ALLOW_TOP_LEVEL_AWAIT
+        )
+        result = types.FunctionType(code_obj, namespace)()
+        return await_(result) if inspect.iscoroutine(result) else result
+
+    if block.body:
+        run(block, "exec")
+    if last is not None:
+        result = run(ast.Expression(last.value), "eval")
+        if result is not None:
+            print(result)

stk/static/VERSIONS.txt

@@ -0,0 +1,4 @@
+vue 3.5.40
+vuetify 4.1.6
+axios 1.18.1
+@tabler/icons-webfont 3.45.0