regstack 0.4.0__tar.gz → 0.5.6__tar.gz

{regstack-0.4.0 → regstack-0.5.6}/.github/workflows/publish.yml

@@ -61,4 +61,9 @@ jobs:
         with:
           name: dist
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@release/v1
+      # Pinned to a commit SHA, not the mutable `release/v1` branch — the
+      # publish job has `id-token: write`, so a tag/branch swap in the
+      # action repo would let an attacker push a malicious wheel under our
+      # OIDC identity. Update by resolving the latest SHA on `release/v1`
+      # and bumping the trailing comment to match.
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1

{regstack-0.4.0 → regstack-0.5.6}/CHANGELOG.md

@@ -5,6 +5,87 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## 0.5.6 — 2026-05-13
+
+Eleven days of security-review remediation, supply-chain hardening,
+a full `mypy --strict` cleanup pass, and the per-route rate-limits
+feature rolled up into a single release.
+
+**Per-route IP rate limits.** Opt-in via the new `rate_limit` extra
+(or a host-supplied `slowapi.Limiter`) plus any of the new
+`RegStackConfig.*_rate_limit` fields (`login_rate_limit`,
+`register_rate_limit`, `forgot_password_rate_limit`,
+`reset_password_rate_limit`, `verify_rate_limit`,
+`resend_verification_rate_limit`, `change_password_rate_limit`,
+`change_email_rate_limit`, `confirm_email_change_rate_limit`,
+`delete_account_rate_limit`). Each accepts a slowapi-syntax string
+(`"5/minute"`, `"5/minute;20/hour"`). Empty / unset means no limit
+on that route — `LockoutService` still defends `/login` against
+credential stuffing per-account. When `*_rate_limit` strings are
+configured but neither a `rate_limiter=` argument is passed nor
+the `rate_limit` extra is installed, `RegStack.router` raises
+`RuntimeError` on first access — failing closed beats silently
+disabling the protection. Hosts remain responsible for
+`app.state.limiter` and `app.add_exception_handler(RateLimitExceeded, ...)`;
+slowapi owns the 429 response shape. The previously-reserved
+`login_max_per_minute` / `login_max_per_hour` fields are kept for
+back-compat but unwired.
+
+**Security fixes.**
+
+- JWT 401 detail now returns a static `"Invalid or expired token."`;
+  no longer leaks the pyjwt failure reason (signature mismatch /
+  expired / malformed / audience mismatch).
+- OAuth sign-in now honours `allow_registration=False`. Previously,
+  `/register` respected the flag but the OAuth `_resolve_user`
+  "brand-new account" branch did not, creating accounts even when
+  self-service signup was disabled.
+- Admin `DELETE /admin/users/{id}` now cascades `oauth_identities`,
+  matching the user-initiated `DELETE /account` path. Previously
+  left orphan rows that blocked re-registration of the same Google
+  subject.
+- `POST /phone/start` and `DELETE /phone` now return 400 (not crash
+  with HTTP 500) for OAuth-only users who have no `hashed_password`.
+
+**Breaking change — hook contracts.** `mfa_login_started` and
+`phone_setup_started` no longer include the raw OTP code in their
+kwargs. Hooks are best-effort observability and are the documented
+integration surface for analytics / logging / Slack notifications,
+so a plaintext OTP in `**kwargs` is a leak waiting to happen.
+Hosts that subscribed to either event to take over SMS delivery
+should migrate to a custom `SmsService` subclass — the supported
+delivery override.
+
+**Dependency floors raised for CVEs.**
+
+- `pyjwt>=2.12.1` for CVE-2026-32597 (`crit` header bypass, CVSS 7.5).
+- `cryptography>=46.0.7` added explicitly to the `oauth` extra for
+  CVE-2026-26007 (ECC subgroup attack on the JWKS code path, CVSS
+  8.2) plus CVE-2026-34073 and CVE-2026-39892.
+- `python-multipart>=0.0.26` for CVE-2026-40347 (DoS via oversized
+  multipart preamble).
+
+**Supply chain.** `pypa/gh-action-pypi-publish` in `publish.yml`
+pinned to a commit SHA instead of the mutable `release/v1` branch.
+The publish job holds `id-token: write`, so a tag/branch swap
+upstream would let an attacker push a malicious wheel under our
+OIDC identity.
+
+**Removed.** `PasswordHasher.needs_rehash` — called pwdlib's
+non-existent `check_needs_rehash` and would `AttributeError` if
+anyone invoked it. No callers in src or tests. If you were planning
+to use it, call `pwdlib.PasswordHash.verify_and_update` directly.
+
+**Internal.** 72 `mypy --strict` errors cleared across 35 files;
+`inv lint` is now green end-to-end. Mongo
+`BlacklistRepo.purge_expired` added (protocol parity with SQL).
+`KNOWN_EVENTS` reconciled — 7 previously-undeclared events added
+(`verification_requested`, `email_change_requested`, `email_changed`,
+`phone_setup_started`, `mfa_login_started`, `mfa_enabled`,
+`mfa_disabled`). `user_logged_out` now actually fires from
+`routers/logout.py` (was listed in `KNOWN_EVENTS` but no router
+emitted it).
+
 ## 0.3.0 — 2026-04-30
 
 **OAuth — Sign in with Google.** Opt-in via the new `oauth` extra

{regstack-0.4.0 → regstack-0.5.6}/CLAUDE.md

@@ -77,6 +77,20 @@ The full plan, including milestone scope and deferred items, lives at
   four layers: validators (unit), writer (golden-file), routes
   (TestClient), full SPA flow (Playwright e2e). Run e2e with
   `inv test-e2e`; `inv test-all` chains it after the backend matrix.
+- **Theme designer — done.** `regstack theme design` opens a sibling
+  pywebview window with controls for every `--rs-*` variable and a
+  real-time preview of the bundled SSR widgets (renders the same
+  `.rs-*` classes the SSR pages render, so what you see is what
+  you'll ship). Save writes `regstack-theme.css`; the designer
+  round-trips values back into the form on next launch so iteration
+  is non-destructive. Lives in `src/regstack/wizard/theme_designer/`,
+  registered via a `_LazyThemeGroup` mirroring the OAuth pattern.
+  Same four-layer test stack (validators / writer / routes /
+  Playwright e2e). The shared scaffold (FastAPI app, uvicorn launcher,
+  pywebview shim, e2e fixture pattern) is duplicated rather than
+  abstracted into a base class — the two tools have meaningfully
+  different inputs and an early shared base would calcify the wrong
+  decisions. Refactor only when a third pywebview tool lands.
 
 ## Three kinds of single-use proof
 

{regstack-0.4.0 → regstack-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.4.0
+Version: 0.5.6
 Summary: Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB.
 Project-URL: Homepage, https://github.com/jdrumgoole/regstack
 Project-URL: Repository, https://github.com/jdrumgoole/regstack
@@ -27,8 +27,8 @@ Requires-Dist: jinja2>=3.1
 Requires-Dist: pwdlib[argon2]>=0.2.1
 Requires-Dist: pydantic-settings>=2.2
 Requires-Dist: pydantic>=2.6
-Requires-Dist: pyjwt>=2.8
-Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pyjwt>=2.12.1
+Requires-Dist: python-multipart>=0.0.26
 Requires-Dist: pywebview>=5.0
 Requires-Dist: sqlalchemy[asyncio]>=2.0
 Requires-Dist: tomlkit>=0.13
@@ -36,10 +36,11 @@ Requires-Dist: uvicorn[standard]>=0.29
 Provides-Extra: dev
 Requires-Dist: anyio>=4.3; extra == 'dev'
 Requires-Dist: asyncpg>=0.29; extra == 'dev'
+Requires-Dist: cryptography>=46.0.7; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: invoke>=2.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pyjwt[crypto]>=2.8; extra == 'dev'
+Requires-Dist: pyjwt[crypto]>=2.12.1; extra == 'dev'
 Requires-Dist: pymongo>=4.9; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
@@ -47,6 +48,7 @@ Requires-Dist: pytest-playwright>=0.5; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: slowapi>=0.1.9; extra == 'dev'
 Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: furo>=2024.1; extra == 'docs'
@@ -58,9 +60,12 @@ Requires-Dist: sphinx>=7.3; extra == 'docs'
 Provides-Extra: mongo
 Requires-Dist: pymongo>=4.9; extra == 'mongo'
 Provides-Extra: oauth
-Requires-Dist: pyjwt[crypto]>=2.8; extra == 'oauth'
+Requires-Dist: cryptography>=46.0.7; extra == 'oauth'
+Requires-Dist: pyjwt[crypto]>=2.12.1; extra == 'oauth'
 Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: rate-limit
+Requires-Dist: slowapi>=0.1.9; extra == 'rate-limit'
 Provides-Extra: ses
 Requires-Dist: aioboto3>=12.3; extra == 'ses'
 Provides-Extra: sns
@@ -143,7 +148,7 @@ result everywhere is what regstack is for.
 ✔ Server-rendered HTML pages, theme with one CSS file
 ✔ Pluggable email (console / SMTP / Amazon SES) and SMS (Amazon SNS / Twilio)
 ✔ Argon2 password hashing, CSP-friendly templates
-✔ Setup wizard (`regstack init`) and config validator (`regstack doctor`)
+✔ Setup wizards (live in their own pywebview windows): `regstack init` (project bootstrap), `regstack oauth setup` (guided Google OAuth client config), `regstack theme design` (live theme designer with preview), and `regstack doctor` (config validator)
 ✔ Three storage backends: SQLite, PostgreSQL, MongoDB — chosen by URL
 ```
 
@@ -186,7 +191,7 @@ register from the command line:
 ```bash
 curl -X POST http://localhost:8000/api/auth/register \
     -H 'content-type: application/json' \
-    -d '{"email":"alice@example.com","password":"hunter2hunter2","full_name":"Alice"}'
+    -d '{"email":"alice@app.example.com","password":"<password>","full_name":"Alice"}'
 ```
 
 The bundled example serves themed SSR pages at `/account/*`, prints
@@ -251,8 +256,8 @@ The same docs are also browsable as Markdown in [`docs/`](https://github.com/jdr
 Alpha. Single-file SQLite is the default and runs with no infrastructure;
 PostgreSQL and MongoDB backends pass the same parametrized integration
 suite. OAuth (Google) shipped in `v0.3.0`; the `regstack oauth setup`
-guided wizard shipped in `v0.4.0`. Latest tagged release: `v0.4.0`.
-See the
+guided wizard in `v0.4.0`; the live `regstack theme design` tool in
+`v0.5.0`. Latest tagged release: `v0.5.0`. See the
 [changelog](https://regstack.readthedocs.io/en/latest/changelog.html)
 for the per-release breakdown.
 

{regstack-0.4.0 → regstack-0.5.6}/README.md

@@ -72,7 +72,7 @@ result everywhere is what regstack is for.
 ✔ Server-rendered HTML pages, theme with one CSS file
 ✔ Pluggable email (console / SMTP / Amazon SES) and SMS (Amazon SNS / Twilio)
 ✔ Argon2 password hashing, CSP-friendly templates
-✔ Setup wizard (`regstack init`) and config validator (`regstack doctor`)
+✔ Setup wizards (live in their own pywebview windows): `regstack init` (project bootstrap), `regstack oauth setup` (guided Google OAuth client config), `regstack theme design` (live theme designer with preview), and `regstack doctor` (config validator)
 ✔ Three storage backends: SQLite, PostgreSQL, MongoDB — chosen by URL
 ```
 
@@ -115,7 +115,7 @@ register from the command line:
 ```bash
 curl -X POST http://localhost:8000/api/auth/register \
     -H 'content-type: application/json' \
-    -d '{"email":"alice@example.com","password":"hunter2hunter2","full_name":"Alice"}'
+    -d '{"email":"alice@app.example.com","password":"<password>","full_name":"Alice"}'
 ```
 
 The bundled example serves themed SSR pages at `/account/*`, prints
@@ -180,8 +180,8 @@ The same docs are also browsable as Markdown in [`docs/`](https://github.com/jdr
 Alpha. Single-file SQLite is the default and runs with no infrastructure;
 PostgreSQL and MongoDB backends pass the same parametrized integration
 suite. OAuth (Google) shipped in `v0.3.0`; the `regstack oauth setup`
-guided wizard shipped in `v0.4.0`. Latest tagged release: `v0.4.0`.
-See the
+guided wizard in `v0.4.0`; the live `regstack theme design` tool in
+`v0.5.0`. Latest tagged release: `v0.5.0`. See the
 [changelog](https://regstack.readthedocs.io/en/latest/changelog.html)
 for the per-release breakdown.
 

{regstack-0.4.0 → regstack-0.5.6}/docs/architecture.md

@@ -54,9 +54,13 @@ multi-tenant deployments where a single FastAPI app serves multiple
 The backend is auto-built from `config.database_url` if not supplied
 explicitly. URL scheme decides:
 
-- `sqlite+aiosqlite://` → SQLAlchemy backend in SQLite mode.
-- `postgresql+asyncpg://` → SQLAlchemy backend in Postgres mode.
-- `mongodb://` / `mongodb+srv://` → Mongo backend.
+- `sqlite+aiosqlite:///PATH` → SQLAlchemy backend in SQLite mode.
+  `PATH` is `./dbname.db` for a relative file, `/var/lib/app/dbname.db`
+  for an absolute file, or `:memory:` for an ephemeral in-process DB.
+- `postgresql+asyncpg://<username>:<password>@dbhost.example.com:5432/dbname`
+  → SQLAlchemy backend in Postgres mode.
+- `mongodb://<username>:<password>@dbhost.example.com:27017/dbname`
+  (or `mongodb+srv://…`) → Mongo backend.
 
 The façade exposes:
 

{regstack-0.4.0 → regstack-0.5.6}/docs/changelog.md

@@ -3,6 +3,154 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 0.5.6 — 2026-05-13
+
+A rollup release that consolidates 11 days of security-review
+remediation, supply-chain hardening, a full `mypy --strict` pass,
+and the per-route rate-limits feature.
+
+### Added
+
+- **Per-route IP rate limits.** Opt-in via the new `rate_limit` extra
+  (or a host-supplied `slowapi.Limiter`) plus any of the new
+  `RegStackConfig.*_rate_limit` fields (`login_rate_limit`,
+  `register_rate_limit`, `forgot_password_rate_limit`,
+  `reset_password_rate_limit`, `verify_rate_limit`,
+  `resend_verification_rate_limit`, `change_password_rate_limit`,
+  `change_email_rate_limit`, `confirm_email_change_rate_limit`,
+  `delete_account_rate_limit`). Each accepts a slowapi-syntax string
+  (`"5/minute"`, `"5/minute;20/hour"`).
+- New constructor argument `RegStack(rate_limiter=...)`. When at
+  least one `*_rate_limit` field is set, regstack expects either
+  this argument or the `rate_limit` extra; failure to provide one
+  raises `RuntimeError` on first access to `regstack.router` —
+  failing closed beats silently disabling the protection. Hosts
+  remain responsible for `app.state.limiter` and the
+  `RateLimitExceeded` exception handler; slowapi owns the 429
+  response shape.
+- **`user_logged_out` hook now fires.** The event was listed in
+  `KNOWN_EVENTS` since M1 but no router ever emitted it.
+  `routers/logout.py` now fires `user_logged_out` (with a `user=`
+  kwarg) immediately after the bearer token is revoked.
+
+### Changed (security)
+
+- **JWT 401 responses no longer leak the pyjwt error reason.**
+  Replaced `f"Invalid token: {exc}"` with the static `"Invalid or
+  expired token."`. The pyjwt error text disclosed *why* a token was
+  rejected (signature mismatch, expired, malformed, audience
+  mismatch) — useful signal for an attacker probing the auth
+  surface.
+- **OAuth sign-in honours `allow_registration=False`.** `/register`
+  already did; the OAuth `_resolve_user` "brand-new account" branch
+  did not, so an operator who disabled self-service signup still got
+  accounts created via "Sign in with Google". The OAuth callback now
+  redirects with `?error=registration_disabled` if no existing
+  account matches and registration is disabled.
+- **Admin `DELETE /admin/users/{id}` now cascades
+  `oauth_identities`.** Matches the user-initiated `DELETE
+  /account` flow; previously left orphan rows that blocked the
+  Google subject from re-registering.
+- **`POST /phone/start` and `DELETE /phone` guard against OAuth-only
+  users.** Both endpoints previously crashed with HTTP 500 for
+  users with `hashed_password=None`. Both now return 400 with a
+  message pointing to forgot-password (which doubles as a "set
+  initial password" path).
+
+### Changed (BREAKING — hook contracts)
+
+- **`mfa_login_started` and `phone_setup_started` no longer include
+  the raw OTP code in their kwargs.** Hooks are best-effort
+  observability and are the documented integration surface for
+  analytics / logging / Slack notifications, so a plaintext OTP in
+  `**kwargs` is a leak waiting to happen — a host adding
+  `logger.info(kw)` to a hook handler is enough to put OTPs in a
+  log stream. Hosts that subscribed to either event to take over
+  SMS delivery should migrate to a custom `SmsService` subclass
+  (the supported delivery override). The other kwargs (`user`,
+  `phone`) remain.
+
+### Changed (deps)
+
+- `pyjwt>=2.12.1` (was `>=2.8`). Picks up CVE-2026-32597 (`crit`
+  header bypass, CVSS 7.5).
+- `cryptography>=46.0.7` added explicitly to the `oauth` extra
+  (was pulled transitively, unbounded). Picks up CVE-2026-26007
+  (ECC subgroup attack on the JWKS code path, CVSS 8.2) plus
+  CVE-2026-34073 and CVE-2026-39892.
+- `python-multipart>=0.0.26` (was `>=0.0.9`). Picks up
+  CVE-2026-40347 (DoS via oversized multipart preamble).
+- `pypa/gh-action-pypi-publish` in `publish.yml` pinned to a commit
+  SHA instead of the mutable `release/v1` branch. The publish job
+  holds `id-token: write`, so a tag/branch swap upstream would let
+  an attacker push a malicious wheel under our OIDC identity.
+
+### Removed
+
+- `PasswordHasher.needs_rehash` — called pwdlib's non-existent
+  `check_needs_rehash` and would `AttributeError` if anyone invoked
+  it. No callers in src or tests. If you were planning to use it,
+  call `pwdlib.PasswordHash.verify_and_update` directly.
+
+### Internal
+
+- 72 `mypy --strict` errors cleared across 35 files. `inv lint` is
+  green end-to-end (ruff + mypy). Still local-only — not yet a CI
+  gate.
+- Mongo `BlacklistRepo.purge_expired` added (was missing from the
+  Mongo impl; SQL impl already had it). Mongo's TTL index still
+  reaps automatically; the explicit `delete_many` is for protocol
+  parity and for tests that can't wait for the 60-second TTL
+  monitor.
+- `KNOWN_EVENTS` reconciled with reality: 7 previously-undeclared
+  events added (`verification_requested`, `email_change_requested`,
+  `email_changed`, `phone_setup_started`, `mfa_login_started`,
+  `mfa_enabled`, `mfa_disabled`).
+- `routers/_helpers.require_password_set` factored out of
+  `routers/account.py` and reused in `routers/phone.py`.
+- `AsyncDatabase[MongoDoc]` / `AsyncMongoClient[MongoDoc]`
+  parameterized across the Mongo backend so pymongo's typed stubs
+  are satisfied.
+
+### Notes
+
+- `LockoutService` (per-account, sliding-window failure counter) is
+  unchanged and continues to defend `/login` against
+  credential-stuffing against a single account. Per-route IP limits
+  are orthogonal: they defend each endpoint against a single source
+  IP spamming requests across many accounts.
+- The previously-reserved `login_max_per_minute` /
+  `login_max_per_hour` config fields are kept for back-compat but
+  no longer have any effect. Switch to the per-route fields when
+  you next touch your config.
+
+## 0.5.0 — 2026-05-02
+
+### Added
+
+- **Theme designer.** `regstack theme design` opens a native pywebview
+  window with controls for every `--rs-*` CSS custom property and a
+  real-time preview of the bundled SSR widgets (sign-in form, success
+  / error banners, danger-zone button). Saving writes
+  `regstack-theme.css`; the designer round-trips values back into the
+  form on next launch so iteration is non-destructive. `--print-only`
+  mode takes repeatable `--var NAME=VALUE` pairs (with a `dark:`
+  prefix for dark-scheme overrides) and writes the file headlessly.
+  Lives in `regstack.wizard.theme_designer`; registered as a lazy
+  Click subgroup so `regstack init` / `doctor` don't pay the
+  pywebview/uvicorn import cost.
+- "Why use regstack" pitch in `docs/index.md` updated to surface the
+  two pywebview tools (`oauth setup` + `theme design`) as a
+  distinguishing feature vs. fastapi-users / Auth0 / Keycloak.
+
+### Docs
+
+- New "About the examples" convention block at the top of
+  `docs/index.md`. Every URL, email, smtp host, and admin command
+  across the docs now extrapolates from the same fictional app at
+  `app.example.com` with `<username>` / `<password>` placeholders —
+  no more `user:pw@host/dbname` / `db.internal/myapp` mishmash.
+
 ## 0.4.0 — 2026-05-02
 
 ### Added

regstack-0.5.6/docs/cli.md

@@ -0,0 +1,187 @@
+# CLI reference
+
+`regstack` is the entry point installed by the package. All sub-commands
+share a config-loading model: programmatic kwargs > env vars >
+`regstack.secrets.env` > `regstack.toml` > defaults. The `--config <path>`
+flag overrides where the TOML file is found.
+
+## `regstack init`
+
+Interactive wizard that writes `regstack.toml` and `regstack.secrets.env`
+in the current directory. Asks which backend to use (SQLite default →
+Postgres → MongoDB), generates a 64-byte JWT secret, runs DNS sanity
+checks if asked, never provisions infrastructure.
+
+```bash
+uv run regstack init
+uv run regstack init --target /etc/app --force
+```
+
+Options:
+
+- `--target DIR` — directory to write the config files (default cwd).
+- `--force` — overwrite without confirming.
+
+Re-running the wizard prompts before overwriting unless `--force` is
+passed; pre-existing answers aren't kept (the wizard is intentionally
+stateless).
+
+## `regstack oauth setup`
+
+Opens a guided 12-step wizard in a native webview window that walks you
+through registering a Google OAuth 2.0 client (project selection,
+consent screen, redirect URI, credentials) and merges the result into
+your existing `regstack.toml` and `regstack.secrets.env`. The merge is
+**non-clobbering** — comments, unrelated tables (`[email]`, `[sms]`,
+…), and unrelated top-level keys are preserved. Re-run any time to
+rotate credentials or change the linking policy.
+
+```bash
+uv run regstack oauth setup
+uv run regstack oauth setup --target /etc/app
+```
+
+Options:
+
+- `--target DIR` — directory containing (or to receive) `regstack.toml`
+  (default cwd).
+- `--api-prefix PREFIX` — router prefix the host mounts regstack under
+  (default `/api/auth`). Used to compute the suggested redirect URI.
+- `--port N` — pin the wizard server's TCP port (default: random free
+  port on `127.0.0.1`).
+- `--print-only` — skip the GUI; print the TOML + secrets diff that
+  *would* be written to stdout, then exit. Useful for headless hosts
+  (CI, servers without a webview backend) and dry-run smoke tests.
+  Pair with `--client-id`, `--client-secret`, `--base-url`,
+  `--auto-link/--no-auto-link`, `--mfa/--no-mfa`.
+
+The interactive mode requires a desktop environment with a webview
+backend (WebKit on macOS, GTK / QtWebEngine on Linux, Edge WebView2 on
+Windows). On a headless host it exits with a clear error pointing at
+`--print-only`.
+
+The wizard binds to `127.0.0.1` only and authenticates every API call
+with a per-launch random token, so a hostile process on the same host
+can't drive the write endpoint.
+
+## `regstack theme design`
+
+Opens a live designer for `regstack-theme.css` in a native pywebview
+window. The left pane has controls for every `--rs-*` CSS custom
+property; the right pane renders the bundled SSR widgets (sign-in
+form, success / error messages, danger-zone button) with your changes
+applied in real time. Click **Save** to write the file; **Reset to
+defaults** to start over; **Copy CSS** to put the generated
+stylesheet on the clipboard without writing.
+
+```bash
+uv run regstack theme design
+uv run regstack theme design --target /var/www/static
+```
+
+Options:
+
+- `--target DIR` — directory to write `regstack-theme.css` into
+  (default cwd).
+- `--filename NAME` — output filename
+  (default `regstack-theme.css`).
+- `--port N` — pin the designer's TCP port (default: random free
+  port on `127.0.0.1`).
+- `--print-only` — skip the GUI; write the file from `--var` pairs
+  and emit a JSON summary. For headless / CI use.
+- `--var NAME=VALUE` — repeatable. Used with `--print-only`. Prefix
+  with `dark:` to set the dark-scheme value, e.g.
+  `--var dark:--rs-accent=#2dd4bf`.
+
+Re-running the designer reloads the previous values out of the file,
+so iterating on a theme is non-destructive. Only the `:root` and
+`@media (prefers-color-scheme: dark)` blocks are managed by the
+designer — anything else in the file is left alone.
+
+Same security shape as `regstack oauth setup`: binds `127.0.0.1`
+only, every API call requires a per-launch random token.
+
+## `regstack create-admin`
+
+Create or promote a superuser. Idempotent.
+
+```bash
+uv run regstack create-admin --email admin@app.example.com
+uv run regstack create-admin --email admin@app.example.com --password 'long-strong-password'
+uv run regstack create-admin --email admin@app.example.com --config /etc/app/regstack.toml
+```
+
+Options:
+
+- `--email EMAIL` *(required)*.
+- `--password PW` — if omitted, prompts (with confirmation).
+- `--config PATH` — TOML file to load (default: env or cwd).
+
+If the user already exists, the command sets `is_superuser=True` and
+keeps the existing password. If they don't exist, it creates the user
+with `is_active=True`, `is_verified=True`, `is_superuser=True` and the
+provided password.
+
+## `regstack migrate`
+
+Runs the bundled Alembic migrations against the configured
+`database_url`. Idempotent — re-running on a DB already at the target
+revision is a no-op. Use this on SQL backends (SQLite / PostgreSQL)
+to roll the schema forward to a new regstack release.
+
+```bash
+uv run regstack migrate
+uv run regstack migrate --target head
+uv run regstack migrate --config /etc/app/regstack.toml --target 0001
+```
+
+Options:
+
+- `--config PATH` — TOML file to load (default: cwd / `$REGSTACK_CONFIG`).
+- `--target REV` — revision to upgrade to (default `head`). Accepts
+  any Alembic revision spec: a revision id (`0001`), a relative step
+  (`+1`), or `head`.
+
+Mongo backends are silently skipped: TTL indexes are installed by
+`RegStack.install_schema()` on every app start, so there's no separate
+migration story to run. Output prints the before / after revision and
+exits non-zero if Alembic raises.
+
+## `regstack doctor`
+
+Runs read-only validation against the loaded config and reports each
+check on a green/red line. Exit code is the number of failed checks —
+suitable for use in container health checks.
+
+```bash
+uv run regstack doctor
+uv run regstack doctor --config /etc/app/regstack.toml
+uv run regstack doctor --check-dns
+uv run regstack doctor --send-test-email alice@app.example.com
+```
+
+Options:
+
+- `--config PATH` — TOML file to load.
+- `--check-dns` — run SPF / DMARC / MX `dig`s on the sender domain.
+  Internet-dependent; off by default.
+- `--send-test-email TO` — actually send a probe email through the
+  configured backend. Costs real money on SES; off by default.
+
+Default checks:
+
+| Check | Pass criterion |
+|-------|----------------|
+| `jwt secret` | Present, ≥ 32 chars |
+| `backend` | `Backend.ping()` succeeds (works for any backend) |
+| `schema` | Mongo: required indexes present. SQL: `users` table responds to `count(*)` |
+| `email backend` | `build_email_service(config.email)` instantiates |
+
+Optional checks:
+
+| Check | Pass criterion |
+|-------|----------------|
+| `dns mx` | At least one MX record on the sender domain |
+| `dns spf` | A TXT record containing `v=spf1` |
+| `dns dmarc` | A TXT record at `_dmarc.<domain>` containing `v=DMARC1` |
+| `email send` | The configured backend's `send()` returned without raising |

{regstack-0.4.0 → regstack-0.5.6}/docs/configuration.md

@@ -85,15 +85,17 @@ regstack picks a backend at construction time from the URL scheme of
   - Notes
 
 * - SQLite
-  - `sqlite+aiosqlite:///./path.db`
+  - Relative file: `sqlite+aiosqlite:///./dbname.db`
   - Default. Bundled in the base install — no extras needed.
-    `:memory:` works too (per-test).
+    See [SQLite URL forms](#sqlite-url-forms) below for absolute-path
+    and in-memory variants.
 * - Postgres
-  - `postgresql+asyncpg://user:pw@host/dbname`
+  - `postgresql+asyncpg://<username>:<password>@dbhost.example.com:5432/dbname`
   - Requires the `postgres` extra (pulls in `asyncpg`). The driver is
     pinned to `+asyncpg` — sync drivers won't work.
 * - MongoDB
-  - `mongodb://host:port/dbname` (or `mongodb+srv://`)
+  - `mongodb://<username>:<password>@dbhost.example.com:27017/dbname`
+    (or `mongodb+srv://<username>:<password>@app.abc123.mongodb.net/dbname`)
   - Requires the `mongo` extra (pulls in `pymongo`). Database is taken
     from the URL path; falls back to ``mongodb_database`` if absent.
 ```
@@ -102,6 +104,41 @@ The active backend exposes the same five repository protocols on
 ``RegStack.users``, ``.pending``, ``.blacklist``, ``.attempts``,
 ``.mfa_codes``. Routers / hooks never branch on backend kind.
 
+### SQLite URL forms
+
+SQLite is the default backend and the only one whose URL points at a
+file rather than a network host. The shape is always:
+
+```
+sqlite+aiosqlite:///PATH
+```
+
+…where the prefix is fixed and `PATH` is whatever you want SQLAlchemy
+to open. Three useful values for `PATH`:
+
+| `PATH` | Resolves to | When to use it |
+|---|---|---|
+| `./dbname.db` | `dbname.db` in the process working directory | Local dev and the bundled `examples/` apps. |
+| `/var/lib/app/dbname.db` | the absolute file at that path | Production. Point it at the host's persistent volume. |
+| `:memory:` | per-process in-memory DB | Per-test fixtures only — contents vanish at process exit. |
+
+So the three full URLs are:
+
+```bash
+sqlite+aiosqlite:///./dbname.db
+sqlite+aiosqlite:////var/lib/app/dbname.db
+sqlite+aiosqlite:///:memory:
+```
+
+The absolute form looks like it has four slashes, but it's the same
+three-slash prefix as the others — the fourth slash is the leading
+`/` of the absolute path. This is the single most common SQLite-URL
+paper-cut.
+
+Both file forms create the file on first connection, so a fresh
+checkout running `uv run regstack init && uv run uvicorn …` works
+with no `mkdir` or `touch` step.
+
 ## JWT
 
 ```{list-table}
@@ -234,14 +271,14 @@ The active backend exposes the same five repository protocols on
 ```toml
 [email]
 backend = "console"             # console | smtp | ses
-from_address = "noreply@…"
-from_name    = "MyApp"
+from_address = "noreply@app.example.com"
+from_name    = "Example App"
 
 # smtp
-smtp_host = "smtp.example.com"
+smtp_host = "smtp.app.example.com"
 smtp_port = 587
 smtp_starttls = true
-smtp_username = "myapp"
+smtp_username = "<username>"
 # smtp_password is a SecretStr — set via REGSTACK_EMAIL__SMTP_PASSWORD
 
 # ses