regstack 0.2.0__tar.gz → 0.2.2__tar.gz

regstack-0.2.2/.github/workflows/test.yml

@@ -0,0 +1,147 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    services:
+      mongodb:
+        image: mongo:7
+        ports:
+          - 27017:27017
+        options: >-
+          --health-cmd "mongosh --quiet --eval 'db.runCommand({ping:1}).ok' --port 27017"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+          --health-start-period 10s
+      postgres:
+        image: postgres:16
+        ports:
+          - 5432:5432
+        env:
+          POSTGRES_USER: regstack
+          POSTGRES_PASSWORD: regstack
+          POSTGRES_DB: regstack
+        options: >-
+          --health-cmd "pg_isready -U regstack"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+          --health-start-period 10s
+    env:
+      # Drives the parametrized backend fixture in tests/conftest.py.
+      # Connect as superuser so the per-test fixture can CREATE/DROP DATABASE.
+      REGSTACK_TEST_POSTGRES_URL: postgresql+asyncpg://regstack:regstack@localhost:5432
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Pin Python ${{ matrix.python-version }}
+        run: uv python pin ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --extra dev
+
+      - name: ruff check
+        run: uv run ruff check src tests
+
+      - name: ruff format check
+        run: uv run ruff format --check src tests
+
+      - name: pytest (parallel, all backends)
+        run: uv run python -m pytest -n auto --tb=short
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - run: uv python pin 3.11
+      - run: uv sync --extra docs --extra dev
+      - run: uv run sphinx-build -b html -W --keep-going docs docs/_build/html
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html
+
+  base-install-smoketest:
+    # Catches the kind of regression that broke 0.2.0: an unconditional
+    # `from bson import ...` (or any other optional-extra import) at module
+    # top level makes `import regstack` fail for any user who didn't opt
+    # into the `mongo` extra. The unit test of the same name exercises the
+    # equivalent in-process via meta_path blocking; this job verifies the
+    # actual built wheel installs and imports against a clean Python.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - run: uv python pin 3.11
+      - name: Build wheel
+        run: uv build --wheel
+      - name: Install wheel into a clean venv (no extras)
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --upgrade pip
+          /tmp/smoke/bin/pip install dist/regstack-*.whl
+      - name: Import smoketest
+        run: |
+          /tmp/smoke/bin/python -c "
+          import regstack
+          from regstack import RegStack, RegStackConfig
+          assert RegStack.__module__ == 'regstack.app'
+          print('ok', regstack.__version__)
+          "
+      - name: SQLite end-to-end smoketest
+        run: |
+          /tmp/smoke/bin/python <<'PY'
+          import asyncio, secrets, tempfile
+          from pathlib import Path
+          from regstack import RegStack, RegStackConfig
+          from regstack.models.user import BaseUser
+
+          async def main() -> None:
+              with tempfile.TemporaryDirectory() as td:
+                  cfg = RegStackConfig.load(
+                      toml_path=Path("/dev/null"),
+                      secrets_env_path=Path("/dev/null"),
+                      jwt_secret=secrets.token_urlsafe(64),
+                      database_url=f"sqlite+aiosqlite:///{td}/rs.db",
+                      require_verification=False,
+                      allow_registration=True,
+                      rate_limit_disabled=True,
+                  )
+                  rs = RegStack(config=cfg)
+                  await rs.install_schema()
+                  user = await rs.users.create(
+                      BaseUser(email="a@b.com", hashed_password="h", is_verified=True)
+                  )
+                  assert user.id
+                  await rs.aclose()
+                  print("sqlite ok")
+
+          asyncio.run(main())
+          PY

{regstack-0.2.0 → regstack-0.2.2}/CHANGELOG.md

@@ -5,6 +5,27 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## 0.2.2 — 2026-04-28
+
+Docs-only release. The README and Sphinx docs landing page now lead
+with the same pitch (problem framing, "Why not just use…?" comparison
+vs Auth0 / Clerk / Keycloak / fastapi-users) before diving into
+architecture. Hyperlink density trimmed back: only major external
+packages, products, and JWT (RFC 7519) are linked — Wikipedia trivia,
+MDN basics, OWASP article links, and deep-dependency helper-class
+docs were removed.
+
+## 0.2.1 — 2026-04-28
+
+Hotfix for 0.2.0: `import regstack` failed on a base install because
+several modules in the import path (`models/_objectid.py`,
+`backends/protocols.py`, four routers, and the SQL `mfa_code_repo`)
+had unconditional `from bson …` / `from regstack.backends.mongo …`
+imports — but `pymongo` became an optional `mongo` extra in 0.2.0.
+Added a CI smoketest that builds the wheel and imports it in a
+no-extras venv, plus an in-process regression test that blocks `bson`
+/ `pymongo` via `sys.meta_path`.
+
 ## 0.2.0 — 2026-04-28
 
 Multi-backend support — SQLite (default), Postgres, MongoDB — switched

{regstack-0.2.0 → regstack-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -96,17 +96,15 @@ the admin panel, lock out brute-force attackers, and ideally a second
 factor. Every one of those endpoints has a well-known way to get
 subtly wrong:
 
-- **Password hashing.** Use [Argon2](https://en.wikipedia.org/wiki/Argon2)
-  (the [PHC winner](https://www.password-hashing.net/)), not MD5, SHA-1,
-  bcrypt-without-pepper, or — somehow still common — plain text.
+- **Password hashing.** Use Argon2id, not MD5, SHA-1, bcrypt-without-pepper,
+  or — somehow still common — plain text.
 - **Token revocation.** A [JWT](https://datatracker.ietf.org/doc/html/rfc7519)
   is signed and self-contained: the server can't "log it out" unless you
   build a revocation list. Forget this and a stolen token works until it
   expires.
 - **Account enumeration.** A login or password-reset endpoint that
   responds differently for "user exists" vs "user doesn't" lets an
-  attacker harvest your customer list. See
-  [OWASP WSTG-IDNT-04](https://owasp.org/www-project-web-security-testing-guide/v42/4-Web_Application_Security_Testing/03-Identity_Management_Testing/04-Testing_for_Account_Enumeration_and_Guessable_User_Account).
+  attacker harvest your customer list.
 - **Bulk session invalidation.** When a user changes their password
   because they think they were compromised, every existing token they
   hold should stop working immediately. Most homegrown JWT layers don't
@@ -115,9 +113,9 @@ subtly wrong:
   random, hashed at rest, single-use, and expire fast. Storing the raw
   token in the database is a "now your DB backup is also a credential
   dump" mistake.
-- **Phone numbers.** SMS codes need [E.164](https://en.wikipedia.org/wiki/E.164)-validated
-  numbers, attempt limits, and an upstream provider. Wiring all of that
-  yourself for a single feature is rarely worth it.
+- **Phone numbers.** SMS codes need E.164-validated numbers, attempt
+  limits, and an upstream provider. Wiring all of that yourself for a
+  single feature is rarely worth it.
 
 Doing all of these correctly, with tests, is two to four weeks of
 engineering for a competent team. Doing them once and embedding the
@@ -244,9 +242,9 @@ 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. The next tagged release is `v0.2.0`. See the
+suite. Latest tagged release: `v0.2.1`. See the
 [changelog](https://regstack.readthedocs.io/en/latest/changelog.html)
-for the per-milestone breakdown.
+for the per-release breakdown.
 
 ## Contributing
 

{regstack-0.2.0 → regstack-0.2.2}/README.md

@@ -32,17 +32,15 @@ the admin panel, lock out brute-force attackers, and ideally a second
 factor. Every one of those endpoints has a well-known way to get
 subtly wrong:
 
-- **Password hashing.** Use [Argon2](https://en.wikipedia.org/wiki/Argon2)
-  (the [PHC winner](https://www.password-hashing.net/)), not MD5, SHA-1,
-  bcrypt-without-pepper, or — somehow still common — plain text.
+- **Password hashing.** Use Argon2id, not MD5, SHA-1, bcrypt-without-pepper,
+  or — somehow still common — plain text.
 - **Token revocation.** A [JWT](https://datatracker.ietf.org/doc/html/rfc7519)
   is signed and self-contained: the server can't "log it out" unless you
   build a revocation list. Forget this and a stolen token works until it
   expires.
 - **Account enumeration.** A login or password-reset endpoint that
   responds differently for "user exists" vs "user doesn't" lets an
-  attacker harvest your customer list. See
-  [OWASP WSTG-IDNT-04](https://owasp.org/www-project-web-security-testing-guide/v42/4-Web_Application_Security_Testing/03-Identity_Management_Testing/04-Testing_for_Account_Enumeration_and_Guessable_User_Account).
+  attacker harvest your customer list.
 - **Bulk session invalidation.** When a user changes their password
   because they think they were compromised, every existing token they
   hold should stop working immediately. Most homegrown JWT layers don't
@@ -51,9 +49,9 @@ subtly wrong:
   random, hashed at rest, single-use, and expire fast. Storing the raw
   token in the database is a "now your DB backup is also a credential
   dump" mistake.
-- **Phone numbers.** SMS codes need [E.164](https://en.wikipedia.org/wiki/E.164)-validated
-  numbers, attempt limits, and an upstream provider. Wiring all of that
-  yourself for a single feature is rarely worth it.
+- **Phone numbers.** SMS codes need E.164-validated numbers, attempt
+  limits, and an upstream provider. Wiring all of that yourself for a
+  single feature is rarely worth it.
 
 Doing all of these correctly, with tests, is two to four weeks of
 engineering for a competent team. Doing them once and embedding the
@@ -180,9 +178,9 @@ 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. The next tagged release is `v0.2.0`. See the
+suite. Latest tagged release: `v0.2.1`. See the
 [changelog](https://regstack.readthedocs.io/en/latest/changelog.html)
-for the per-milestone breakdown.
+for the per-release breakdown.
 
 ## Contributing
 

{regstack-0.2.0 → regstack-0.2.2}/docs/architecture.md

@@ -5,10 +5,11 @@ who wants to embed it, extend it, or contribute to it. If you only
 want to use it, [Quickstart](quickstart.md) is shorter.
 
 regstack is a single embeddable façade — `RegStack` — that wires
-together storage, password and JWT primitives, an email service, an
-SMS service, a [hooks bus](#hooks), and a [FastAPI](https://fastapi.tiangolo.com/)
-router. Hosts construct one façade per application and mount its
-router(s) wherever they like.
+together storage, password and [JWT](https://datatracker.ietf.org/doc/html/rfc7519)
+primitives, an email service, an SMS service, a [hooks bus](#hooks),
+and a [FastAPI](https://fastapi.tiangolo.com/) router. Hosts
+construct one façade per application and mount its router(s) wherever
+they like.
 
 ```text
 ┌────────────────────────────────────────────────┐
@@ -36,10 +37,9 @@ router(s) wherever they like.
    └────────┘  └──────────┘  └──────────┘
 ```
 
-The pattern is the
-[façade pattern](https://en.wikipedia.org/wiki/Facade_pattern): one
-object that owns and exposes a coherent set of related sub-systems,
-so the host has a single import to learn.
+The pattern is the façade pattern: one object that owns and exposes
+a coherent set of related sub-systems, so the host has a single
+import to learn.
 
 ## One façade per process
 
@@ -48,8 +48,7 @@ sms_service=…, mail_composer=…)` is the only public constructor.
 Everything downstream (routers, dependencies, repos) takes its
 dependencies from this instance, so you can run **two regstack
 instances in the same process** without shared state — useful for
-[multi-tenant](https://en.wikipedia.org/wiki/Multitenancy) deployments
-where a single FastAPI app serves multiple
+multi-tenant deployments where a single FastAPI app serves multiple
 `<host, database, branding>` triples.
 
 The backend is auto-built from `config.database_url` if not supplied
@@ -64,9 +63,7 @@ The façade exposes:
 - `router` — the JSON `APIRouter` to mount under `config.api_prefix`.
 - `ui_router` — the SSR `APIRouter` (built on first access; only
   meaningful when `enable_ui_router=True`).
-- `static_files` — Starlette
-  [`StaticFiles`](https://www.starlette.io/staticfiles/) over the
-  bundled CSS/JS.
+- `static_files` — Starlette `StaticFiles` over the bundled CSS/JS.
 - `deps` — `AuthDependencies` factory for `current_user` /
   `current_admin` (each call returns a closure-bound dep).
 - `users`, `pending`, `blacklist`, `attempts`, `mfa_codes` — repos.
@@ -75,7 +72,7 @@ The façade exposes:
 - `backend` — the active `regstack.backends.base.Backend`.
 - `install_schema()` — install indexes (Mongo) or run
   [Alembic](https://alembic.sqlalchemy.org/) migrations (SQL).
-  `install_indexes()` is kept as a backwards-compat alias.
+  `install_indexes()` is kept as a back-compat alias.
 - `aclose()` — tear down the backend's connection pool.
 - `bootstrap_admin(email, password)`,
   `add_template_dir(path)`, `set_email_backend(...)`,
@@ -85,9 +82,8 @@ The façade exposes:
 
 The Backend ABC owns the persistence story. Each backend ships:
 
-- One concrete repository per
-  [Protocol](https://docs.python.org/3/library/typing.html#typing.Protocol):
-  `UserRepoProtocol`, `PendingRepoProtocol`, `BlacklistRepoProtocol`,
+- One concrete repository per Protocol: `UserRepoProtocol`,
+  `PendingRepoProtocol`, `BlacklistRepoProtocol`,
   `LoginAttemptRepoProtocol`, `MfaCodeRepoProtocol`.
 - `install_schema()` to create indexes (Mongo) or run table creation /
   Alembic migrations (SQL).
@@ -95,16 +91,15 @@ The Backend ABC owns the persistence story. Each backend ships:
 - `aclose()` for clean shutdown.
 
 The Mongo backend lives at `regstack.backends.mongo`; the SQL backend
-(driving both SQLite and Postgres via [SQLAlchemy 2 async](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html))
-lives at `regstack.backends.sql`. Both are routed via the
+(driving both SQLite and Postgres via [SQLAlchemy](https://www.sqlalchemy.org/)
+async) lives at `regstack.backends.sql`. Both are routed via the
 `regstack.backends.factory.build_backend(config)` factory.
 
 ### TTL handling differences
 
-Mongo gets free expiry via [TTL indexes](https://www.mongodb.com/docs/manual/core/index-ttl/) —
-`pending_registrations`, `token_blacklist`, `login_attempts`, and
-`mfa_codes` all have `expireAfterSeconds` indexes that the Mongo
-background task reaps.
+Mongo gets free expiry via TTL indexes — `pending_registrations`,
+`token_blacklist`, `login_attempts`, and `mfa_codes` all have
+`expireAfterSeconds` indexes that the Mongo background task reaps.
 
 The SQL backends have no equivalent. Two safety nets:
 
@@ -112,22 +107,21 @@ The SQL backends have no equivalent. Two safety nets:
   checks `expires_at > now()` (or equivalent). A stale row in the
   table is harmless because it's never returned.
 - **Periodic reaper**: each repo exposes `purge_expired(...)`. Hosts
-  that care about disk usage can run it on a schedule (e.g. via
-  [APScheduler](https://apscheduler.readthedocs.io/) or a
-  `regstack reap` cron job).
+  that care about disk usage can run it on a schedule (e.g. a cron
+  job calling a small `regstack reap` script).
 
 This means SQL backends are functionally correct without the reaper,
 but accumulate dead rows over time. Mongo doesn't.
 
 ## Repositories
 
-Each backend ships a thin async repo per collection / table. The Mongo
-repos are tz-aware because `make_client` configures
+Each backend ships a thin async repo per collection / table. The
+Mongo repos are tz-aware because `make_client` configures
 `AsyncMongoClient(..., tz_aware=True)`; the SQL repos use a custom
-`UtcDateTime` [TypeDecorator](https://docs.sqlalchemy.org/en/20/core/custom_types.html#sqlalchemy.types.TypeDecorator)
-that stores UTC and re-attaches the UTC tzinfo on read. Every layer
-above the repo assumes UTC-aware datetimes — there is no naive
-datetime anywhere in the public API.
+`UtcDateTime` SQLAlchemy `TypeDecorator` that stores UTC and
+re-attaches the UTC tzinfo on read. Every layer above the repo
+assumes UTC-aware datetimes — there is no naive datetime anywhere in
+the public API.
 
 `UserRepo` accepts an injected `Clock`; bulk-revoke writes
 (`update_password`, `update_email`, `set_tokens_invalidated_after`)
@@ -179,20 +173,18 @@ one mechanism:
 - `build_ui_environment` — SSR HTML templates under
   `regstack/ui/templates/`.
 
-Both wrap a
-[`ChoiceLoader([host_dirs..., regstack_default])`](https://jinja.palletsprojects.com/en/stable/api/#jinja2.ChoiceLoader)
-so a host override drops a same-named file into its template
-directory and wins over the bundled version.
-`RegStack.add_template_dir(path)` feeds both loaders simultaneously.
+Both wrap a `ChoiceLoader([host_dirs..., regstack_default])` so a
+host override drops a same-named file into its template directory and
+wins over the bundled version. `RegStack.add_template_dir(path)`
+feeds both loaders simultaneously.
 
 ## CLI runtime
 
 `regstack init`, `regstack create-admin`, and `regstack doctor` share
-`cli/_runtime.py`. `open_regstack(toml_path=None)` is an
-[async context manager](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager)
-that builds a real RegStack against a real backend, runs
-`install_schema()`, and tears the connection down on exit — the right
-pattern for a short-lived CLI invocation.
+`cli/_runtime.py`. `open_regstack(toml_path=None)` is an async
+context manager that builds a real RegStack against a real backend,
+runs `install_schema()`, and tears the connection down on exit — the
+right pattern for a short-lived CLI invocation.
 
 ## Testing seams
 
@@ -206,5 +198,4 @@ pattern for a short-lived CLI invocation.
   test build multiple `RegStack` instances against per-worker DBs to
   exercise different config combinations without leaking. The
   parametrized `backend_kind` fixture runs every integration test
-  against every active backend in parallel via
-  [`pytest-xdist`](https://pytest-xdist.readthedocs.io/).
+  against every active backend in parallel via pytest-xdist.

{regstack-0.2.0 → regstack-0.2.2}/docs/changelog.md

@@ -3,6 +3,61 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 0.2.2 — 2026-04-28
+
+**Docs-only release.**
+
+### Changed
+
+- README and `docs/index.md` both now lead with the same pitch — a
+  tagline ("Production-grade user accounts for your FastAPI app —
+  without the vendor lock-in, the second service to run, or the
+  homegrown auth bugs"), a "The problem regstack solves" section
+  (Argon2, JWT revocation, account enumeration, bulk session
+  invalidation, hashed one-time tokens, E.164 phone numbers), and a
+  "Why not just use…?" comparison table covering hosted SaaS
+  (Auth0 / Clerk / WorkOS / Stytch), self-hosted IAM (Keycloak /
+  Authentik / Authelia / Ory Kratos), `fastapi-users`, and DIY.
+- Trimmed hyperlink density back. Only major external packages,
+  products, and JWT (RFC 7519) are linked. Wikipedia articles on
+  CS concepts (façade pattern, multitenancy, idempotence, E.164,
+  SHA-256, HMAC), MDN web platform basics (CSP, fetch, localStorage,
+  HTTP 429, Retry-After, HTTPS, CSS custom properties), OWASP article
+  links, Python stdlib pages, and deep-dependency helper-class docs
+  (pwdlib, pydantic, asyncpg, pymongo, ChoiceLoader, TypeDecorator,
+  StaticFiles, ProxyHeadersMiddleware, slowapi, APScheduler,
+  pytest-xdist, Kubernetes probes) were removed.
+
+## 0.2.1 — 2026-04-28
+
+**Hotfix for 0.2.0.** `import regstack` was broken on any install that
+didn't include the new `mongo` extra: `models/_objectid.py` imported
+`bson` unconditionally, and four routers + the SQL MFA repo imported
+shared error / enum types out of `regstack.backends.mongo.*`, which
+in turn imports `pymongo` at module top level.
+
+### Fixed
+
+- `models/_objectid.py` now imports `bson.ObjectId` lazily inside a
+  `try / except ImportError` and only uses it for `isinstance` checks
+  when present.
+- `UserAlreadyExistsError`, `PendingAlreadyExistsError`,
+  `MfaVerifyOutcome`, and `MfaVerifyResult` moved from their backend
+  modules to `regstack.backends.protocols` (the backend-agnostic
+  location). Mongo modules re-export them for backwards compatibility.
+- All consumer modules (`routers/register.py`, `routers/account.py`,
+  `routers/login.py`, `routers/phone.py`, the SQL MFA repo) updated to
+  import from `regstack.backends.protocols`.
+
+### Added
+
+- New `base-install-smoketest` CI job: builds the wheel and runs
+  `import regstack` + a SQLite end-to-end RegStack lifecycle in a
+  fresh venv with **no extras**. Will catch any future regression.
+- New `tests/unit/test_base_install_imports.py` regression test that
+  uses `sys.meta_path` to block `bson` / `pymongo` and confirm
+  `import regstack` still succeeds.
+
 ## 0.2.0 — 2026-04-28
 
 **Multi-backend support + Alembic migrations.** SQLite is now the

{regstack-0.2.0 → regstack-0.2.2}/docs/embedding.md

@@ -110,9 +110,8 @@ regstack.add_template_dir(Path("/app/host/templates"))
 ```
 
 Drop a same-named file into your directory to win against the bundled
-default — regstack uses Jinja2's
-[`ChoiceLoader`](https://jinja.palletsprojects.com/en/stable/api/#jinja2.ChoiceLoader)
-so the host directory is searched first. Examples:
+default — regstack uses Jinja2's `ChoiceLoader` so the host directory
+is searched first. Examples:
 
 - `auth/login.html` — replaces the SSR sign-in page.
 - `verification.html` / `verification.txt` /
@@ -125,8 +124,8 @@ A list of every overridable file lives in
 ## Switching the SSR theme without templates
 
 If you only want to flip colors / fonts, you don't need to override
-any templates — just supply a CSS file that overrides the
-[CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*):
+any templates — just supply a CSS file that overrides the bundled
+CSS custom properties:
 
 ```toml
 # regstack.toml
@@ -171,8 +170,8 @@ In code:
 await regstack.bootstrap_admin("admin@example.com", "long-strong-password")
 ```
 
-This is [idempotent](https://en.wikipedia.org/wiki/Idempotence) —
-promotes an existing user, creates one if not present.
+This is idempotent — promotes an existing user, creates one if not
+present.
 
 ## Health-check and probes
 
@@ -183,16 +182,14 @@ uv run regstack doctor [--config ...] [--check-dns] [--send-test-email <addr>]
 `doctor` reports JWT secret strength, database reachability, indexes,
 the email backend's instantiability, and optionally DNS (SPF/DKIM/MX)
 and a real email send. Exit code is the number of failed checks —
-wire it into a container health check or a
-[Kubernetes liveness probe](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
+wire it into a container health check or a Kubernetes liveness probe
 for production probes that need more than a TCP hit.
 
 ## What regstack does *not* do
 
-- It does not mount a [CSRF](https://owasp.org/www-community/attacks/csrf)
-  middleware. The bundled SSR pages don't use cookies, so they don't
-  need it; if you swap the bundled JS for a cookie-based variant,
-  configure CSRF at the host.
+- It does not mount a CSRF middleware. The bundled SSR pages don't
+  use cookies, so they don't need it; if you swap the bundled JS for
+  a cookie-based variant, configure CSRF at the host.
 - It does not enforce HTTPS. Run behind a TLS terminator.
 - It does not provision SES identities, Route 53 records, IAM users,
   or anything else outside the database.