regstack 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -60,8 +60,23 @@ 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.
 
 ## Three kinds of single-use proof
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.3.0
+Version: 0.4.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,6 +136,7 @@ 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)
@@ -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 shipped in `v0.4.0`. Latest tagged release: `v0.4.0`.
+See the
 [changelog](https://regstack.readthedocs.io/en/latest/changelog.html)
 for the per-release breakdown.
 

{regstack-0.3.0 → regstack-0.4.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,6 +65,7 @@ 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)
@@ -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 shipped in `v0.4.0`. Latest tagged release: `v0.4.0`.
+See the
 [changelog](https://regstack.readthedocs.io/en/latest/changelog.html)
 for the per-release breakdown.
 

{regstack-0.3.0 → regstack-0.4.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.4.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.4.0}/docs/changelog.md

@@ -3,6 +3,24 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 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.3.0 → regstack-0.4.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.4.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
@@ -165,7 +171,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)
@@ -256,6 +264,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}

{regstack-0.3.0 → regstack-0.4.0}/docs/embedding.md

@@ -54,11 +54,22 @@ async def _send_to_crm(user) -> None:
 @regstack.on("user_deleted")
 async def _purge_host_data(user) -> None:
     await my_app.delete_all_data_for(user.id)
+
+
+@regstack.on("oauth_signin_completed")
+async def _track_signin(*, user, provider, mode, was_new) -> None:
+    if was_new:
+        await analytics.track("signup", {"user": user.id, "provider": provider})
+    else:
+        await analytics.track("login", {"user": user.id, "provider": provider})
 ```
 
 Handlers can be sync or async. Exceptions are logged but never break
 the primary auth flow — see [`HookRegistry`](architecture.md#hooks).
-The full event list is in the architecture guide.
+The full event list (including the four OAuth events:
+``oauth_signin_started``, ``oauth_signin_completed``,
+``oauth_account_linked``, ``oauth_account_unlinked``) is in the
+architecture guide.
 
 ## Custom email or SMS backends
 
@@ -101,6 +112,48 @@ regstack.set_email_backend(PostmarkEmailService(server_token=os.environ["POSTMAR
 The same pattern applies for SMS via `SmsService` and
 `set_sms_backend(...)`.
 
+## Enabling OAuth
+
+Install the extra and configure a provider:
+
+```bash
+uv add 'regstack[oauth]'
+```
+
+```toml
+# regstack.toml
+enable_oauth = true
+
+[oauth]
+google_client_id = "12345.apps.googleusercontent.com"
+# google_client_secret in regstack.secrets.env
+auto_link_verified_emails = false  # security default — see oauth.md
+```
+
+The router mounts five JSON endpoints under `/oauth/` (start /
+callback / exchange / link-start / unlink) plus a `/oauth/providers`
+list. The bundled SSR pages pick up the rest automatically: a
+"Sign in with Google" button on `/account/login` and a Connected-
+accounts panel on `/account/me`.
+
+Hosts that need a custom provider (Apple, Microsoft, an internal
+OIDC) can register one programmatically on the registry:
+
+```python
+rs.oauth.register(MyCustomProvider(...))
+```
+
+Anything implementing :class:`~regstack.oauth.base.OAuthProvider`
+works — three abstract methods (`authorization_url`,
+`exchange_code`, `verify_id_token`). The router parametrizes its
+URL paths on the provider name, so a registered provider named
+``"github"`` is reachable at `/oauth/github/start` without any
+router changes.
+
+The full host guide — Google client setup, the linking-policy
+decision, OAuth-only-user knock-on effects — is in
+[OAuth](oauth.md).
+
 ## Overriding email and HTML templates
 
 Both surfaces share `RegStack.add_template_dir(path)`:
@@ -193,5 +246,7 @@ for production probes that need more than a TCP hit.
 - 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.
-- It does not ship OAuth providers in v1 — `oauth/` reserves the
-  abstraction surface only, for a future milestone.
+- It does not ship OAuth providers other than Google. The
+  abstraction is shaped to take GitHub / Microsoft / Apple later;
+  hosts that want a different provider today can implement
+  :class:`~regstack.oauth.base.OAuthProvider` and register it.

{regstack-0.3.0 → regstack-0.4.0}/docs/index.md

@@ -78,6 +78,10 @@ each time".
   Full template overrides are still possible per host.
 - **CLIs.** `regstack init` (interactive setup wizard),
   `regstack create-admin`, `regstack doctor`.
+- **OAuth — Sign in with Google** (opt-in, since 0.3.0). Authorization
+  Code with PKCE, ID-token verification, identity-linking with a
+  default-refuse policy hosts can opt out of. Connected-accounts
+  panel on the SSR `/account/me` page. See [the OAuth guide](oauth.md).
 - **Pluggable email and SMS.** Email backends: `console` (dev), SMTP,
   [Amazon SES](https://aws.amazon.com/ses/). SMS backends:
   [Amazon SNS](https://aws.amazon.com/sns/),
@@ -135,7 +139,7 @@ changelog
 
 ## Project status
 
-Alpha. Latest tagged release: `v0.2.1`. SQLite is the default and
+Alpha. Latest tagged release: `v0.4.0`. SQLite is the default and
 runs with no infrastructure; PostgreSQL and MongoDB pass the same
 parametrized integration suite. The full backend matrix runs in
 parallel against every test, so a green CI on `main` is a strong

{regstack-0.3.0 → regstack-0.4.0}/docs/oauth.md

@@ -53,6 +53,25 @@ In the [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
 
 ## Configure regstack
 
+The fastest path is the **OAuth setup wizard**, which opens a native
+window and walks you through every step (registering the GCP client,
+pasting the redirect URI, picking your linking policy) and finally
+merges the credentials into your existing `regstack.toml` and
+`regstack.secrets.env` without disturbing other settings:
+
+```bash
+uv run regstack oauth setup
+```
+
+The wizard is **non-clobbering** — it preserves comments, unrelated
+top-level keys, and unrelated tables (`[email]`, `[sms]`, etc.). Re-run
+it any time you need to rotate credentials or change the linking
+policy. On a headless host (CI, server) use
+`regstack oauth setup --print-only --client-id=… --client-secret=…`
+to get the same merge with no GUI.
+
+If you'd rather edit by hand, the resulting files look like:
+
 ```toml
 # regstack.toml
 enable_oauth = true

regstack-0.4.0/docs/security-reports/README.md

@@ -0,0 +1,15 @@
+# Security reports
+
+Daily output from the scheduled security-review agent (see
+[`scripts/security-review-prompt.md`](../../scripts/security-review-prompt.md)).
+
+Each file is named `YYYY-MM-DD.md` and follows the structure declared
+in the prompt: 🔴 CRITICAL / 🟠 WARNING / 🟡 INFO / 🟢 CLEAN findings,
+plus a summary block.
+
+The agent files a PR per report so each review is reviewable as a
+diff against `main`. PR title prefix:
+
+- `[security-critical]` — at least one CRITICAL finding.
+- `[security-warning]` — at least one WARNING finding (no CRITICALs).
+- `[security-clean]` — clean bill of health.

{regstack-0.3.0 → regstack-0.4.0}/docs/security.md

@@ -161,6 +161,77 @@ visible to logged-out users only.
   instead of a session token, sends an SMS, and requires
   `POST /login/mfa-confirm` to complete.
 
+## OAuth (Sign in with Google)
+
+Opt-in subsystem behind `enable_oauth` and the `oauth` extra. Five
+JSON endpoints plus an SSR token-handoff page. The full host-facing
+guide is in [OAuth](oauth.md); this section is the threat model.
+
+- **Server-side PKCE.** The `code_verifier` is generated server-side
+  and persisted on a `oauth_states` row; only its SHA-256
+  `code_challenge` ever travels through the browser. The token
+  exchange POSTs the verifier directly from the regstack server to
+  Google's token endpoint, so a leaked browser-side state value
+  alone can't drive a token exchange.
+- **State row is the OAuth `state` parameter.** Random 32-byte
+  url-safe id; carries `code_verifier`, `nonce`, `redirect_to`,
+  `mode` (`signin` or `link`), optional `linking_user_id`. The
+  callback looks the row up by id, rejects missing / expired rows
+  with `?error=bad_state` or `?error=state_expired`. Mongo gets free
+  TTL via `expireAfterSeconds`; SQL backends rely on read-side
+  `expires_at > now()` plus `purge_expired()`.
+- **ID token verification.** Signature against Google's JWKS
+  (`PyJWKClient` cached), `iss` matches Google, `aud` matches the
+  configured `client_id`, `exp > now`, `nonce` matches the value
+  stashed on the state row. Any failure raises
+  `OAuthIdTokenError` and the callback redirects to the login page
+  with `?error=id_token_failed` — the specific check that failed is
+  logged but not echoed.
+- **Account-linking policy.** Defaults to **refuse**. If a Google
+  sign-in carries an email already owned by a regstack user, the
+  callback returns `?error=email_in_use` and the user has to sign
+  in with their existing password before linking from
+  `/account/me`. Auto-linking is available behind
+  `oauth.auto_link_verified_emails = true`; even then, regstack
+  requires `email_verified=true` on the ID token. The threat
+  auto-link accepts is *email recycling at the provider* — if
+  someone later acquires the original Gmail address, they could
+  sign in as the original regstack user. Hosts choosing auto-link
+  do so eyes-open. Full writeup in
+  `tasks/oauth-design.md` § 1.
+- **One-time token-handoff.** After a successful callback, the
+  fresh session JWT is stashed on the `oauth_states.result_token`
+  field and the SPA exchanges its state-id for the token via
+  `POST /oauth/exchange`. The exchange consumes the row atomically
+  (read + delete in one transaction); a second exchange call with
+  the same id returns 404. Tokens never appear in URLs longer than
+  the callback redirect, no cookies are set.
+- **OAuth-issued sessions are normal session JWTs** signed with the
+  same `session`-purpose key. The `tokens_invalidated_after` bulk-
+  revoke applies — a password change or admin-disable kills any
+  OAuth-issued session too.
+- **Open-redirect protection.** `redirect_to` on `/start` is
+  validated same-origin against `config.base_url`; a request with
+  an off-site target returns 400.
+- **Identity-row uniqueness.** `(provider, subject_id)` is unique
+  so two regstack users can't share one external account; a
+  second-user link attempt returns `?error=identity_in_use`.
+  `(user_id, provider)` is also unique so re-linking the same
+  provider to the same user returns `?error=already_linked`
+  rather than silently succeeding.
+- **OAuth-only users.** A Google sign-up creates a user with
+  `hashed_password=None`. Login with a password against such an
+  account returns the same generic 401 a wrong-password attempt
+  gets — never reveal that an account exists but has no password
+  set, so an attacker can't enumerate which accounts to phish via
+  OAuth. `change-password` / `change-email` / `delete-account`
+  return 400 with a pointer at the password-reset flow, which
+  doubles as a "set initial password" path.
+- **Refuse to unlink the only auth method.**
+  `DELETE /oauth/{provider}/link` returns 400 if the user has no
+  password and only the one identity. Forces them to either set a
+  password (via reset) or link another provider first.
+
 ## CSP and the SSR layer
 
 Content Security Policy (CSP) is a browser feature that restricts

{regstack-0.3.0 → regstack-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "regstack"
-version = "0.3.0"
+version = "0.4.0"
 description = "Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -32,6 +32,11 @@ dependencies = [
     "sqlalchemy[asyncio]>=2.0",
     "aiosqlite>=0.20",
     "alembic>=1.13",
+    # OAuth setup wizard (regstack oauth setup) — needs a webview shell,
+    # a small in-process FastAPI server, and round-trip-safe TOML editing.
+    "pywebview>=5.0",
+    "tomlkit>=0.13",
+    "uvicorn[standard]>=0.29",
 ]
 
 [project.optional-dependencies]
@@ -65,6 +70,8 @@ dev = [
     "asyncpg>=0.29",
     # OAuth provider tests need the crypto bits to verify ID tokens.
     "pyjwt[crypto]>=2.8",
+    # E2E tests for the OAuth setup wizard (drives the SPA in headless Chromium).
+    "pytest-playwright>=0.5",
 ]
 
 [project.scripts]
@@ -98,11 +105,18 @@ markers = [
 filterwarnings = [
     "error",
     "ignore::DeprecationWarning:passlib.*",
+    # uvicorn[standard] still imports websockets.legacy on shutdown,
+    # which fires a DeprecationWarning. The wizard's e2e fixture runs
+    # uvicorn in a thread and pytest's threadexception plugin promotes
+    # thread warnings to errors — silence at the source.
+    "ignore::DeprecationWarning:websockets.*",
+    "ignore::DeprecationWarning:uvicorn.*",
     # CI surfaces PytestUnraisableExceptionWarning when async fixtures
     # from a previous test leak sockets/event loops past their cleanup
     # window — the sync UI tests shouldn't fail just because asyncpg or
     # aiosqlite teardown was sloppy in a sibling test.
     "ignore::pytest.PytestUnraisableExceptionWarning",
+    "ignore::pytest.PytestUnhandledThreadExceptionWarning",
 ]
 
 [tool.ruff]