regstack 0.3.0__tar.gz → 0.5.0__tar.gz

{regstack-0.3.0 → regstack-0.5.0}/CLAUDE.md

@@ -60,8 +60,37 @@ The full plan, including milestone scope and deferred items, lives at
   Phone setup uses a separate signed `phone_setup` JWT carrying the
   proposed phone as a custom claim — same per-purpose key derivation as
   password-reset and email-change.
-- **OAuth** — explicitly deferred. The `oauth/` package will hold a provider
-  ABC only; concrete providers (Google first) come post-v1.
+- **OAuth — done (0.3.0).** `OAuthProvider` ABC + `OAuthRegistry`,
+  Google provider (Authorization Code with PKCE, ID-token verification
+  via `pyjwt[crypto]` + `PyJWKClient`), 5 JSON endpoints,
+  `/account/oauth-complete` SSR token-handoff page, "Sign in with
+  Google" button on `/account/login`, Connected-accounts panel on
+  `/account/me`. Optional extra: `oauth = ["pyjwt[crypto]>=2.8"]`.
+- **OAuth setup wizard — done.** `regstack oauth setup` opens a native
+  pywebview window over a 127.0.0.1 FastAPI server (random port +
+  one-shot launch token). 12-step SPA, per-step server validation,
+  non-clobbering tomlkit merge into `regstack.toml` +
+  `regstack.secrets.env`. Lives in `src/regstack/wizard/oauth_google/`;
+  Click subcommand registered through a `_LazyOauthGroup` so
+  `regstack init` / `doctor` don't pay the pywebview/uvicorn import
+  cost. `--print-only` mode runs the same merge headlessly. Tested 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.3.0 → regstack-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.3.0
+Version: 0.5.0
 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
@@ -29,7 +29,10 @@ 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: pywebview>=5.0
 Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: uvicorn[standard]>=0.29
 Provides-Extra: dev
 Requires-Dist: anyio>=4.3; extra == 'dev'
 Requires-Dist: asyncpg>=0.29; extra == 'dev'
@@ -40,6 +43,7 @@ Requires-Dist: pyjwt[crypto]>=2.8; 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'
+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'
@@ -78,9 +82,9 @@ auth bugs.**
 
 `pip install regstack`, point it at SQLite (default), [PostgreSQL](https://www.postgresql.org/),
 or [MongoDB](https://www.mongodb.com/), and you have register / login /
-verify-email / reset-password / change-email / delete-account / optional SMS
-two-factor / admin endpoints / themable HTML pages — all behind a small Python
-API and one config file.
+verify-email / reset-password / change-email / delete-account / Sign in
+with Google / optional SMS two-factor / admin endpoints / themable
+HTML pages — all behind a small Python API and one config file.
 
 📚 **Docs:** <https://regstack.readthedocs.io>
 &nbsp;·&nbsp;
@@ -132,13 +136,14 @@ result everywhere is what regstack is for.
 ✔ Forgot / reset password — anti-enumeration: identical responses
 ✔ Change password (revokes old tokens) / change email (re-verify)
 ✔ Delete account
+✔ Sign in with Google (PKCE + ID-token verification, opt-in)
 ✔ Optional SMS two-factor (TOTP-style 6-digit codes over SMS)
 ✔ Server-side login lockout (HTTP 429 + Retry-After)
 ✔ Admin endpoints (list / disable / delete users, stats)
 ✔ 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
 ```
 
@@ -181,7 +186,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
@@ -245,7 +250,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. Latest tagged release: `v0.2.1`. See the
+suite. OAuth (Google) shipped in `v0.3.0`; the `regstack oauth setup`
+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.3.0 → regstack-0.5.0}/README.md

@@ -11,9 +11,9 @@ auth bugs.**
 
 `pip install regstack`, point it at SQLite (default), [PostgreSQL](https://www.postgresql.org/),
 or [MongoDB](https://www.mongodb.com/), and you have register / login /
-verify-email / reset-password / change-email / delete-account / optional SMS
-two-factor / admin endpoints / themable HTML pages — all behind a small Python
-API and one config file.
+verify-email / reset-password / change-email / delete-account / Sign in
+with Google / optional SMS two-factor / admin endpoints / themable
+HTML pages — all behind a small Python API and one config file.
 
 📚 **Docs:** <https://regstack.readthedocs.io>
 &nbsp;·&nbsp;
@@ -65,13 +65,14 @@ result everywhere is what regstack is for.
 ✔ Forgot / reset password — anti-enumeration: identical responses
 ✔ Change password (revokes old tokens) / change email (re-verify)
 ✔ Delete account
+✔ Sign in with Google (PKCE + ID-token verification, opt-in)
 ✔ Optional SMS two-factor (TOTP-style 6-digit codes over SMS)
 ✔ Server-side login lockout (HTTP 429 + Retry-After)
 ✔ Admin endpoints (list / disable / delete users, stats)
 ✔ 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
 ```
 
@@ -114,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
@@ -178,7 +179,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. Latest tagged release: `v0.2.1`. See the
+suite. OAuth (Google) shipped in `v0.3.0`; the `regstack oauth setup`
+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.3.0 → regstack-0.5.0}/docs/api.md

@@ -18,6 +18,7 @@ The handful of things you import from `regstack` directly:
 - [`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.
+- [`OAuthConfig`](#regstack.config.schema.OAuthConfig) — OAuth provider sub-config.
 
 Most embeddings need only `RegStack` and `RegStackConfig`.
 
@@ -59,6 +60,11 @@ default.
    :show-inheritance:
    :exclude-members: model_config, model_fields, model_computed_fields
 
+.. autoclass:: regstack.config.schema.OAuthConfig
+   :members:
+   :show-inheritance:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
 .. autofunction:: regstack.config.loader.load_config
 ```
 
@@ -247,6 +253,73 @@ MessageBird, …) and pass the instance to `regstack.set_email_backend`
 .. autofunction:: regstack.sms.factory.build_sms_service
 ```
 
+## OAuth
+
+Opt-in subsystem behind `enable_oauth` and the `oauth` extra. v1
+ships Google; the abstraction is shaped so adding GitHub /
+Microsoft / Apple later is a new module under
+`regstack.oauth.providers` plus a registry entry. The full host
+guide is in [OAuth](oauth.md); the threat model is in
+[Security model](security.md#oauth-sign-in-with-google).
+
+### Provider abstraction
+
+```{eval-rst}
+.. autoclass:: regstack.oauth.base.OAuthProvider
+   :members:
+
+.. autoclass:: regstack.oauth.base.OAuthTokens
+   :members:
+
+.. autoclass:: regstack.oauth.base.OAuthUserInfo
+   :members:
+
+.. autoclass:: regstack.oauth.registry.OAuthRegistry
+   :members:
+
+.. autoexception:: regstack.oauth.errors.OAuthError
+
+.. autoexception:: regstack.oauth.errors.OAuthConfigError
+
+.. autoexception:: regstack.oauth.errors.OAuthTokenExchangeError
+
+.. autoexception:: regstack.oauth.errors.OAuthIdTokenError
+```
+
+### Google provider
+
+```{eval-rst}
+.. autoclass:: regstack.oauth.providers.google.GoogleProvider
+   :members:
+   :show-inheritance:
+```
+
+### Identity + state storage
+
+```{eval-rst}
+.. autoclass:: regstack.models.oauth_identity.OAuthIdentity
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.models.oauth_state.OAuthState
+   :members:
+   :exclude-members: model_config, model_fields, model_computed_fields
+
+.. autoclass:: regstack.backends.protocols.OAuthIdentityRepoProtocol
+   :members:
+
+.. autoclass:: regstack.backends.protocols.OAuthStateRepoProtocol
+   :members:
+
+.. autoexception:: regstack.backends.protocols.OAuthIdentityAlreadyLinkedError
+```
+
+### Router
+
+```{eval-rst}
+.. autofunction:: regstack.routers.oauth.build_oauth_router
+```
+
 ## Hooks
 
 The event bus regstack uses to fire side-effect notifications

{regstack-0.3.0 → regstack-0.5.0}/docs/architecture.md

@@ -139,8 +139,52 @@ The composite `router` conditionally includes:
 - `password` (forgot/reset) — when `enable_password_reset`.
 - `phone` and the `mfa-confirm` route — when `enable_sms_2fa`.
 - `admin` — when `enable_admin_router`.
-
-`ui_router` mounts the same conditional pages.
+- `oauth` — when `enable_oauth` AND at least one provider is
+  registered on `rs.oauth`.
+
+`ui_router` mounts the same conditional pages, plus
+`/account/oauth-complete` when `enable_oauth` is on.
+
+## OAuth subsystem
+
+Opt-in. Lives in `regstack.oauth/`; hosts pull it in via the
+`oauth` extra (`pyjwt[crypto]>=2.8`). Imports are lazy — the
+package keeps importing on a base install with no `cryptography`
+installed, and the OAuth-specific modules only get loaded when
+`enable_oauth` is on.
+
+The shape is:
+
+- `OAuthProvider` ABC — three methods: `authorization_url`,
+  `exchange_code`, `verify_id_token`.
+- `OAuthRegistry` — name-keyed map of providers, scoped to one
+  `RegStack` instance. The `RegStack` constructor reads
+  `config.oauth` and registers `GoogleProvider` automatically when
+  `enable_oauth` and the credentials are set; hosts can also
+  register custom providers post-construction.
+- `GoogleProvider` — Authorization Code with PKCE, ID-token
+  verification via `pyjwt[crypto]` + `PyJWKClient` against Google's
+  JWKS. ~150 lines hand-rolled rather than pulling `authlib`.
+- Two new repos via the protocol pattern:
+  `OAuthIdentityRepoProtocol` (links between regstack users and
+  external accounts; double-unique on `(provider, subject_id)` and
+  `(user_id, provider)`) and `OAuthStateRepoProtocol` (in-flight
+  state rows carrying the PKCE `code_verifier`, redirect target,
+  mode, and the `result_token` slot the SPA exchanges).
+- `build_oauth_router(rs)` — the router with the five endpoints
+  (`/start`, `/callback`, `/exchange`, `/link/start`, `/link`) plus
+  `/oauth/providers` for the SSR connected-accounts panel.
+
+The token-handoff round-trip avoids putting access tokens in URLs:
+the callback stashes the freshly-minted session JWT on the state
+row's `result_token`, redirects to `/account/oauth-complete?id=…`,
+and the SPA POSTs that id back to `/oauth/exchange` to retrieve the
+token. The exchange consumes the row atomically — the same id can't
+be exchanged twice.
+
+The full design (including the four-milestone build sequence and
+the threat model) is in
+[`tasks/oauth-design.md`](https://github.com/jdrumgoole/regstack/blob/main/tasks/oauth-design.md).
 
 ## Hooks
 
@@ -157,6 +201,8 @@ primary auth flow. Known events:
 - `phone_setup_started` / `mfa_login_started`
 - `mfa_enabled` / `mfa_disabled`
 - `user_deleted`
+- `oauth_signin_started` / `oauth_signin_completed`
+- `oauth_account_linked` / `oauth_account_unlinked`
 
 Hosts are free to subscribe to custom event names too — the registry
 is just a `defaultdict(list)`. Use this surface to push events into

{regstack-0.3.0 → regstack-0.5.0}/docs/changelog.md

@@ -3,6 +3,51 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 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
+
+- **OAuth setup wizard.** `regstack oauth setup` opens a native
+  webview window that walks an operator through registering a Google
+  OAuth 2.0 client and merges the credentials into `regstack.toml` +
+  `regstack.secrets.env` non-destructively (preserves comments, other
+  tables, unrelated keys). 12-step SPA inside a local-only
+  127.0.0.1 FastAPI server, gated by a per-launch random token. Each
+  Next click hits a server-side validator so the Write step can never
+  be reached with bad data. `--print-only` mode skips the GUI for
+  headless / CI use.
+- Three new base dependencies: `pywebview>=5.0`, `tomlkit>=0.13`,
+  `uvicorn[standard]>=0.29` (the wizard's local server).
+- `pytest-playwright` added to the `dev` extra; new `inv test-e2e`
+  task chained into `inv test-all`.
+
 ## 0.3.0 — 2026-04-30
 
 **OAuth — Sign in with Google.** Built across four PRs (M1–M4 of

regstack-0.5.0/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.3.0 → regstack-0.5.0}/docs/conf.py

@@ -38,7 +38,14 @@ extensions = [
 source_suffix = {".md": "markdown", ".rst": "restructuredtext"}
 master_doc = "index"
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    # Daily security review reports — these are GitHub-rendered
+    # markdown, not part of the published Sphinx site.
+    "security-reports/**",
+]
 
 # Suppress noisy autodoc warnings on dynamically-typed pydantic helpers.
 suppress_warnings = ["autodoc.import_object"]

{regstack-0.3.0 → regstack-0.5.0}/docs/configuration.md

@@ -63,6 +63,12 @@ addressed in env using a `__` separator: `REGSTACK_EMAIL__FROM_ADDRESS`.
 * - `mfa_code_collection`
   - `"mfa_codes"`
   -
+* - `oauth_identity_collection`
+  - `"oauth_identities"`
+  -
+* - `oauth_state_collection`
+  - `"oauth_states"`
+  -
 ```
 
 ## Backends
@@ -79,15 +85,16 @@ regstack picks a backend at construction time from the URL scheme of
   - Notes
 
 * - SQLite
-  - `sqlite+aiosqlite:///./path.db`
+  - `sqlite+aiosqlite:///./dbname.db`
   - Default. Bundled in the base install — no extras needed.
     `:memory:` works too (per-test).
 * - 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.
 ```
@@ -165,7 +172,9 @@ The active backend exposes the same five repository protocols on
   - Mounts `/phone/*` routes and gates the MFA second step in `/login`.
 * - `enable_oauth`
   - `false`
-  - Reserved. No providers ship in v1.
+  - Mounts `/oauth/*` routes when at least one provider is registered
+    (currently Google). Requires the ``oauth`` extra
+    (``pip install 'regstack[oauth]'``).
 ```
 
 ## Lockout (login)
@@ -226,14 +235,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
@@ -256,6 +265,31 @@ twilio_account_sid = "AC…"
 # twilio_auth_token via REGSTACK_SMS__TWILIO_AUTH_TOKEN
 ```
 
+`[oauth]` (`OAuthConfig`):
+
+```toml
+[oauth]
+google_client_id = "12345.apps.googleusercontent.com"
+# google_client_secret via REGSTACK_OAUTH__GOOGLE_CLIENT_SECRET
+# google_redirect_uri = "https://your.app/api/auth/oauth/google/callback"
+#                       (default: f"{base_url}{api_prefix}/oauth/google/callback")
+
+# Account-linking policy. Off by default — see docs/oauth.md and
+# docs/security.md for the threat model. On = a Google sign-in for an
+# existing email-registered user is auto-linked when Google's
+# email_verified=true. Hosts choosing on are accepting the email-
+# recycling-at-the-provider risk in exchange for less friction.
+auto_link_verified_emails = false
+
+# When true, an OAuth sign-in for a user with SMS MFA enabled still
+# goes through the second-factor step. Off by default — the OAuth
+# provider already authenticated the human.
+enforce_mfa_on_oauth_signin = false
+
+state_ttl_seconds = 300        # in-flight state row lifetime
+completion_ttl_seconds = 30    # /oauth/exchange window after callback
+```
+
 ## SSR / theming
 
 ```{list-table}