stkit 17.0.0__tar.gz

stkit-17.0.0/.gitignore

@@ -0,0 +1,33 @@
+*.pyc
+.webassets-cache
+.idea
+celerybeat-schedule
+env
+.env
+.env.backup*
+local_settings.py
+node_modules/
+.DS_Store
+.sass-cache
+.vscode/
+.cache/
+.parcel-cache
+stk.sqlite3
+instance/
+
+
+__pycache__/
+
+# Claude Code
+.claude/settings.local.json
+*.skill
+.quartenv
+
+# Private planning docs and security reviews (never publish; checks.py fails if tracked)
+security-review*
+docs/plans/
+docs/stk-report.html
+docs/superpowers/
+
+# Browser smoke artifacts
+.stk/smoke/

stkit-17.0.0/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+## v17.0.0 (unreleased)
+
+stk becomes an installed, versioned package. An app is a separate, thin package that composes it and never edits a framework file, so upgrading stk is a version bump plus whatever its release note says.
+
+### Breaking
+
+- An app is no longer a fork of stk. `stk init <name>` writes an app package: `myapp/app.py` builds `Stk(__name__, config=Config, extensions=[...])`, settings are `class Config(stk.Config)` in `myapp/settings.py`, and the app depends on `stkit>=17,<18`: stk is published on PyPI as `stkit`, still imported as `stk` and run as `stk`. Commands find the app from `[tool.stk] app` in the nearest `pyproject.toml`, or from `STK_APP`.
+- `create_app(Config)` is replaced by `Stk(import_name, config=..., extensions=[...])`. Each extension is a package with `init_app(app)`; its `models` module is imported before it is called. `run.py` is gone: uvicorn serves the `[tool.stk] app` value (`myapp.app:app`).
+- Templates and static files resolve app first, then each extension's, then stk's. Core templates are reachable as `stk/<name>`. `layout.html` gains `title` and `navigation` blocks.
+- The sidebar is data: `stk/static/js/navigation.js` is removed. Extensions add pages with `app.navigation.append({...})`; they appear under Dashboard in extension order.
+- stk's migrations ship inside the package (`stk/migrations/`) as one squashed revision, `stk_0001`, with the branch label `stk`. An app keeps its own lineage in `myapp/migrations/`, and each app revision depends on stk's head. `stk db upgrade` runs `upgrade heads`. `alembic.ini` and the `alembic/` directory are gone. A database created by stk 16 is not upgraded.
+- `stk new <module>` writes an extension into the app package and adds it to the app's `extensions` list; it no longer patches `stk/app.py` or `navigation.js`.
+- `stk run` serves through uvicorn with a 3 second graceful shutdown, so Ctrl+C no longer hangs on open tabs. Its options are `--host`, `--port`, and `--reload/--no-reload`.
+- Importing stk needs no environment: missing `SECRET_KEY` or `SECURITY_PASSWORD_SALT` fails when the app is built. `.env` is read from the working directory. `Config.APP_DIR` and `Config.PROJECT_ROOT` are removed; the default SQLite database is `instance/stk.db` beside the app package.
+- `Dockerfile`, `docker-compose.yml`, `nginx/`, `postgres/`, and `.env-sample` move into the app template that `stk init` writes. Nginx and Caddy pass `/static/` to the app instead of reading `stk/static` from disk. `deploy.sh` requires `REPO`, your app's repository. `.gitattributes` and the merge-based upgrade guide are removed.
+- `checks.py` moves to `stk/checks.py` and runs against the app. Its docs checks run only inside the stk repository.
+
+### Also
+
+- `stk db check` and `stk smoke` use a throwaway database of the configured dialect, so Postgres apps are checked on Postgres (the role needs CREATEDB). Autogenerate never offers to drop PostGIS's `spatial_ref_sys`. `stk.migrations.portable_tables()` returns the tables SQLite can build.
+- Autogenerated revisions import what their column types need, and pass ruff without per-file exceptions.
+- `stk doctor` reports the app it loaded and understands two lineages.
+
+### Upgrade considerations
+
+There is nothing to upgrade from: 17.0.0 starts the new design. To move an app built on stk 16, start a fresh app with `stk init`, move each module into the app package with an `init_app`, move its settings into the app's `Config`, turn template and navigation edits into overrides and `app.navigation` entries, and replace its migration history with one fresh app revision. Paste-ready prompt for a coding agent:
+
+```text
+Move this app off its stk 16 fork onto stk 17. Run `uvx --from stkit stk init <name>` next to it. For each module the app added under stk/: move it to <name>/<module>/, give its __init__.py an init_app(app) that registers its blueprint and appends its sidebar entries to app.navigation, and add it to `extensions` in <name>/app.py. Move app settings into <name>/settings.py (class Config(stk.Config)). Replace edited stk templates with files at the same path in <name>/templates/ that extend "stk/<name>" and override blocks. Delete the old migrations, then run `uv run stk db upgrade` and `uv run stk db revision -m "initial"`. Done when `uv run stk verify` and `uv run stk smoke` pass and no file under stk is edited.
+```
+
+## v16.4.1 (2026-10-25)
+
+No migration required.
+
+- Apps built on stk upgrade by merging stk release tags: see Deployment, "Upgrading an app built on stk". `.gitattributes` keeps an app's README, CHANGELOG, lockfile, and brand files on merge once `git config merge.ours.driver true` is set. An app copied without stk's history records its starting commit once with `git merge -s ours --allow-unrelated-histories <commit>`.
+- `stk smoke` skips every WebSocket route, not only `/ws`, and any path listed in the new `STK_SMOKE_SKIP` app config value.
+- The Vue brace check in `stk verify` ignores `<script>` bodies, where JS template literals are valid.
+
+## v16.4.0 (2026-10-25)
+
+No migration required.
+
+- New `stk-lessons` skill. When a failure the docs did not warn about costs an agent time, it logs one line in `.stk/lessons.md` and continues. On request, it triages the log: drops covered or one-off lessons, confirms the rest in code, and proposes each at the strongest home that holds (code default, `stk verify` check, `stk doctor` hint, docs line, skill step). Nothing applies without approval. Apps built on stk get framework lessons in generic terms to send upstream.
+
+## v16.3.0 (2026-10-25)
+
+No migration required.
+
+- Static JS and CSS in the layouts load through `url_for('static', ...)`, which adds a content hash (`?v=...`). The app, `nginx/stk.conf`, and the Caddy config from `deploy.sh` cache versioned files forever and revalidate the rest. Servers set up by an earlier `deploy.sh` cached every static file for a year: re-run it or apply the new `handle_path /static/*` block to the Caddyfile.
+- `alembic.ini` no longer names a database, so `uv run alembic` targets the app's database like `stk db` does.
+- `Base` sets `eager_defaults`, so `server_default` and SQL `onupdate` columns are readable after a flush instead of raising `MissingGreenlet`.
+- `TestingConfig` in `stk/settings.py` pins the database, sessions, mail, OAuth, rate limits, breach check, and agent login. Subclass it in tests instead of `Config` so `.env` never reaches them.
+- `stk verify` fails on `{` inside a Vue `${ }` interpolation, which blanks the page.
+
+## v16.2.1 (2026-10-23)
+
+No migration required.
+
+- `stk verify` fails on a migration whose `upgrade()` drops or renames a table or column, retypes a column, or adds a NOT NULL column without a `server_default`. Mark a deliberate step with a `# destructive: <reason>` comment inside `upgrade()`.
+- `stk verify` fails when `CLAUDE.md` grows past 8KB or a skill past 4KB, so the agent index stays an index.
+
+## v16.2.0 (2026-10-23)
+
+No migration required.
+
+- The docs in `docs/src/content/docs/` are the single source for humans and agents. `.stk/context/` and the `stk-dev` skill are removed; their content moved into the Frontend, Models, JSON APIs, Background Work, Build Loop, and Deployment pages. `AGENTS.md` is now an index of those pages plus the rules that fail silently. Apps that referenced `.stk/context/*.md` should point at the docs pages instead.
+- `stk inspect commands` reports every command and option, as text, `--json`, or `--markdown`. The docs CLI reference is generated from it.
+- `stk verify` fails when the CLI reference is stale, when `stk/settings.py` reads an environment variable the Configuration page does not list, when `AGENTS.md` misses a docs page, or when docs, skills, or the README point at a file that does not exist.
+- New docs pages: Configuration, CLI Reference, Renaming Your App, and WebSockets in Background Work. The docs site uses the stk logo.
+
+## v16.1.0 (2026-10-19)
+
+No migration required. Existing databases keep their constraint names and show no drift.
+
+- `APP_NAME`, `APP_TAGLINE` and `APP_DESCRIPTION` settings brand titles and auth pages. The logo lives in one partial, `stk/templates/_brand.html`. The placeholder Terms of Service and Privacy Policy line is removed from login and registration.
+- `stk.security.csrf_exempt` lets a signed third-party webhook skip the CSRF token check. Host, API body and pagination checks still apply, and the view must authenticate the caller itself.
+- `stk smoke` also visits every parameterless GET page, skipping auth flows, APIs and webhooks, and fails on uncaught page errors.
+- Unhandled database errors return 500 and are logged instead of using the SQLAlchemy error code as the status.
+- `stk db downgrade -1` accepts relative targets.
+- `stk install` and `stk create` reject email addresses the login form would refuse.
+- New constraints are named by a convention on `Base.metadata`, so SQLite batch migrations can add foreign keys.
+- The navigation drawer starts closed on phones.
+- `stk --version` reports the framework version when an app renames its package, and `setup.sh` runs without a terminal.
+
+## v16.0.0 (2026-10-06)
+
+Requires quart-security 2.0.1. Run `uv run stk db upgrade` and `uv run stk protect-mfa` before upgrading an existing deployment. Preserve the MFA encryption keys.
+
+- Require CSRF tokens for application mutations and send them from Axios.
+- Use single-use OAuth state, PKCE, signed Google ID tokens, and verified GitHub email. Disable automatic email linking and enforce local MFA and account lockout.
+- Rotate Redis session IDs on authentication changes and keep tracking records aligned with revoked sessions.
+- Use atomic SQL authentication limits across workers. Apply migration `20261006_0002` before starting the app.
+- Bound WebSocket connections, queues, messages, and lifetime. Require same-origin connections and explicit broadcast recipients. Remove automatic audit broadcasts.
+- Enforce admin password policy and bound API pagination. Use Argon2id for new passwords; existing hashes still verify.
+- Encrypt enrolled and pending MFA seeds. `stk protect-mfa` encrypts dormant accounts and supports key rotation.
+- Disable public password registration by default. Set `SECURITY_REGISTERABLE=True` only when required.
+- Require unique database and Redis secrets plus TLS certificates in Docker Compose. Keep data services and the app port private.
+- Update vulnerable runtime packages and add PostgreSQL and Redis security checks to CI.
+
+See `SECURITY.md` for deployment requirements and review limits.
+
+## v15.0.0 (2026-10-06)
+
+Requires quart-security 2.0.0 and a database migration before startup.
+Run `uv run stk db upgrade` to add the shared authentication-state table.
+Existing login cookies are invalidated.
+
+- Share database sessions between authentication and application routes.
+- Revoke authentication state on logout, password resets, and single-session login.
+- Preserve local HTTP cookie configuration and default to secure cookies.
+- Pass application settings to password hashing in account commands.
+- Add regression checks for startup, copied cookies, session revocation, and TOTP replay.
+
+## v14.1.0 (2026-07-25)
+
+### Added
+- `stk doctor`: env, secrets, database, migration state, admin user, vendored
+  assets, agent-login exposure, browser, and REPL, each problem with the command
+  that fixes it. `--json` for tooling.
+- `stk verify --watch`: re-runs only the checks a changed file can break (models
+  touch migration drift, templates do not) and prints the remedy under a failure.
+- Every verify check now carries its remedy, in the text output and in the JSON.
+- `stk new <name>` generates and applies the migration, then prints the URL of the
+  page it created. `--no-migrate` opts out.
+- Docs: `build-loop.mdx` and `shell.mdx`, both example-first.
+
+### Changed
+- Alembic failures report one line plus a next step instead of a traceback.
+- CI actions bumped off Node 20 (checkout v7, setup-uv v9, upload-artifact v7).
+- `alembic.ini` sets `path_separator`, silencing the deprecation warning.
+
+### Removed
+- `stk migrate` and `stk migration-status`, pure aliases for `stk db upgrade` and
+  `stk db current`.
+
+## v14.0.0 (2026-07-25)
+
+Bundles the unreleased 13.4.x work (hardened auth via quart-security 1.4.1) with a
+new CLI, a frontend upgrade, and three gates that catch failures the old gate could
+not see.
+
+### Added
+- `stk` command as the single entry point: grouped `--help`, app factory baked in
+  (no `QUART_APP`), `python -m stk` and `uv run stk` both work. `quart <command>`
+  keeps working.
+- `stk shell`: async REPL with the app, a live `db` session, every model, query
+  helpers, and top-level `await`. Uses ptpython (dev extra) for highlighting,
+  fuzzy completion, and fish-style suggestions; falls back to the stdlib console.
+  `stk shell -c "await count(User)"` for one-shot queries and scripts.
+- `stk db check`: fails when models have drifted from migrations, measured by
+  running migrations onto a throwaway database. Part of `stk verify`, so CI enforces it.
+- `stk smoke` now visits `/`, measures WCAG contrast on every button, chip, and
+  alert, and fails on text that is invisible against its background.
+- `checks.py` asserts every route the report calls guarded actually rejects
+  anonymous access.
+- `vendor.sh` refreshes pinned frontend assets; versions recorded in
+  `stk/static/VERSIONS.txt`.
+
+### Changed
+- **Vuetify 3.7.8 to 4.1.6.** Material Design 2 type classes are gone; 67 usages
+  renamed to the MD3 names (`text-h5` to `text-headline-small`, and so on). Forks
+  with custom templates must do the same rename. Mapping table in
+  `.stk/context/frontend.md`.
+- Vue 3.3.4 to 3.5.40, now the production build (was shipping the dev build).
+  Axios to 1.18.1. Tabler Icons 3.45.0 self-hosted instead of an unpinned CDN.
+- `stk/commands.py` (918 lines) split into `stk/cli/`: `agent`, `database`,
+  `users`, `reports`, `smoke`, `base`.
+- Route auth in `stk inspect routes` is read from the actual guard chain instead
+  of guessed from path prefixes.
+- `stk verify` prints the tail of a failing check instead of a bare cross.
+
+### Fixed
+- Seven security routes (`/change`, `/tf-setup`, `/wan-register`, and others) were
+  reported as public while actually requiring auth.
+- `GET /mf-recovery` returned 500 to anonymous users: the template used
+  `mf_recovery_form` while quart-security passes `recovery_form`.
+- Nav filtering mutated state inside a computed, which hung the dashboard under
+  Vue 3.5's production reactivity (the dev build only warned).
+- Buttons rendered as anchors took the link colour, so a primary button on a
+  primary background was invisible. Vuetify 4 ships in CSS cascade layers, which
+  let unlayered app CSS win.
+- Smoke output redacted the agent-login token by list position, leaking it when a
+  page was added.
+
+### Removed
+- 5.1MB of unused Material Design Icons (referenced nowhere).
+- `register_shellcontext`, replaced by `stk shell`.
+- Empty `stk/core/` and app packages left over from a killed branch.
+
+## v11.3.0 (2025-12-02)
+
+### Added
+- Lite mode: Zero-config startup with `uv sync && flask run` — no Redis required
+- Full mode: Optional Redis + Celery via `uv sync --extra full`
+- SQLAlchemy-based sessions as default (Redis sessions optional)
+- AI-assisted development with AGENTS.md for Claude Code and Cursor
+
+### Changed
+- Redis and Celery moved to optional dependencies
+- SQLite database path now uses absolute path in `instance/stk.db`
+- Updated documentation for lite/full mode workflow
+- Simplified README with clearer positioning
+
+## v11.2.0 (2025-04-24)
+
+### Added
+- Production-ready Docker configuration with multi-stage builds
+- PostgreSQL service in Docker Compose setup
+- Improved environment variable handling for Docker
+- Support for user-specific Docker UID configuration
+- Enhanced setup.sh script with Docker configuration option
+
+### Changed
+- Optimized Dockerfile with multi-stage build for smaller, more secure images
+- Fixed Redis connectivity by using correct environment variables
+- Improved nginx configuration with proper retry settings
+- Enhanced tmpfs configuration for better performance
+- Added proper health checks for all Docker services
+
+## v11.1.0 (2025-03-30)
+
+### Added
+- Migrated from pip/venv to uv for package management
+- Faster installation and dependency resolution
+- Better Python environment isolation
+
+### Changed
+- Updated setup.sh script to use uv instead of venv
+- Modified Dockerfile to use uv for package installation
+- Updated documentation to reference uv
+
+## v11.0 (2023-03-27)
+
+### Added
+- New activity model to track user actions like creating and editing users/roles
+- Cursor Rules for improved code generation and assistance
+- Comprehensive documentation for Cursor Rules approach
+
+### Changed
+- Improved user and roles tables design in both frontend and backend
+- Transitioned from OpenAI integration to Cursor Rules for code generation
+- Enhanced admin user creation with better console output
+
+### Removed
+- Removed flask-openai dependency and related code generation commands
+- Removed OpenAI API key requirements
+
+### Fixed
+- Various UI and UX improvements
+- Code cleanup and bug fixes 

stkit-17.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Nidal Alhariri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stkit-17.0.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: stkit
+Version: 17.0.0
+Summary: An async Quart framework optimized for AI-assisted development workflows
+Author-email: Level09 <hello@level09.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiosmtplib>=5.0.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.16.0
+Requires-Dist: authlib<2,>=1.9.1
+Requires-Dist: bcrypt>=4.3.0
+Requires-Dist: blinker>=1.9.0
+Requires-Dist: click>=8.3.1
+Requires-Dist: cryptography>=45.0.5
+Requires-Dist: email-validator>=2.2.0
+Requires-Dist: httpx2>=2.16.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: joserfc<2,>=1.7.1
+Requires-Dist: libpass>=1.9.0
+Requires-Dist: orjson>=3.10.18
+Requires-Dist: pillow>=13.0.0
+Requires-Dist: psycopg2-binary>=2.9.10
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: qrcode>=8.2
+Requires-Dist: quart-security<3,>=2.0.1
+Requires-Dist: quart-session>=3.0.0
+Requires-Dist: quart>=0.20.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.41
+Requires-Dist: uvicorn>=0.40.0
+Requires-Dist: webauthn>=2.6.0
+Requires-Dist: wtforms>=3.2.1
+Provides-Extra: asgi
+Requires-Dist: hypercorn>=0.17.0; extra == 'asgi'
+Provides-Extra: dev
+Requires-Dist: playwright; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ptpython>=3.0.30; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: asyncpg>=0.30.0; extra == 'full'
+Requires-Dist: redis>=7.1.0; extra == 'full'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/src/assets/logo-dark.webp">
+    <img src="docs/src/assets/logo-light.webp" alt="stk" width="360">
+  </picture>
+</p>
+
+<h1 align="center">stk</h1>
+
+<p align="center">
+  <strong>Async Python framework with batteries you actually need.</strong><br>
+  Auth, 2FA, WebAuthn, OAuth, WebSockets, admin dashboard, Vue 3 frontend. No build step, no third-party auth services. One codebase, you own everything.
+  STK makes SaaS apps legible, changeable, testable, and operable by agents.
+</p>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a>
+  <a href="https://docs.astral.sh/uv/"><img src="https://img.shields.io/badge/uv-package%20manager-blueviolet.svg" alt="uv"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.stk.dev">Docs</a> &middot;
+  <a href="https://docs.stk.dev/llms.txt">llms.txt</a> &middot;
+  <a href="https://github.com/level09/stk/wiki">Tutorials</a>
+</p>
+
+---
+
+```bash
+uvx --from stkit stk init myapp && cd myapp
+uv run stk db upgrade       # database via Alembic
+uv run stk install          # admin user
+uv run stk run              # localhost:5000
+```
+
+Your app is its own package that composes stk, not a fork of it. Upgrading stk is a version bump.
+
+## Why stk
+
+Most frameworks give you routing and leave the rest as homework. Auth alone eats weeks. Then you bolt on Clerk or Auth0, hand your users' credentials to a third party, and pay per-MAU for the privilege.
+
+stk ships what actually matters:
+
+**You own your auth.** Login, session management, TOTP 2FA (Google Authenticator, Authy, 1Password), WebAuthn passkeys (Touch ID, YubiKey), recovery codes, OAuth (Google, GitHub). Production code, not a tutorial. Your users' data stays on your server.
+
+**Async all the way down.** Quart + async SQLAlchemy + aiosmtplib + native WebSockets. Not async bolted onto a sync framework. Real concurrency without threads, workers, or callback hell.
+
+**No JS build step.** Vue 3 + Vuetify 4 loaded directly in the browser. No webpack, no vite, no node_modules, no npm. Delete your frontend toolchain. Still get a polished admin dashboard with data tables, dark mode, collapsible sidebar, 5000+ icons.
+
+**SQLite by default.** Deploy anywhere. No managed database required. PostgreSQL when you need it, not when the framework demands it.
+
+**No Celery, no Redis (unless you want them).** Background tasks run on asyncio. Session store works with cookies or Redis. Complexity is opt-in.
+
+**Built to be operated by agents.** `stk inspect` reports routes, auth guards, models, and commands as JSON. `stk verify` and `stk smoke` are a real gate: lint, migration drift, and a real browser that fails on console errors and invisible text. The docs ship in the repo and the gate fails when they drift from the code.
+
+> **Want payments?** [ReadyKit](https://readykit.dev) adds Stripe, multi-tenancy, and teams on top of stk.
+
+## What's included
+
+- **Auth and security:** Argon2id passwords (12 char minimum), TOTP 2FA, passkeys as first or second factor, recovery codes, Google and GitHub OAuth with PKCE and verified emails, session tracking by IP and device, account lockout, per-IP rate limits shared across workers, CSRF on every mutation. Public sign-up is off by default.
+- **Admin dashboard:** users, roles, and an activity audit log, with server-paginated tables and JSON APIs.
+- **Real-time:** authenticated, origin-checked WebSockets that push to a named user and close when the session ends.
+- **Frontend:** Vue 3 and Vuetify 4 with no build step, dark mode, collapsible sidebar, notifications, Tabler Icons.
+- **Tooling:** one CLI, `stk`: run, shell, new, db, doctor, verify, smoke, inspect, report, and user management.
+- **Deploy:** a one-command VPS script (Caddy, systemd, hardened OS) or Docker Compose with PostgreSQL, Redis, and Nginx.
+
+## Stack
+
+| Layer | Tech |
+|-------|------|
+| Runtime | Python 3.11+, [uv](https://docs.astral.sh/uv/) |
+| Web | [Quart](https://quart.palletsprojects.com/) (async Flask) |
+| ORM | SQLAlchemy 2.0+ async |
+| Database | SQLite (default), PostgreSQL (optional) |
+| Migrations | Alembic |
+| Auth | [quart-security](https://quart-security.readthedocs.io/) (2FA, WebAuthn, OAuth) |
+| Frontend | Vue 3, Vuetify 4, Axios |
+| Server | Uvicorn (ASGI) behind Caddy or Nginx |
+
+## Documentation
+
+Everything else lives at [docs.stk.dev](https://docs.stk.dev), and in this repo at `docs/src/content/docs/`:
+[quick start](https://docs.stk.dev/getting-started/), [build loop](https://docs.stk.dev/build-loop/), [models](https://docs.stk.dev/models/), [frontend](https://docs.stk.dev/frontend/), [authentication](https://docs.stk.dev/authentication/), [configuration](https://docs.stk.dev/configuration/), [CLI reference](https://docs.stk.dev/cli/), [deployment](https://docs.stk.dev/deployment/), and [working with agents](https://docs.stk.dev/ai-coding/). Upgrade notes are in `CHANGELOG.md`; the production security contract is `SECURITY.md`.
+
+## License
+
+MIT

stkit-17.0.0/README.md

@@ -0,0 +1,88 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/src/assets/logo-dark.webp">
+    <img src="docs/src/assets/logo-light.webp" alt="stk" width="360">
+  </picture>
+</p>
+
+<h1 align="center">stk</h1>
+
+<p align="center">
+  <strong>Async Python framework with batteries you actually need.</strong><br>
+  Auth, 2FA, WebAuthn, OAuth, WebSockets, admin dashboard, Vue 3 frontend. No build step, no third-party auth services. One codebase, you own everything.
+  STK makes SaaS apps legible, changeable, testable, and operable by agents.
+</p>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a>
+  <a href="https://docs.astral.sh/uv/"><img src="https://img.shields.io/badge/uv-package%20manager-blueviolet.svg" alt="uv"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.stk.dev">Docs</a> &middot;
+  <a href="https://docs.stk.dev/llms.txt">llms.txt</a> &middot;
+  <a href="https://github.com/level09/stk/wiki">Tutorials</a>
+</p>
+
+---
+
+```bash
+uvx --from stkit stk init myapp && cd myapp
+uv run stk db upgrade       # database via Alembic
+uv run stk install          # admin user
+uv run stk run              # localhost:5000
+```
+
+Your app is its own package that composes stk, not a fork of it. Upgrading stk is a version bump.
+
+## Why stk
+
+Most frameworks give you routing and leave the rest as homework. Auth alone eats weeks. Then you bolt on Clerk or Auth0, hand your users' credentials to a third party, and pay per-MAU for the privilege.
+
+stk ships what actually matters:
+
+**You own your auth.** Login, session management, TOTP 2FA (Google Authenticator, Authy, 1Password), WebAuthn passkeys (Touch ID, YubiKey), recovery codes, OAuth (Google, GitHub). Production code, not a tutorial. Your users' data stays on your server.
+
+**Async all the way down.** Quart + async SQLAlchemy + aiosmtplib + native WebSockets. Not async bolted onto a sync framework. Real concurrency without threads, workers, or callback hell.
+
+**No JS build step.** Vue 3 + Vuetify 4 loaded directly in the browser. No webpack, no vite, no node_modules, no npm. Delete your frontend toolchain. Still get a polished admin dashboard with data tables, dark mode, collapsible sidebar, 5000+ icons.
+
+**SQLite by default.** Deploy anywhere. No managed database required. PostgreSQL when you need it, not when the framework demands it.
+
+**No Celery, no Redis (unless you want them).** Background tasks run on asyncio. Session store works with cookies or Redis. Complexity is opt-in.
+
+**Built to be operated by agents.** `stk inspect` reports routes, auth guards, models, and commands as JSON. `stk verify` and `stk smoke` are a real gate: lint, migration drift, and a real browser that fails on console errors and invisible text. The docs ship in the repo and the gate fails when they drift from the code.
+
+> **Want payments?** [ReadyKit](https://readykit.dev) adds Stripe, multi-tenancy, and teams on top of stk.
+
+## What's included
+
+- **Auth and security:** Argon2id passwords (12 char minimum), TOTP 2FA, passkeys as first or second factor, recovery codes, Google and GitHub OAuth with PKCE and verified emails, session tracking by IP and device, account lockout, per-IP rate limits shared across workers, CSRF on every mutation. Public sign-up is off by default.
+- **Admin dashboard:** users, roles, and an activity audit log, with server-paginated tables and JSON APIs.
+- **Real-time:** authenticated, origin-checked WebSockets that push to a named user and close when the session ends.
+- **Frontend:** Vue 3 and Vuetify 4 with no build step, dark mode, collapsible sidebar, notifications, Tabler Icons.
+- **Tooling:** one CLI, `stk`: run, shell, new, db, doctor, verify, smoke, inspect, report, and user management.
+- **Deploy:** a one-command VPS script (Caddy, systemd, hardened OS) or Docker Compose with PostgreSQL, Redis, and Nginx.
+
+## Stack
+
+| Layer | Tech |
+|-------|------|
+| Runtime | Python 3.11+, [uv](https://docs.astral.sh/uv/) |
+| Web | [Quart](https://quart.palletsprojects.com/) (async Flask) |
+| ORM | SQLAlchemy 2.0+ async |
+| Database | SQLite (default), PostgreSQL (optional) |
+| Migrations | Alembic |
+| Auth | [quart-security](https://quart-security.readthedocs.io/) (2FA, WebAuthn, OAuth) |
+| Frontend | Vue 3, Vuetify 4, Axios |
+| Server | Uvicorn (ASGI) behind Caddy or Nginx |
+
+## Documentation
+
+Everything else lives at [docs.stk.dev](https://docs.stk.dev), and in this repo at `docs/src/content/docs/`:
+[quick start](https://docs.stk.dev/getting-started/), [build loop](https://docs.stk.dev/build-loop/), [models](https://docs.stk.dev/models/), [frontend](https://docs.stk.dev/frontend/), [authentication](https://docs.stk.dev/authentication/), [configuration](https://docs.stk.dev/configuration/), [CLI reference](https://docs.stk.dev/cli/), [deployment](https://docs.stk.dev/deployment/), and [working with agents](https://docs.stk.dev/ai-coding/). Upgrade notes are in `CHANGELOG.md`; the production security contract is `SECURITY.md`.
+
+## License
+
+MIT

stkit-17.0.0/SECURITY.md

@@ -0,0 +1,24 @@
+# Security and production deployment
+
+Use the locked dependencies with `uv sync --frozen --extra full`. Apply `uv run stk db upgrade` and `uv run stk protect-mfa` before starting an existing deployment. Version 16 adds `rate_limit_window`; version 15 added `quart_security_state`. Both tables are required. Docker Compose runs the migrations before the app starts.
+
+Use a unique generated `SECRET_KEY` and `SECURITY_PASSWORD_SALT`. Set `STK_ENV=production`, `QUART_DEBUG=0`, and `SESSION_COOKIE_SECURE=True`. Set `STK_PUBLIC_URL` to the HTTPS origin of the app. Set `SECURITY_WAN_RP_ID` to its DNS name and `SECURITY_WAN_EXPECTED_ORIGIN` to that HTTPS origin. The public URL restricts request hosts and fixes OAuth callback URLs. Trust proxy headers only from your proxy. The Compose app port is private and Uvicorn trusts the internal proxy network.
+
+The production Compose stack requires `DB_ADMIN_PASSWORD`, `DB_PASSWORD`, `REDIS_PASSWORD`, `STK_HOST`, `TLS_CERTIFICATE`, and `TLS_PRIVATE_KEY`. Passwords must be unique and URL-safe because they appear in connection URLs. Certificate paths must be absolute, valid for the public host, and readable by the configured container UID. Renew certificates and reload Nginx before expiry. New PostgreSQL volumes use a separate non-superuser app role. Existing volumes need an operator privilege review because initialization scripts do not run again. Only ports 80 and 443 are published. Port 80 redirects to HTTPS. Keep container images patched and restrict access to the Docker host and network.
+
+Public password registration is disabled by default. Enable it only for an app that needs public registration. OAuth providers remain opt-in. OAuth creates accounts only from verified provider identities; it does not attach a provider to an existing email. Existing users must use their current sign-in method. Review provider links created before version 16 because this update cannot establish how those links were originally authorized. Provider access tokens are no longer stored for login. Remove stored legacy provider tokens through your approved data maintenance process.
+
+All POST, PUT, PATCH, and DELETE routes require the session CSRF token in a form or the `X-CSRFToken` header. The shared layout configures Axios. Custom API clients must fetch a rendered page and include its token. These APIs use session authentication. Do not disable CSRF for production. Webhooks from third parties that have no session can opt out per view with `stk.security.csrf_exempt` placed below the route decorator; an exempt view must authenticate the caller itself, for example by verifying an HMAC signature, and still gets the host, API body, and pagination checks.
+
+Authentication limits use atomic fixed-minute SQL windows shared across workers. Defaults are 120 authentication requests and 10 authentication attempts per IP per minute, shared across auth endpoints. `STK_AUTH_REQUEST_LIMIT` and `STK_AUTH_ATTEMPT_LIMIT` are application config values. Fixed windows permit a burst at a boundary. An edge proxy should apply total connection and traffic limits. Limits rely on a trusted client IP; behind a proxy, configure forwarded-header trust explicitly. A proxy error must not make the whole site use one IP or accept client-supplied IP headers.
+
+WebSocket defaults allow 5 connections per user and 1000 per worker, a queue of 32 messages, and 60 incoming messages per minute with a 64 KiB message limit. Sessions are checked before each outgoing message and every 5 seconds. Logout, account deactivation, expiry, and session revocation close the connection. These checks bound the revocation delay. `STK_WS_*` application config values can tune these limits. Connections must use the same origin, or an explicit `STK_WS_ALLOWED_ORIGINS` list. Broadcasts require a user ID. Audit entries are stored in the database and remain accessible through the admin API. In-memory delivery is local to one worker; use a separate authorized message transport if the app needs cross-worker delivery.
+
+New passwords use Argon2id. Legacy hashes verify and upgrade on login. Password creation and reset routes check minimum length and the breach service. The authentication dependency permits a password if that external service is unavailable; monitoring should detect these failures. Admin password hashes are generated off the event loop. MFA, OAuth, Redis, and shared state controls have regression tests. CI also checks PostgreSQL migrations, real Redis session behavior, and runtime dependency advisories.
+
+The 2026-10-06 review covers framework routes and local test fixtures. It is not a certification of a deployed application. Validate live OAuth provider settings, real authenticator/passkey enrollment, proxy behavior, certificate renewal, backup restoration, monitoring, and traffic capacity in your staging environment before production. A dependency scan only checks published advisories. See `security-review-2026-10-06.md` for the original findings and remediation evidence.
+
+
+TOTP seeds and pending setup secrets are encrypted by quart-security 2.0.1. Legacy seeds remain readable and upgrade on login or authenticated requests. `uv run stk protect-mfa` encrypts all dormant seeds and rotates existing encrypted seeds to the current key. The command prints only a count and commits the data changes as one transaction. Run it in a maintenance window after taking a protected backup.
+
+The default MFA encryption key is derived from `SECRET_KEY` for backward-compatible setup. Keep it stable. For independent key rotation, set `SECURITY_TOTP_ENCRYPTION_KEYS` to a comma-separated list of Fernet keys. The first key writes new data; all listed keys read existing data. Generate a key with `uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`. Protect keys separately from database backups. To move from the default to an independent keyring, include the old default key from `derive_totp_encryption_key(old_secret_key)` in the keyring until existing seeds have been rotated and pending setup states have expired. Retain keys needed for recovery of required backups. Do not change `SECRET_KEY` while using its derived MFA key unless you preserve the old MFA key. Invalid ciphertext or a wrong key fails closed.

stkit-17.0.0/examples/minimal/.env-sample

@@ -0,0 +1,78 @@
+# ============================================
+# STK CONFIGURATION
+# ============================================
+# Lite mode: uv sync && uv run stk run (just works)
+# Full mode: uv sync --extra full (Redis + asyncpg)
+# ============================================
+
+# === CORE (Required) ===
+SECRET_KEY=
+QUART_DEBUG=1
+STK_ENV=development
+SECURITY_REGISTERABLE=False
+SECURITY_PASSWORD_SALT=
+
+# === BRANDING ===
+#APP_NAME=stk
+#APP_TAGLINE=Secure. Scalable. Swift.
+#APP_DESCRIPTION=
+
+# === DATABASE ===
+# SQLite used by default (instance/stk.db) - no config needed
+# Schema changes are tracked with Alembic migrations
+# PostgreSQL (uncomment for production)
+#SQLALCHEMY_DATABASE_URI=postgresql+asyncpg://postgres:pass@localhost/dbname
+
+# === FULL MODE - Redis + asyncpg (optional) ===
+# Uncomment after: uv sync --extra full
+#REDIS_URL=redis://localhost:6379/1
+
+# === OAUTH (optional) ===
+GOOGLE_AUTH_ENABLED=False
+GOOGLE_OAUTH_CLIENT_ID=your_google_client_id
+GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret
+
+GITHUB_AUTH_ENABLED=False
+GITHUB_OAUTH_CLIENT_ID=your_github_client_id
+GITHUB_OAUTH_CLIENT_SECRET=your_github_client_secret
+
+# For local development only (remove in production)
+OAUTHLIB_INSECURE_TRANSPORT=1
+
+# === MAIL (optional) ===
+MAIL_SERVER=smtp.sendgrid.net
+MAIL_USERNAME=sendgrid
+MAIL_PASSWORD=sendgrid_secure_password
+SECURITY_EMAIL_SENDER=info@domain.com
+
+# === SESSION & COOKIES ===
+# Local HTTP only. Use True with HTTPS in production.
+SESSION_COOKIE_SECURE=False
+SESSION_COOKIE_HTTPONLY=True
+SESSION_COOKIE_SAMESITE=Lax
+# Set to True to logout other sessions on login (single session per user)
+DISABLE_MULTIPLE_SESSIONS=False
+
+# ============================================
+# DOCKER CONFIGURATION (docker compose up)
+# ============================================
+#COMPOSE_PROJECT_NAME=minimal
+#PYTHONUNBUFFERED=true
+#DOCKER_UID=1000
+#DB_ADMIN_PASSWORD=generate-a-separate-admin-secret
+#DB_PASSWORD=generate-a-unique-secret
+#REDIS_PASSWORD=generate-a-unique-secret
+#SQLALCHEMY_DATABASE_URI=postgresql+asyncpg://stk:${DB_PASSWORD}@postgres/stk
+#REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379/1
+
+# Required by the production Docker stack. Use readable certificate files.
+#STK_HOST=app.example.com
+#TLS_CERTIFICATE=/absolute/path/fullchain.pem
+#TLS_PRIVATE_KEY=/absolute/path/key.pem
+#STK_PUBLIC_URL=https://app.example.com
+#SECURITY_WAN_RP_ID=app.example.com
+#SECURITY_WAN_EXPECTED_ORIGIN=https://app.example.com
+
+# Optional independent MFA encryption keyring, newest key first.
+# Generate Fernet keys and retain old keys during rotation. See SECURITY.md.
+#SECURITY_TOTP_ENCRYPTION_KEYS=new-fernet-key,old-fernet-key

stkit-17.0.0/examples/minimal/.gitignore

@@ -0,0 +1,8 @@
+.env
+.env.backup*
+instance/
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/
+.stk/smoke/