regstack 0.2.6__tar.gz → 0.4.0__tar.gz

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

@@ -5,6 +5,40 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## 0.3.0 — 2026-04-30
+
+**OAuth — Sign in with Google.** Opt-in via the new `oauth` extra
+and `enable_oauth=True`. Five JSON endpoints, an SSR
+`/account/oauth-complete` page, "Sign in with Google" button on the
+login page, and a Connected-accounts panel on `/account/me`.
+
+Schema migration `0002_oauth.py` creates `oauth_identities` +
+`oauth_states` and makes `users.hashed_password` nullable
+(OAuth-only users have no password). Roll forward via
+`regstack migrate` or first-boot `install_schema()` — no manual
+intervention.
+
+Account-linking policy defaults to **refuse**: if a Google sign-in
+arrives carrying an email that already belongs to a password-
+registered user, the callback returns `?error=email_in_use` and the
+user must sign in then explicitly link from `/account/me`. Hosts
+that consciously accept the email-recycling threat for UX can flip
+`oauth.auto_link_verified_emails = true`. See
+[`docs/oauth.md`](https://regstack.readthedocs.io/en/latest/oauth.html)
+and [`tasks/oauth-design.md`](https://github.com/jdrumgoole/regstack/blob/main/tasks/oauth-design.md)
+for the full threat model.
+
+**Migration**
+
+- Install the new extra: `uv add 'regstack[oauth]'`.
+- Set `enable_oauth = true` and provide `oauth.google_client_id` +
+  `oauth.google_client_secret`.
+- Run `regstack migrate` (SQL backends only) or rely on
+  `install_schema()` at first boot.
+
+`BaseUser.hashed_password` is now `str | None`. Code that imported
+the field type explicitly will need to widen it.
+
 ## 0.2.6 — 2026-04-28
 
 Bug fix.

{regstack-0.2.6 → 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.2.6 → regstack-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.2.6
+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,16 +29,21 @@ 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'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: invoke>=2.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pyjwt[crypto]>=2.8; extra == 'dev'
 Requires-Dist: 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'
@@ -52,6 +57,8 @@ Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
 Requires-Dist: sphinx>=7.3; extra == 'docs'
 Provides-Extra: mongo
 Requires-Dist: pymongo>=4.9; extra == 'mongo'
+Provides-Extra: oauth
+Requires-Dist: pyjwt[crypto]>=2.8; extra == 'oauth'
 Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.29; extra == 'postgres'
 Provides-Extra: ses
@@ -75,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;
@@ -129,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)
@@ -242,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.2.6 → 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.2.6 → 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.2.6 → 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.2.6 → regstack-0.4.0}/docs/changelog.md

@@ -3,6 +3,107 @@
 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
+[`tasks/oauth-design.md`](https://github.com/jdrumgoole/regstack/blob/main/tasks/oauth-design.md));
+this is the release cut that wraps them up.
+
+### Added
+
+- New optional extra `oauth = ["pyjwt[crypto]>=2.8"]`.
+- New `enable_oauth` flag and `OAuthConfig` sub-model
+  (`google_client_id`, `google_client_secret`, `google_redirect_uri`,
+  `auto_link_verified_emails`, `enforce_mfa_on_oauth_signin`,
+  `state_ttl_seconds`, `completion_ttl_seconds`).
+- `regstack.oauth` package — `OAuthProvider` ABC, `OAuthRegistry`,
+  `OAuthTokens`, `OAuthUserInfo`, error hierarchy, and the concrete
+  `GoogleProvider` (Authorization Code with PKCE, ID-token
+  verification via `pyjwt[crypto]` + `PyJWKClient` against Google's
+  JWKS).
+- Five JSON endpoints (mounted lazily when `enable_oauth=True` and a
+  provider is registered):
+  - `GET    /oauth/{provider}/start`
+  - `GET    /oauth/{provider}/callback`
+  - `POST   /oauth/exchange`
+  - `POST   /oauth/{provider}/link/start` (auth)
+  - `DELETE /oauth/{provider}/link` (auth)
+  - `GET    /oauth/providers` (auth)
+- New SSR page `/account/oauth-complete` (token-handoff round-trip).
+- "Sign in with Google" button on `/account/login` and a Connected-
+  accounts panel on `/account/me`. Login page surfaces callback
+  errors via `?error=<code>` with translated banners.
+- Two new repo protocols: `OAuthIdentityRepoProtocol`,
+  `OAuthStateRepoProtocol`. Mongo + SQL implementations with
+  parametrized integration tests over all three backends.
+- Four new hook events: `oauth_signin_started`,
+  `oauth_signin_completed`, `oauth_account_linked`,
+  `oauth_account_unlinked`.
+- `tests/_fake_google/` — in-process provider stub so the OAuth
+  test suite stays offline and parallel-safe.
+- New docs page [`docs/oauth.md`](oauth.md) — host guide.
+
+### Changed (potentially breaking)
+
+- **`BaseUser.hashed_password: str` → `str | None`.** OAuth-only
+  users have no password. The login route rejects password attempts
+  on these accounts with the same generic 401 wrong-password gets
+  (no enumeration). `change-password`, `change-email`, and
+  `delete-account` all return 400 for OAuth-only users with a
+  pointer at the password-reset flow, which doubles as a "set
+  initial password" path.
+- `users.hashed_password` is now nullable in the SQL schema —
+  migration `0002_oauth.py` flips the column via `batch_alter_table`
+  (SQLite-safe). Existing rows are unaffected.
+- New SQL tables `oauth_identities` and `oauth_states`. Mongo
+  collections + indexes added by `install_schema()`.
+
+### Security defaults
+
+- **Account-linking policy defaults to refuse.** When a Google
+  sign-in carries an email that already belongs to a regstack user,
+  the callback returns `?error=email_in_use`. Hosts can opt into
+  auto-linking via `oauth.auto_link_verified_emails = true`, which
+  also requires `email_verified=true` on the ID token. The threat
+  model is in `tasks/oauth-design.md` § 1.
+- **Server-side PKCE.** `code_verifier` is stored on the
+  `oauth_states` row and never enters the URL.
+- **One-time token-handoff.** `/oauth/exchange` consumes the state
+  row atomically; second exchange returns 404.
+- **Refuse to unlink the only sign-in method.** Returns 400 for
+  OAuth-only users attempting to unlink their only provider.
+- **OAuth sessions are normal session JWTs** — the existing
+  `tokens_invalidated_after` bulk-revoke applies, so a password
+  change kills any OAuth-issued session too.
+
+### Migration notes
+
+- Install the extra: `uv add 'regstack[oauth]'`.
+- Configure: set `enable_oauth = true` and provide
+  `oauth.google_client_id` + `oauth.google_client_secret` (the
+  secret in `regstack.secrets.env` as
+  `REGSTACK_OAUTH__GOOGLE_CLIENT_SECRET`).
+- Schema: roll forward via `regstack migrate` or rely on
+  `install_schema()` at first boot.
+
 ## 0.2.6 — 2026-04-28
 
 **Bug fix.**

{regstack-0.2.6 → 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.2.6 → 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.2.6 → 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.2.6 → 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/),
@@ -120,6 +124,7 @@ configuration
 architecture
 security
 embedding
+oauth
 theming
 cli
 ```
@@ -134,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