stkit 17.0.0__py3-none-any.whl

stk/cli/smoke.py

@@ -0,0 +1,399 @@
+"""Real-browser smoke check: boot a throwaway app, drive it with Playwright."""
+
+import asyncio
+import os
+import secrets
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import click
+import httpx
+
+from stk.agent_login import create_agent_login_token
+from stk.cli.base import cli_app, run_async
+
+SMOKE_EMAIL = "smoke@example.com"
+SMOKE_PASSWORD = "SmokePassword123!"
+SMOKE_SCREENSHOT = Path(".stk/smoke/dashboard.png")
+
+# Text the same colour as what it sits on renders invisible without raising a
+# console error, so the browser has to measure it. 3:1 is the WCAG floor for
+# large/bold text; below ~1.5 the element is effectively gone.
+MIN_CONTRAST_RATIO = 3.0
+_CONTRAST_TEMPLATE = """() => {
+  const parse = (value) => {
+    const parts = value.match(/[\\d.]+/g);
+    if (!parts) return null;
+    const nums = parts.map(Number);
+    const scale = value.startsWith('color(') ? 255 : 1;
+    return {r: nums[0] * scale, g: nums[1] * scale, b: nums[2] * scale,
+            a: nums.length > 3 ? nums[3] : 1};
+  };
+  const luminance = ({r, g, b}) => {
+    const channel = (v) => {
+      v /= 255;
+      return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+  };
+  const flatten = (fg, bg) => ({
+    r: fg.r * fg.a + bg.r * (1 - fg.a),
+    g: fg.g * fg.a + bg.g * (1 - fg.a),
+    b: fg.b * fg.a + bg.b * (1 - fg.a),
+    a: 1,
+  });
+  const backdrop = (element) => {
+    for (let node = element; node; node = node.parentElement) {
+      const background = parse(getComputedStyle(node).backgroundColor);
+      if (background && background.a > 0.5) return background;
+    }
+    return {r: 255, g: 255, b: 255, a: 1};
+  };
+  const findings = [];
+  for (const element of document.querySelectorAll('.v-btn, .v-chip, .v-alert')) {
+    if (!element.offsetParent || !element.innerText.trim()) continue;
+    const foreground = parse(getComputedStyle(element).color);
+    if (!foreground) continue;
+    const background = backdrop(element);
+    const text = flatten(foreground, background);
+    const [a, b] = [luminance(text), luminance(background)];
+    const ratio = (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+    if (ratio < __MIN_RATIO__) {
+      findings.push({label: element.innerText.trim().slice(0, 32),
+                     ratio: Math.round(ratio * 100) / 100});
+    }
+  }
+  return findings;
+}"""
+CONTRAST_JS = _CONTRAST_TEMPLATE.replace("__MIN_RATIO__", str(MIN_CONTRAST_RATIO))
+
+
+FIXED_SMOKE_PATHS = ("/", "/login", "/dashboard/", "/users/")
+# Prefixes that are not pages, or whose GET starts an auth flow or redirect
+# (OAuth logins, agent login).
+_SKIP_PREFIXES = ("/api/", "/static", "/_test", "/login", "/logout")
+
+
+def machine_paths(app):
+    """Paths a browser never opens as a page: WebSockets and @csrf_exempt webhooks."""
+    return {
+        rule.rule
+        for rule in app.url_map.iter_rules()
+        if rule.websocket
+        or getattr(app.view_functions.get(rule.endpoint), "_stk_csrf_exempt", False)
+    }
+
+
+def discover_smoke_paths(routes, skip=frozenset()):
+    """Pick parameterless GET pages from build_routes_report that smoke should visit."""
+    return sorted(
+        route["rule"]
+        for route in routes
+        if "GET" in route["methods"]
+        and not route["arguments"]
+        and "<" not in route["rule"]
+        and route["blueprint"] != "security"
+        and not route["rule"].startswith(_SKIP_PREFIXES)
+        and route["rule"] not in FIXED_SMOKE_PATHS
+        and route["rule"] not in skip
+    )
+
+
+def build_smoke_report(pages, dashboard_screenshot):
+    """Return a browser smoke report with per-page failure reasons."""
+    page_reports = []
+    for page in pages:
+        problems = []
+        status_code = page.get("status")
+        if status_code is None:
+            problems.append("no document response")
+        elif status_code >= 400:
+            problems.append(f"HTTP {status_code}")
+
+        for entry in page.get("console", []):
+            if entry["type"] == "error":
+                problems.append(f"console error: {entry['text']}")
+            elif entry["type"] == "pageerror":
+                problems.append(f"uncaught error: {entry['text']}")
+
+        for request in page.get("failed_requests", []):
+            failure = request.get("failure") or "unknown"
+            problems.append(f"request failed: {request['url']} {failure}")
+
+        for finding in page.get("low_contrast", []):
+            problems.append(
+                f'invisible text: "{finding["label"]}" contrast {finding["ratio"]}:1'
+            )
+
+        page_reports.append(
+            {
+                "name": page["name"],
+                "path": page["path"],
+                "status_code": status_code,
+                "status": "failed" if problems else "passed",
+                "console": page.get("console", []),
+                "failed_requests": page.get("failed_requests", []),
+                "low_contrast": page.get("low_contrast", []),
+                "problems": problems,
+            }
+        )
+
+    status = (
+        "passed"
+        if all(page["status"] == "passed" for page in page_reports)
+        else "failed"
+    )
+    return {
+        "status": status,
+        "dashboard_screenshot": str(dashboard_screenshot),
+        "pages": page_reports,
+    }
+
+
+def smoke_exit_code(report):
+    return 0 if report["status"] == "passed" else 1
+
+
+def _free_localhost_port():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+def _smoke_env(database_uri):
+    env = os.environ.copy()
+    env.update(
+        {
+            "SECRET_KEY": secrets.token_urlsafe(32),
+            "SECURITY_PASSWORD_SALT": secrets.token_urlsafe(32),
+            "SQLALCHEMY_DATABASE_URI": database_uri,
+            "STK_ENV": "development",
+            "STK_ENABLE_AGENT_LOGIN": "true",
+            "SESSION_COOKIE_SECURE": "False",
+        }
+    )
+    env.pop("REDIS_URL", None)
+    env.pop("REDIS_SESSION", None)
+    return env
+
+
+def _run_smoke_setup(env):
+    commands = [
+        [sys.executable, "-m", "stk", "db", "upgrade"],
+        [
+            sys.executable,
+            "-m",
+            "stk",
+            "install",
+            "--email",
+            SMOKE_EMAIL,
+            "--password",
+            SMOKE_PASSWORD,
+        ],
+    ]
+    for command_args in commands:
+        result = subprocess.run(
+            command_args,
+            capture_output=True,
+            text=True,
+            check=False,
+            env=env,
+        )
+        if result.returncode != 0:
+            raise click.ClickException(
+                "smoke setup failed for "
+                f"{' '.join(command_args)}\n{result.stderr.strip()}"
+            )
+
+
+def _prepare_smoke(app, secret_key):
+    """Return an agent login token and the extra page paths to visit."""
+    from stk.cli.reports import build_routes_report
+
+    async def _create_token():
+        async with app.app_context():
+            # Signed with the key the smoke server runs with, not the app's own.
+            app.config["SECRET_KEY"] = secret_key
+            token = create_agent_login_token(SMOKE_EMAIL, "/dashboard/")
+        skip = machine_paths(app) | set(app.config.get("STK_SMOKE_SKIP", ()))
+        paths = discover_smoke_paths(build_routes_report(app), skip)
+        return token, paths
+
+    return run_async(_create_token())
+
+
+def _start_smoke_server(port, env):
+    return subprocess.Popen(
+        [
+            sys.executable,
+            "-m",
+            "stk",
+            "run",
+            "--host",
+            "127.0.0.1",
+            "--port",
+            str(port),
+            "--no-reload",
+        ],
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+
+def _wait_for_smoke_server(base_url, process):
+    deadline = time.monotonic() + 20
+    while time.monotonic() < deadline:
+        if process.poll() is not None:
+            stdout, stderr = process.communicate(timeout=1)
+            raise click.ClickException(
+                "smoke server exited before accepting requests\n"
+                f"{stdout.strip()}\n{stderr.strip()}"
+            )
+        try:
+            response = httpx.get(f"{base_url}/login", timeout=1)
+            if response.status_code < 500:
+                return
+        except httpx.HTTPError:
+            pass
+        time.sleep(0.2)
+    raise click.ClickException("smoke server did not start within 20 seconds")
+
+
+def _stop_smoke_server(process):
+    if process.poll() is not None:
+        return
+    process.terminate()
+    try:
+        process.communicate(timeout=5)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.communicate(timeout=5)
+
+
+async def _visit_smoke_page(context, base_url, name, path, screenshot_path=None):
+    page = await context.new_page()
+    console_entries = []
+    failed_requests = []
+
+    def _record_console(message):
+        if message.type in {"error", "warning"}:
+            console_entries.append({"type": message.type, "text": message.text})
+
+    def _record_failed_request(request):
+        failure = request.failure
+        if callable(failure):
+            failure = failure()
+        failed_requests.append({"url": request.url, "failure": failure or ""})
+
+    def _record_page_error(error):
+        console_entries.append({"type": "pageerror", "text": str(error)})
+
+    page.on("console", _record_console)
+    page.on("pageerror", _record_page_error)
+    page.on("requestfailed", _record_failed_request)
+    response = await page.goto(f"{base_url}{path}", wait_until="networkidle")
+    low_contrast = await page.evaluate(CONTRAST_JS)
+    if screenshot_path is not None:
+        screenshot_path.parent.mkdir(parents=True, exist_ok=True)
+        await page.screenshot(path=str(screenshot_path), full_page=True)
+    await page.close()
+    return {
+        "name": name,
+        "path": path,
+        "status": response.status if response else None,
+        "console": console_entries,
+        "failed_requests": failed_requests,
+        "low_contrast": low_contrast,
+    }
+
+
+async def _run_playwright_smoke(base_url, token, extra_paths):
+    try:
+        from playwright.async_api import Error as PlaywrightError
+        from playwright.async_api import async_playwright
+    except ImportError as exc:
+        raise click.ClickException(
+            "Playwright is not installed. Run `uv sync --extra dev`."
+        ) from exc
+
+    try:
+        async with async_playwright() as playwright:
+            browser = await playwright.chromium.launch()
+            context = await browser.new_context()
+            pages = [
+                await _visit_smoke_page(context, base_url, "home", "/"),
+                await _visit_smoke_page(context, base_url, "login", "/login"),
+                await _visit_smoke_page(
+                    context,
+                    base_url,
+                    "agent-login",
+                    f"/_test/login?token={token}",
+                ),
+                await _visit_smoke_page(
+                    context,
+                    base_url,
+                    "dashboard",
+                    "/dashboard/",
+                    SMOKE_SCREENSHOT,
+                ),
+                await _visit_smoke_page(context, base_url, "admin-users", "/users/"),
+            ]
+            for path in extra_paths:
+                pages.append(await _visit_smoke_page(context, base_url, path, path))
+            await context.close()
+            await browser.close()
+    except PlaywrightError as exc:
+        message = str(exc)
+        if "Executable doesn't exist" in message or "playwright install" in message:
+            raise click.ClickException(
+                "Chromium is not installed. Run `uv run playwright install chromium`."
+            ) from exc
+        raise
+
+    for page in pages:
+        if page["name"] == "agent-login":
+            page["path"] = "/_test/login?token=<redacted>"
+    return build_smoke_report(pages, SMOKE_SCREENSHOT)
+
+
+def run_smoke():
+    """Boot a throwaway app on a free port and drive it with a real browser."""
+    from stk.migrations import throwaway_database_url
+
+    app = cli_app()
+    with throwaway_database_url(app.config["SQLALCHEMY_DATABASE_URI"]) as database_uri:
+        env = _smoke_env(database_uri)
+        _run_smoke_setup(env)
+
+        token, extra_paths = _prepare_smoke(app, env["SECRET_KEY"])
+        port = _free_localhost_port()
+        base_url = f"http://127.0.0.1:{port}"
+        server = _start_smoke_server(port, env)
+        try:
+            _wait_for_smoke_server(base_url, server)
+            return asyncio.run(_run_playwright_smoke(base_url, token, extra_paths))
+        finally:
+            _stop_smoke_server(server)
+
+
+def print_smoke_report(report):
+    click.echo(f"Smoke status: {report['status']}")
+    click.echo(f"Dashboard screenshot: {report['dashboard_screenshot']}")
+    for page in report["pages"]:
+        click.echo(f"{page['status'].upper()} {page['name']} {page['path']}")
+        click.echo(f"  HTTP: {page['status_code']}")
+        for entry in page["console"]:
+            click.echo(f"  console {entry['type']}: {entry['text']}")
+        for finding in page.get("low_contrast", []):
+            click.echo(f"  invisible text: {finding['label']!r} {finding['ratio']}:1")
+        for request in page["failed_requests"]:
+            click.echo(
+                f"  request failed: {request['url']} {request.get('failure') or ''}"
+            )
+        for problem in page["problems"]:
+            click.echo(f"  problem: {problem}")

stk/cli/users.py

@@ -0,0 +1,259 @@
+"""User, role, and session commands."""
+
+import secrets
+import string
+from datetime import datetime
+from uuid import uuid4
+
+import click
+from email_validator import EmailNotValidError, validate_email
+from quart_security import hash_password
+from sqlalchemy import select
+
+import stk.extensions as ext
+from stk.agent_login import create_agent_login_token
+from stk.cli.base import cli_app, console, run_async
+from stk.user.models import User
+
+
+def _check_email(email):
+    """Reject addresses the login form would refuse, such as reserved domains."""
+    try:
+        validate_email(email, check_deliverability=False)
+    except EmailNotValidError as exc:
+        raise click.BadParameter(str(exc), param_hint="email") from exc
+
+
+@click.group("browser-token")
+def browser_token():
+    """Create test-only browser login URLs."""
+
+
+@browser_token.command("create")
+@click.option("--user", "email", required=True, help="Test user email.")
+@click.option("--ttl", default=60, type=int, help="Token TTL in seconds.")
+@click.option("--next", "next_path", default="/dashboard/", help="Local redirect path.")
+def browser_token_create(email, ttl, next_path):
+    """Create a signed test-only browser login URL."""
+    app = cli_app()
+    if ttl > app.config["STK_AGENT_LOGIN_MAX_TTL_SECONDS"]:
+        raise click.ClickException("ttl exceeds STK_AGENT_LOGIN_MAX_TTL_SECONDS")
+    if not app.config["STK_ENABLE_AGENT_LOGIN"]:
+        raise click.ClickException("agent login is disabled")
+
+    async def _create_token():
+        async with app.app_context():
+            return create_agent_login_token(email, next_path)
+
+    token = run_async(_create_token())
+    click.echo(f"/_test/login?token={token}")
+
+
+@click.command()
+@click.option("-e", "--email", default=None, help="Admin email")
+@click.option("-p", "--password", default=None, help="Admin password")
+def install(email, password):
+    """Install a default admin user and add an admin role to it."""
+    app = cli_app()
+
+    async def _run():
+        from stk.user.models import Role
+
+        async with ext.async_session_factory() as session:
+            admin_role = (
+                await session.execute(select(Role).where(Role.name == "admin"))
+            ).scalar_one_or_none()
+            if not admin_role:
+                admin_role = Role(name="admin")
+                session.add(admin_role)
+                await session.commit()
+
+            admin_user = (
+                await session.execute(
+                    select(User).where(User.roles.any(Role.name == "admin"))
+                )
+            ).scalar_one_or_none()
+            if admin_user:
+                console.print(
+                    f"[yellow]An admin user already exists:[/] [blue]{admin_user.email}[/]"
+                )
+                return
+
+            nonlocal email, password
+            if not email:
+                email = click.prompt("Admin email", default="admin@example.com")
+            _check_email(email)
+
+            generated = False
+            if not password:
+                password = "".join(
+                    secrets.choice(string.ascii_letters + string.digits + "@#$%^&*")
+                    for _ in range(32)
+                )
+                generated = True
+
+            user = User(
+                email=email,
+                name="Super Admin",
+                password=hash_password(password, app=app),
+                active=True,
+                confirmed_at=datetime.now(),
+            )
+            user.roles.append(admin_role)
+            session.add(user)
+            await session.commit()
+
+            console.print("\n[green]✓[/] Admin user created successfully!")
+            console.print(f"[blue]Email:[/] {email}")
+            if generated:
+                console.print(f"[blue]Password:[/] [red]{password}[/]")
+                console.print(
+                    "\n[yellow]⚠️  Please save this password securely - you will not see it again![/]"
+                )
+
+    run_async(_run())
+
+
+@click.command()
+@click.option("-e", "--email", prompt=True, default=None)
+@click.option("-p", "--password", prompt=True, default=None)
+def create(email, password):
+    """Creates a user using an email."""
+    _check_email(email)
+    app = cli_app()
+
+    async def _run():
+        async with ext.async_session_factory() as session:
+            existing = (
+                await session.execute(select(User).where(User.email == email))
+            ).scalar_one_or_none()
+            if existing is not None:
+                console.print("[yellow]User already exists![/]")
+            else:
+                user = User(
+                    email=email,
+                    password=hash_password(password, app=app),
+                    active=True,
+                    confirmed_at=datetime.now(),
+                )
+                session.add(user)
+                await session.commit()
+
+    run_async(_run())
+
+
+@click.command()
+@click.option("-e", "--email", prompt=True, default=None)
+@click.option("-r", "--role", prompt=True, default="admin")
+def add_role(email, role):
+    """Adds a role to the specified user."""
+
+    async def _run():
+        from stk.user.models import Role
+
+        async with ext.async_session_factory() as session:
+            u = (
+                await session.execute(select(User).where(User.email == email))
+            ).scalar_one_or_none()
+
+            if u is None:
+                console.print("[red]Sorry, this user does not exist![/]")
+            else:
+                r = (
+                    await session.execute(select(Role).where(Role.name == role))
+                ).scalar_one_or_none()
+                if r is None:
+                    console.print("[yellow]Sorry, this role does not exist![/]")
+                    answer = click.prompt(
+                        "Would you like to create one? Y/N", default="N"
+                    )
+                    if answer.lower() == "y":
+                        r = Role(name=role)
+                        try:
+                            session.add(r)
+                            await session.commit()
+                            console.print(
+                                "[green]Role created successfully, you may add it now to the user[/]"
+                            )
+                        except Exception:
+                            await session.rollback()
+                if r:
+                    u.roles.append(r)
+                    await session.commit()
+
+    run_async(_run())
+
+
+@click.command()
+@click.option("-e", "--email", prompt="Email", default=None)
+@click.option("-p", "--password", hide_input=True, prompt=True, default=None)
+def reset(email, password):
+    """Reset a user password using email"""
+    app = cli_app()
+    try:
+        pwd = hash_password(password, app=app)
+
+        async def _run():
+            async with ext.async_session_factory() as session:
+                u = (
+                    await session.execute(select(User).where(User.email == email))
+                ).scalar_one_or_none()
+                if not u:
+                    console.print(f'[red]User with email "{email}" not found.[/]')
+                    return
+
+                u.password = pwd
+                u.password_set = True
+                u.fs_uniquifier = uuid4().hex
+                try:
+                    await session.commit()
+                    console.print(
+                        "[green]User password has been reset successfully.[/]"
+                    )
+                except Exception:
+                    await session.rollback()
+                    console.print("[red]Error committing to database.[/]")
+
+        run_async(_run())
+    except Exception as e:
+        console.print(f"[red]Error resetting user password: {e}[/]")
+
+
+@click.command("cleanup-sessions")
+def cleanup_sessions():
+    """Deactivate expired sessions and delete old rows."""
+    from stk.tasks import cleanup_expired_sessions
+
+    run_async(cleanup_expired_sessions())
+    console.print("[green]Session cleanup complete[/]")
+
+
+@click.command("protect-mfa")
+def protect_mfa():
+    """Encrypt legacy MFA seeds or rotate them to the current key."""
+    from quart_security.totp import encrypt_totp_secret
+    from sqlalchemy import update
+
+    app = cli_app()
+
+    async def _run():
+        count = 0
+        async with ext.async_session_factory() as database:
+            rows = await database.stream(
+                select(User.id, User.tf_totp_secret)
+                .where(User.tf_totp_secret.is_not(None))
+                .execution_options(yield_per=100)
+            )
+            async for user_id, secret in rows:
+                encrypted = encrypt_totp_secret(secret, app=app)
+                await database.execute(
+                    update(User)
+                    .where(User.id == user_id)
+                    .values(tf_totp_secret=encrypted)
+                )
+                count += 1
+            await database.commit()
+        return count
+
+    count = run_async(_run())
+    console.print(f"[green]Protected {count} MFA seeds[/]")