stkit 17.0.0__py3-none-any.whl

stk/cli/watch.py

@@ -0,0 +1,68 @@
+"""File watching for `stk verify --watch`, with no watcher dependency.
+
+A polling scan over the project's own source files. The tree is small (a few
+hundred files), so a stat() sweep twice a second costs less than importing a
+watcher library would.
+"""
+
+from pathlib import Path
+
+IGNORED_DIRS = {
+    ".git",
+    ".venv",
+    ".ruff_cache",
+    ".pytest_cache",
+    "__pycache__",
+    "node_modules",
+    "instance",
+    ".stk",
+}
+# Checks worth re-running when a file of this kind changes. Also defines what
+# counts as a source file, so the two can never disagree.
+CHECKS_BY_SUFFIX = {
+    ".py": ("ruff", "checks", "migration-drift"),
+    ".html": ("checks",),
+    ".jinja2": ("checks",),
+    ".js": ("checks",),
+    ".css": ("checks",),
+}
+# Vendored assets are refreshed by vendor.sh, not edited, and they are large.
+IGNORED_PARTS = {"static/js/vue.min.js", "static/js/vuetify.min.js"}
+
+
+def scan(root: Path) -> dict[Path, float]:
+    """Return {path: mtime} for every source file worth reacting to."""
+    seen = {}
+    for path in root.rglob("*"):
+        if path.suffix not in CHECKS_BY_SUFFIX:
+            continue
+        if IGNORED_DIRS & set(path.parts):
+            continue
+        if any(part in path.as_posix() for part in IGNORED_PARTS):
+            continue
+        try:
+            seen[path] = path.stat().st_mtime
+        except OSError:  # deleted between rglob and stat
+            continue
+    return seen
+
+
+def changed(previous: dict[Path, float], current: dict[Path, float]) -> list[Path]:
+    """Return the paths that were added, removed, or touched."""
+    touched = [
+        path
+        for path, mtime in current.items()
+        if previous.get(path) != mtime  # new file or new mtime
+    ]
+    touched += [path for path in previous if path not in current]
+    return sorted(set(touched))
+
+
+def checks_for(paths) -> list[str]:
+    """Return the check names worth re-running for this batch of changes."""
+    names = []
+    for path in paths:
+        for name in CHECKS_BY_SUFFIX.get(path.suffix, ()):
+            if name not in names:
+                names.append(name)
+    return names

stk/extensions.py

@@ -0,0 +1,29 @@
+"""Extensions module. Each extension is initialized in the app factory located
+in app.py
+"""
+
+from quart_session import Session
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+# SQLite batch migrations can only add or drop named constraints; without a
+# convention autogenerate emits None and the upgrade fails half-applied.
+NAMING_CONVENTION = {
+    "ix": "ix_%(column_0_label)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData(naming_convention=NAMING_CONVENTION)
+    # A server-side default or onupdate expires its column on flush; reading it
+    # later lazy-loads, which async sessions refuse with MissingGreenlet.
+    __mapper_args__ = {"eager_defaults": True}
+
+
+engine = None
+async_session_factory = None
+session = Session()

stk/migrations/__init__.py

@@ -0,0 +1,130 @@
+"""Alembic integration: stk's lineage ships here, each app keeps its own.
+
+Both lineages share one version table. stk's revisions carry the `stk` branch
+label; an app's carry its package name and live in `<package>/migrations/`.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import pkgutil
+import tempfile
+import uuid
+from contextlib import contextmanager
+from pathlib import Path
+
+from alembic.config import Config as AlembicConfig
+from sqlalchemy.engine import make_url
+
+import stk
+from stk.extensions import Base
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+CORE_VERSIONS = SCRIPT_DIR / "versions"
+CORE_LABEL = "stk"
+
+SYNC_DRIVER_MAP = {
+    "postgresql+asyncpg": "postgresql+psycopg2",
+    "sqlite+aiosqlite": "sqlite",
+}
+
+# Tables an extension owns (PostGIS keeps its reference systems here); no model
+# describes them, so autogenerate and the drift check must not offer to drop them.
+EXTENSION_TABLES = {"spatial_ref_sys"}
+
+
+def import_model_modules() -> None:
+    """Import every `stk.<feature>.models`; apps import theirs when built."""
+    for module in pkgutil.iter_modules(stk.__path__, prefix="stk."):
+        model_module = f"{module.name}.models"
+        try:
+            importlib.import_module(model_module)
+        except ModuleNotFoundError as exc:
+            if exc.name != model_module:
+                raise
+
+
+def get_target_metadata():
+    """Return metadata after loading all model modules."""
+    import_model_modules()
+    return Base.metadata
+
+
+def include_object(obj, name, type_, reflected, compare_to):
+    return not (type_ == "table" and name in EXTENSION_TABLES)
+
+
+def sync_url(database_url: str) -> str:
+    """Convert an async driver URL to the sync driver Alembic uses."""
+    url = make_url(database_url)
+    drivername = SYNC_DRIVER_MAP.get(url.drivername)
+    if drivername is not None:
+        url = url.set(drivername=drivername)
+    # str(URL) masks the password as *** on SQLAlchemy >= 2.0.50
+    return url.render_as_string(hide_password=False)
+
+
+def app_label(app) -> str:
+    """The branch label of an app's lineage: its top-level package name."""
+    return app.import_name.split(".")[0]
+
+
+def app_versions(app) -> Path:
+    return Path(app.root_path) / "migrations"
+
+
+def build_alembic_config(app=None, url=None, *, quiet=False) -> AlembicConfig:
+    """Build an Alembic config for stk's lineage plus the app's, if given."""
+    config = AlembicConfig()
+    config.set_main_option("script_location", str(SCRIPT_DIR))
+    config.set_main_option("path_separator", "os")
+    locations = [CORE_VERSIONS] + ([app_versions(app)] if app is not None else [])
+    config.set_main_option("version_locations", os.pathsep.join(map(str, locations)))
+    if url is None:
+        url = sync_url(app.config["SQLALCHEMY_DATABASE_URI"])
+    # The ini parser behind main options treats % as interpolation.
+    config.set_main_option("sqlalchemy.url", url.replace("%", "%%"))
+    config.attributes["quiet"] = quiet
+    return config
+
+
+def portable_tables() -> list:
+    """Every model table except those marked `info={"postgis": True}`, for SQLite."""
+    return [t for t in get_target_metadata().sorted_tables if not t.info.get("postgis")]
+
+
+def _render(url, *, sync: bool) -> str:
+    rendered = url.render_as_string(hide_password=False)
+    return sync_url(rendered) if sync else rendered
+
+
+@contextmanager
+def throwaway_database_url(database_url: str, *, sync: bool = False):
+    """Yield the URL of an empty database of the same dialect, then drop it.
+
+    Postgres apps need Postgres here: their models and migrations use types
+    SQLite cannot render. Postgres needs a role with CREATEDB.
+    """
+    from sqlalchemy import create_engine, text
+
+    url = make_url(database_url)
+    if url.get_backend_name() != "postgresql":
+        with tempfile.TemporaryDirectory(prefix="stk-db-") as temp_dir:
+            yield _render(url.set(database=f"{temp_dir}/throwaway.db"), sync=sync)
+        return
+
+    name = f"stk_tmp_{uuid.uuid4().hex[:12]}"
+    admin = create_engine(
+        _render(url.set(database="postgres"), sync=True), isolation_level="AUTOCOMMIT"
+    )
+    try:
+        with admin.connect() as connection:
+            connection.execute(text(f'create database "{name}"'))
+        try:
+            yield _render(url.set(database=name), sync=sync)
+        finally:
+            with admin.connect() as connection:
+                connection.execute(text(f'drop database "{name}" with (force)'))
+    finally:
+        admin.dispose()

stk/migrations/env.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import logging
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from stk.migrations import get_target_metadata, include_object
+
+config = context.config
+
+if not config.attributes.get("quiet"):
+    logging.basicConfig(format="%(levelname)-5.5s [%(name)s] %(message)s")
+    logging.getLogger("alembic").setLevel(logging.INFO)
+
+target_metadata = get_target_metadata()
+url = config.get_main_option("sqlalchemy.url")
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        compare_type=True,
+        compare_server_default=True,
+        include_object=include_object,
+        render_as_batch=url.startswith("sqlite"),
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        {"sqlalchemy.url": url}, prefix="sqlalchemy.", poolclass=pool.NullPool
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+            compare_server_default=True,
+            include_object=include_object,
+            # SQLite alters tables by copying them; batch mode does that for us.
+            render_as_batch=connection.dialect.name == "sqlite",
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

stk/migrations/script.py.mako

@@ -0,0 +1,17 @@
+"""${message}"""
+
+import sqlalchemy as sa
+from alembic import op
+${imports if imports else ""}
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

stk/migrations/versions/stk_0001_initial_schema.py

@@ -0,0 +1,213 @@
+"""stk initial schema: users, roles, sessions, passkeys, OAuth, security state."""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "stk_0001"
+down_revision = None
+branch_labels = ("stk",)
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "quart_security_state",
+        sa.Column("token", sa.String(length=160), nullable=False),
+        sa.Column("payload", sa.JSON(), nullable=False),
+        sa.Column("expires_at", sa.BigInteger(), nullable=False),
+        sa.PrimaryKeyConstraint("token", name=op.f("pk_quart_security_state")),
+    )
+    with op.batch_alter_table("quart_security_state", schema=None) as batch_op:
+        batch_op.create_index(
+            batch_op.f("ix_quart_security_state_expires_at"),
+            ["expires_at"],
+            unique=False,
+        )
+
+    op.create_table(
+        "rate_limit_window",
+        sa.Column("key", sa.String(length=160), nullable=False),
+        sa.Column("count", sa.Integer(), nullable=False),
+        sa.Column("expires_at", sa.Integer(), nullable=False),
+        sa.PrimaryKeyConstraint("key", name=op.f("pk_rate_limit_window")),
+    )
+    with op.batch_alter_table("rate_limit_window", schema=None) as batch_op:
+        batch_op.create_index(
+            batch_op.f("ix_rate_limit_window_expires_at"), ["expires_at"], unique=False
+        )
+
+    op.create_table(
+        "role",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(length=80), nullable=True),
+        sa.Column("description", sa.String(length=255), nullable=True),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_role")),
+        sa.UniqueConstraint("name", name=op.f("uq_role_name")),
+    )
+    op.create_table(
+        "user",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("username", sa.String(length=255), nullable=True),
+        sa.Column("fs_uniquifier", sa.String(length=255), nullable=False),
+        sa.Column("name", sa.String(length=255), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("email", sa.String(length=255), nullable=False),
+        sa.Column("password", sa.String(length=255), nullable=False),
+        sa.Column("password_set", sa.Boolean(), nullable=False),
+        sa.Column("active", sa.Boolean(), nullable=True),
+        sa.Column("failed_login_count", sa.Integer(), nullable=False),
+        sa.Column("locked_until", sa.DateTime(), nullable=True),
+        sa.Column("confirmed_at", sa.DateTime(), nullable=True),
+        sa.Column("last_login_at", sa.DateTime(), nullable=True),
+        sa.Column("current_login_at", sa.DateTime(), nullable=True),
+        sa.Column("last_login_ip", sa.String(length=255), nullable=True),
+        sa.Column("current_login_ip", sa.String(length=255), nullable=True),
+        sa.Column("login_count", sa.Integer(), nullable=True),
+        sa.Column("fs_webauthn_user_handle", sa.String(length=64), nullable=True),
+        sa.Column("tf_phone_number", sa.String(length=64), nullable=True),
+        sa.Column("tf_primary_method", sa.String(length=140), nullable=True),
+        sa.Column("tf_totp_secret", sa.String(length=255), nullable=True),
+        sa.Column("mf_recovery_codes", sa.JSON(), nullable=True),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_user")),
+        sa.UniqueConstraint("email", name=op.f("uq_user_email")),
+        sa.UniqueConstraint("fs_uniquifier", name=op.f("uq_user_fs_uniquifier")),
+        sa.UniqueConstraint(
+            "fs_webauthn_user_handle", name=op.f("uq_user_fs_webauthn_user_handle")
+        ),
+        sa.UniqueConstraint("username", name=op.f("uq_user_username")),
+    )
+    op.create_table(
+        "activity",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("action", sa.String(length=255), nullable=False),
+        sa.Column("data", sa.JSON(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["user_id"], ["user.id"], name=op.f("fk_activity_user_id")
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_activity")),
+    )
+    with op.batch_alter_table("activity", schema=None) as batch_op:
+        batch_op.create_index(
+            batch_op.f("ix_activity_created_at"), ["created_at"], unique=False
+        )
+        batch_op.create_index(
+            batch_op.f("ix_activity_user_id"), ["user_id"], unique=False
+        )
+
+    op.create_table(
+        "oauth",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("provider", sa.String(length=50), nullable=False),
+        sa.Column("provider_user_id", sa.String(length=256), nullable=False),
+        sa.Column("token", sa.JSON(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["user_id"], ["user.id"], name=op.f("fk_oauth_user_id")
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_oauth")),
+        sa.UniqueConstraint(
+            "provider", "provider_user_id", name="uq_oauth_provider_user"
+        ),
+    )
+    op.create_table(
+        "roles_users",
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("role_id", sa.Integer(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["role_id"], ["role.id"], name=op.f("fk_roles_users_role_id")
+        ),
+        sa.ForeignKeyConstraint(
+            ["user_id"], ["user.id"], name=op.f("fk_roles_users_user_id")
+        ),
+        sa.PrimaryKeyConstraint("user_id", "role_id", name=op.f("pk_roles_users")),
+    )
+    op.create_table(
+        "user_sessions",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("session_token", sa.String(length=255), nullable=False),
+        sa.Column("last_active", sa.DateTime(), nullable=True),
+        sa.Column("expires_at", sa.DateTime(), nullable=True),
+        sa.Column("ip_address", sa.String(length=255), nullable=True),
+        sa.Column("meta", sa.JSON(), nullable=True),
+        sa.Column("is_active", sa.Boolean(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["user_id"], ["user.id"], name=op.f("fk_user_sessions_user_id")
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_user_sessions")),
+        sa.UniqueConstraint(
+            "session_token", name=op.f("uq_user_sessions_session_token")
+        ),
+    )
+    with op.batch_alter_table("user_sessions", schema=None) as batch_op:
+        batch_op.create_index(
+            batch_op.f("ix_user_sessions_is_active"), ["is_active"], unique=False
+        )
+        batch_op.create_index(
+            batch_op.f("ix_user_sessions_user_id"), ["user_id"], unique=False
+        )
+
+    op.create_table(
+        "web_authn",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("credential_id", sa.LargeBinary(length=1024), nullable=False),
+        sa.Column("public_key", sa.LargeBinary(length=1024), nullable=False),
+        sa.Column("sign_count", sa.Integer(), nullable=False),
+        sa.Column("transports", sa.JSON(), nullable=True),
+        sa.Column("extensions", sa.String(length=255), nullable=True),
+        sa.Column("lastuse_datetime", sa.DateTime(), nullable=False),
+        sa.Column("name", sa.String(length=64), nullable=False),
+        sa.Column("usage", sa.String(length=64), nullable=False),
+        sa.Column("backup_state", sa.Boolean(), nullable=False),
+        sa.Column("device_type", sa.String(length=64), nullable=False),
+        sa.Column("user_id", sa.String(length=64), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["user_id"],
+            ["user.fs_webauthn_user_handle"],
+            name=op.f("fk_web_authn_user_id"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_web_authn")),
+    )
+    with op.batch_alter_table("web_authn", schema=None) as batch_op:
+        batch_op.create_index(
+            batch_op.f("ix_web_authn_credential_id"), ["credential_id"], unique=True
+        )
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("web_authn", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_web_authn_credential_id"))
+
+    op.drop_table("web_authn")
+    with op.batch_alter_table("user_sessions", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_user_sessions_user_id"))
+        batch_op.drop_index(batch_op.f("ix_user_sessions_is_active"))
+
+    op.drop_table("user_sessions")
+    op.drop_table("roles_users")
+    op.drop_table("oauth")
+    with op.batch_alter_table("activity", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_activity_user_id"))
+        batch_op.drop_index(batch_op.f("ix_activity_created_at"))
+
+    op.drop_table("activity")
+    op.drop_table("user")
+    op.drop_table("role")
+    with op.batch_alter_table("rate_limit_window", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_rate_limit_window_expires_at"))
+
+    op.drop_table("rate_limit_window")
+    with op.batch_alter_table("quart_security_state", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_quart_security_state_expires_at"))
+
+    op.drop_table("quart_security_state")
+    # ### end Alembic commands ###

stk/portal/views.py

@@ -0,0 +1,34 @@
+from quart import Blueprint, g, render_template
+from quart_security import auth_required
+from sqlalchemy import func, select
+
+from stk.user.models import Activity, Role, User
+
+portal = Blueprint("portal", __name__, static_folder="../static")
+
+
+@portal.before_request
+@auth_required("session")
+async def before_request():
+    pass
+
+
+@portal.after_request
+async def add_header(response):
+    response.headers["Cache-Control"] = "private, no-store"
+    return response
+
+
+@portal.route("/dashboard/")
+async def dashboard():
+    users_count = (await g.db_session.execute(select(func.count(User.id)))).scalar()
+    roles_count = (await g.db_session.execute(select(func.count(Role.id)))).scalar()
+    activities_count = (
+        await g.db_session.execute(select(func.count(Activity.id)))
+    ).scalar()
+    stats = {
+        "users": users_count,
+        "roles": roles_count,
+        "activities": activities_count,
+    }
+    return await render_template("dashboard.html", stats=stats)