regstack 0.2.1__tar.gz → 0.2.3__tar.gz

{regstack-0.2.1 → regstack-0.2.3}/CHANGELOG.md

@@ -5,6 +5,26 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## 0.2.3 — 2026-04-28
+
+Docs-only release. Restructured the API reference around the current
+package layout (post multi-backend refactor) and added Google-style
+docstrings (Args / Returns / Raises) to the public surface — RegStack,
+JwtCodec, PasswordHasher, LockoutService, AuthDependencies,
+HookRegistry, EmailService, SmsService, the router builders, and the
+Clock implementations. Dataclass field docs moved to PEP 258
+attribute docstrings. Sphinx builds clean under `-W` again.
+
+## 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

{regstack-0.2.1 → regstack-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.2.1
+Version: 0.2.3
 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.1 → regstack-0.2.3}/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.3/docs/api.md

@@ -0,0 +1,278 @@
+# API reference
+
+Auto-generated from docstrings. The most useful entry point is
+[`regstack.RegStack`](#regstack.app.RegStack); everything else hangs
+off it.
+
+This page is organized by what you'd reach for, not by package
+hierarchy. Each section starts with a one-paragraph orientation,
+then the ``autoclass`` / ``autofunction`` directives pull the
+docstrings, signatures, and parameter docs straight off the package
+source.
+
+## Top-level
+
+The handful of things you import from `regstack` directly:
+
+- [`RegStack`](#regstack.app.RegStack) — the embeddable façade.
+- [`RegStackConfig`](#regstack.config.schema.RegStackConfig) — top-level config.
+- [`EmailConfig`](#regstack.config.schema.EmailConfig) — email-backend sub-config.
+- [`SmsConfig`](#regstack.config.schema.SmsConfig) — SMS-backend sub-config.
+
+Most embeddings need only `RegStack` and `RegStackConfig`.
+
+## Façade
+
+`RegStack` is the embeddable façade. One per FastAPI application;
+hosts mount its `router` and (optionally) `ui_router`. All collaborators
+— password hasher, JWT codec, repos, hooks bus, email and SMS
+services — hang off the instance.
+
+```{eval-rst}
+.. autoclass:: regstack.app.RegStack
+   :members:
+   :show-inheritance:
+```
+
+## Configuration
+
+`RegStackConfig` is a `pydantic-settings` model loaded from
+environment variables (`REGSTACK_*`), an optional
+`regstack.secrets.env`, an optional `regstack.toml`, and programmatic
+kwargs — in that priority order. See the
+[Configuration guide](configuration.md) for every field with its
+default.
+
+```{eval-rst}
+.. autoclass:: regstack.config.schema.RegStackConfig
+   :members:
+   :show-inheritance:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.config.schema.EmailConfig
+   :members:
+   :show-inheritance:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.config.schema.SmsConfig
+   :members:
+   :show-inheritance:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autofunction:: regstack.config.loader.load_config
+```
+
+## Auth primitives
+
+The pieces that make authentication work: password hashing (Argon2id),
+JWT issuance and validation with per-purpose derived keys, login
+lockout, and the FastAPI dependency factory. Hosts rarely instantiate
+these directly — they're built and wired by the `RegStack` constructor
+— but the docstrings on the public methods explain the contract.
+
+```{eval-rst}
+.. autoclass:: regstack.auth.password.PasswordHasher
+   :members:
+
+.. autoclass:: regstack.auth.jwt.JwtCodec
+   :members:
+
+.. autoclass:: regstack.auth.jwt.TokenPayload
+   :members:
+
+.. autoexception:: regstack.auth.jwt.TokenError
+
+.. autofunction:: regstack.auth.jwt.is_payload_bulk_revoked
+
+.. autoclass:: regstack.auth.lockout.LockoutService
+   :members:
+
+.. autoclass:: regstack.auth.lockout.LockoutDecision
+   :members:
+
+.. autoclass:: regstack.auth.dependencies.AuthDependencies
+   :members:
+```
+
+### Time
+
+Every time-sensitive operation reads `now()` through a `Clock`. Tests
+inject `FrozenClock` to make assertions deterministic.
+
+```{eval-rst}
+.. autoclass:: regstack.auth.clock.Clock
+   :members:
+
+.. autoclass:: regstack.auth.clock.SystemClock
+   :members:
+
+.. autoclass:: regstack.auth.clock.FrozenClock
+   :members:
+```
+
+## Backends
+
+regstack ships three storage backends behind one set of `Protocol`
+classes: SQLite (default, no infrastructure), PostgreSQL, and MongoDB.
+The active backend is auto-built from `config.database_url`'s URL
+scheme via `build_backend`. Hosts that need to share a connection pool
+with their own application can pass an explicit `Backend` to the
+`RegStack` constructor.
+
+```{eval-rst}
+.. autoclass:: regstack.backends.base.Backend
+   :members:
+   :show-inheritance:
+
+.. autoclass:: regstack.backends.base.BackendKind
+   :members:
+
+.. autofunction:: regstack.backends.factory.build_backend
+
+.. autoclass:: regstack.backends.mongo.MongoBackend
+   :members:
+   :show-inheritance:
+
+.. autoclass:: regstack.backends.sql.SqlBackend
+   :members:
+   :show-inheritance:
+```
+
+### Repository protocols
+
+The five repository protocols are the contract every backend
+implements. Routers and services depend only on these — switching
+backends is a wiring change, not a code change.
+
+```{eval-rst}
+.. autoclass:: regstack.backends.protocols.UserRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.PendingRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.BlacklistRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.LoginAttemptRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.MfaCodeRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.MfaVerifyOutcome
+   :members:
+
+.. autoclass:: regstack.backends.protocols.MfaVerifyResult
+   :members:
+
+.. autoexception:: regstack.backends.protocols.UserAlreadyExistsError
+
+.. autoexception:: regstack.backends.protocols.PendingAlreadyExistsError
+```
+
+## Models
+
+The persisted data shapes. `BaseUser` is the canonical user document;
+`UserCreate` validates registration input; `UserPublic` is what the
+API returns (omits the password hash). The other models drive
+verification, lockout, and SMS MFA.
+
+```{eval-rst}
+.. autoclass:: regstack.models.user.BaseUser
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.user.UserCreate
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.user.UserPublic
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.pending_registration.PendingRegistration
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.login_attempt.LoginAttempt
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.mfa_code.MfaCode
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+```
+
+## Email + SMS
+
+Pluggable transports for the verification / reset / change-email
+emails and the SMS MFA codes. Implement `EmailService` or `SmsService`
+to plug in a provider that isn't bundled (Postmark, SendGrid,
+MessageBird, …) and pass the instance to `regstack.set_email_backend`
+/ `set_sms_backend`.
+
+### Email
+
+```{eval-rst}
+.. autoclass:: regstack.email.base.EmailMessage
+   :members:
+
+.. autoclass:: regstack.email.base.EmailService
+   :members:
+
+.. autoclass:: regstack.email.console.ConsoleEmailService
+   :members:
+
+.. autoclass:: regstack.email.composer.MailComposer
+   :members:
+
+.. autofunction:: regstack.email.factory.build_email_service
+```
+
+### SMS
+
+```{eval-rst}
+.. autoclass:: regstack.sms.base.SmsMessage
+   :members:
+
+.. autoclass:: regstack.sms.base.SmsService
+   :members:
+
+.. autofunction:: regstack.sms.base.is_valid_e164
+
+.. autoclass:: regstack.sms.null.NullSmsService
+   :members:
+
+.. autofunction:: regstack.sms.factory.build_sms_service
+```
+
+## Hooks
+
+The event bus regstack uses to fire side-effect notifications
+(`user_registered`, `password_changed`, etc.) without coupling auth
+code to host concerns like CRMs or analytics. See the
+[Embedding guide](embedding.md#subscribing-to-events) for examples.
+
+```{eval-rst}
+.. autoclass:: regstack.hooks.events.HookRegistry
+   :members:
+
+.. autodata:: regstack.hooks.events.KNOWN_EVENTS
+```
+
+## Routers
+
+Hosts normally access these via the `regstack.router` and
+`regstack.ui_router` properties; the builder functions are public for
+hosts that want to compose differently.
+
+```{eval-rst}
+.. autofunction:: regstack.routers.build_router
+
+.. autofunction:: regstack.ui.pages.build_ui_router
+
+.. autofunction:: regstack.ui.pages.build_ui_environment
+
+.. autofunction:: regstack.ui.pages.default_static_dir
+```

{regstack-0.2.1 → regstack-0.2.3}/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.1 → regstack-0.2.3}/docs/changelog.md

@@ -3,6 +3,59 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 0.2.3 — 2026-04-28
+
+**Docs-only release.** API reference rewritten around the current
+package layout, public surface gained proper Google-style docstrings.
+
+### Changed
+
+- ``docs/api.md`` restructured around the post-multi-backend package
+  layout (``regstack.backends.{base,protocols,factory,mongo,sql}`` and
+  friends). Each section now opens with a one-paragraph orientation
+  before the autodoc directives. The pre-refactor
+  ``regstack.db.repositories.*`` references that rendered empty are
+  gone.
+- Added Google-style docstrings (purpose summary + Args / Returns /
+  Raises) to the most-touched public methods on ``RegStack``,
+  ``JwtCodec``, ``PasswordHasher``, ``LockoutService``,
+  ``AuthDependencies``, ``HookRegistry``, ``EmailService``,
+  ``SmsService``, ``build_router``, ``build_ui_router``,
+  ``build_ui_environment``, ``default_static_dir``, ``Clock`` /
+  ``SystemClock`` / ``FrozenClock``.
+- Dataclass field documentation moved to PEP 258 attribute docstrings
+  on ``TokenPayload``, ``LockoutDecision``, ``EmailMessage``,
+  ``SmsMessage``, ``MfaVerifyResult`` — autodoc now renders each field
+  with its description without the "duplicate object description"
+  warnings the napoleon ``Attributes:`` block was triggering.
+- ``MfaVerifyOutcome`` enum docstring reformatted as a bullet list
+  (the napoleon ``Members:`` block isn't a recognised section).
+
+## 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

{regstack-0.2.1 → regstack-0.2.3}/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.