supython 0.1.14__tar.gz → 0.1.15__tar.gz

{supython-0.1.14 → supython-0.1.15}/CHANGELOG.md

@@ -30,6 +30,120 @@ Each entry links the relevant `PROJECT.md` section and decision-log row
 
 ---
 
+## [0.1.15] — 2026-07-21
+
+Auth hardening from the GHSA security review (three stacked PRs, #10–#12).
+
+### Breaking
+- Emailed verify links (`GET /auth/v1/{magiclink,confirm}/verify`) are now
+  side-effect-free HTML interstitials; the token is consumed by the form
+  **POST** to the same path. Mail scanners that prefetch the GET no longer
+  burn the token or (in redirect mode) receive the session. Any client
+  calling the verify endpoint directly must switch GET → POST (the bundled
+  SDK already does).
+- OAuth `redirect_uri` must now match `OAUTH_REDIRECT_ALLOWLIST`
+  (comma-separated origins). The allowlist is empty by default, which
+  **fails closed**: OAuth sign-in returns `invalid_redirect` (400) until
+  the setting lists your app origins. Previously any `redirect_uri`
+  accepted by the provider was 302'd to with the token pair in the URL
+  fragment — a token-stealing open redirect on laxly configured
+  providers.
+- Refresh tokens are stored as sha256 hashes (migration `0019` converts
+  existing rows in place; issued raw tokens keep working). Anything that
+  read raw tokens out of `auth.refresh_tokens` directly — including the
+  admin refresh-token list — now sees digests.
+- `client.auth.sign_up(...)` now resolves to a `SignUpResponse`
+  (`{user, session, confirmation_sent_at}`) instead of a bare
+  `TokenResponse`; `session` is `None` when the server requires email
+  confirmation. Read tokens via `result.data.session.access_token`.
+- OAuth sign-ins whose provider cannot vouch for the email address are
+  refused with `provider_email_unverified` (403). In particular, GitHub
+  accounts with no *verified* email can no longer sign in or link.
+
+### Added
+- Email change with dual confirmation. `PUT /auth/v1/user` with `email`
+  starts it; a confirmation link is sent to **both** the current and the
+  new address, and the change applies only once both are verified
+  (`POST /auth/v1/email_change/verify`, 202 until the second side). The
+  current-inbox requirement means a stolen access token alone cannot
+  re-point the account email. New `EMAIL_CHANGE_TOKEN_TTL` (1 h) and two
+  operator-editable templates (migration `0020`).
+- User/app metadata. `raw_user_meta_data` is now wired through: set at
+  signup via `data`, merged via `PUT /auth/v1/user` `data`, and returned
+  as `user_metadata` on the user object — user-controlled, display-only,
+  **never** an authorization input. New server-controlled
+  `raw_app_meta_data` (migration `0020`) records the auth provider(s) and
+  is surfaced as `app_metadata`. SDK: `auth.update_user(email=, data=)`,
+  `auth.verify_email_change(token)`.
+- `TRUSTED_PROXIES` — proxy-aware client-IP resolution for rate limiting
+  and audit logging. When the TCP peer is a listed proxy, the IP is taken
+  from the rightmost untrusted `X-Forwarded-For` hop; empty (default)
+  ignores the header so a spoofed value can never shift a rate-limit
+  bucket.
+- Signup email-confirmation flow (§9.2). With
+  `AUTH_REQUIRE_EMAIL_CONFIRMATION=true`, `POST /auth/v1/signup` returns
+  202 without tokens and emails a confirmation link;
+  `GET /auth/v1/confirm/verify` redeems it (optionally 302-redirecting to
+  an allowlisted `redirect_url` with the token pair in the fragment) and
+  `POST /auth/v1/confirm/resend` re-sends it. Sign-in and refresh are
+  refused with `email_not_confirmed` (403) until the address is proven.
+  New settings: `AUTH_REQUIRE_EMAIL_CONFIRMATION` (default off),
+  `SIGNUP_CONFIRM_TOKEN_TTL` (24 h),
+  `AUTH_RATE_LIMIT_CONFIRM_PER_WINDOW` (5). New `signup_confirm`
+  one-time-token type and operator-editable email template
+  (migration `0018`). Client SDK grows `auth.verify_signup(token)` and
+  `auth.resend_confirmation(email)`.
+- Scoped signout. `POST /auth/v1/logout` accepts
+  `{refresh_token?, scope: local|global|others}` (default `local`, wire-
+  compatible with the old body). `local` also revokes the token's rotated
+  descendants; `global` revokes every session and can be driven by the
+  bearer access token alone; `others` keeps only the presented session.
+  Global/others sign-outs write a `sign_out` audit event. Client SDK:
+  `auth.sign_out(scope=...)`.
+- `PUT /auth/v1/user` — authenticated password change. Requires
+  `current_password` when one is set (a stolen access token alone cannot
+  take over the credential); passwordless (OAuth-only/invite) accounts
+  may set a first password with just their bearer. Revokes every refresh
+  token and returns a fresh pair. Client SDK:
+  `auth.update_password(new, current)`.
+
+### Changed
+- `auth.users.email_confirmed_at` is now an honest "inbox ownership
+  proven" flag: stamped by signup confirmation, magic-link / OTP /
+  recovery verification, and provider-verified OAuth sign-ins — never by
+  signup itself (previously it was set unconditionally at signup). Rows
+  created before `0018` keep their old unproven stamp; see the migration
+  header for the strict-mode cleanup query.
+
+### Fixed
+- One-time-token consumption (recover / magic link / OTP / signup
+  confirm) is now a single atomic `update … where used_at is null`,
+  closing the race where two concurrent verifies of the same token could
+  both succeed.
+
+### Security
+- Emailed verify links are no longer consumable by GET prefetch (see
+  Breaking) — closes the link-scanner token-burn / session-leak window.
+- `PUT /auth/v1/user` email change requires confirmation from the current
+  inbox as well as the new one, so a stolen access token cannot silently
+  hijack the account's email.
+- A successful password reset (`/auth/v1/recover/verify`) now revokes
+  every existing refresh token and every other pending recover token, so
+  a suspected-stolen session does not survive the reset. Password change
+  via `PUT /auth/v1/user` does the same.
+- Refresh tokens are hashed at rest (see Breaking) and OAuth redirect
+  targets are origin-allowlisted (see Breaking).
+- Account pre-hijack defence (pre-hijack pair, review 2026-07-21):
+  OAuth account creation and link-by-email now require a
+  provider-verified email (Google: OIDC `email_verified`; GitHub:
+  verified entry from `/user/emails`), and linking into an unproven-email
+  account that has a password is refused with `email_conflict` (403) and
+  an `oauth_link_refused` audit event. Previously an attacker could
+  pre-register a victim's email with a password and silently gain a
+  backdoor into the account the victim later created via OAuth.
+
+---
+
 ## [0.1.14] — 2026-07-17
 
 ### Added

{supython-0.1.14 → supython-0.1.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.14
+Version: 0.1.15
 Summary: A lightweight Postgres-first BaaS framework for Python
 Project-URL: Homepage, https://github.com/Tkeby/supython
 Project-URL: Repository, https://github.com/Tkeby/supython
@@ -407,20 +407,29 @@ supython dev
 
 | Endpoint | Method | Purpose |
 |---|---|---|
-| `/auth/v1/signup` | POST | Create account, return token pair |
+| `/auth/v1/signup` | POST | Create account; returns a token pair, or `202` + confirmation email when `AUTH_REQUIRE_EMAIL_CONFIRMATION` is on |
+| `/auth/v1/confirm/verify` | GET / POST | GET renders a confirm page; POST redeems the signup-confirmation token |
+| `/auth/v1/confirm/resend` | POST | Re-send the signup confirmation email |
 | `/auth/v1/token` | POST | Password login |
 | `/auth/v1/refresh` | POST | Rotate refresh token (reuse detection built in) |
-| `/auth/v1/logout` | POST | Revoke refresh token |
-| `/auth/v1/user` | GET | Return the caller's user (JWT required) |
+| `/auth/v1/logout` | POST | Sign out — `scope`: `local` (default) / `global` / `others` |
+| `/auth/v1/user` | GET | Return the caller's user, incl. `user_metadata` / `app_metadata` (JWT required) |
+| `/auth/v1/user` | PUT | Change password, OR start an email change / merge `data` into `user_metadata` |
+| `/auth/v1/email_change/verify` | GET / POST | Confirm one side of a dual-confirmation email change |
 | `/auth/v1/recover` | POST | Request password-reset email |
-| `/auth/v1/recover/verify` | POST | Verify reset token, set new password |
+| `/auth/v1/recover/verify` | POST | Verify reset token, set new password (revokes all sessions) |
 | `/auth/v1/magiclink` | POST | Request magic-link email |
-| `/auth/v1/magiclink/verify` | GET | Verify magic-link token (`?token=…`) |
+| `/auth/v1/magiclink/verify` | GET / POST | GET renders a confirm page; POST redeems the magic-link token |
 | `/auth/v1/otp` | POST | Request email OTP |
 | `/auth/v1/otp/verify` | POST | Verify OTP code |
-| `/auth/v1/authorize/{provider}` | GET | Start OAuth flow (redirect to provider) |
+| `/auth/v1/authorize/{provider}` | GET | Start OAuth flow (redirect to provider; `redirect_uri` must be allowlisted) |
 | `/auth/v1/callback/{provider}` | GET | Handle OAuth callback, redirect with tokens |
 
+Emailed verify links (signup confirm, magic link, email change) are
+**GET landing pages** that consume nothing — the token is redeemed by the
+form **POST** they submit, so mail-scanner GET prefetch can't burn a token
+or leak a session.
+
 **Email backend** — set `EMAIL_BACKEND=console` (default, logs to stdout) or
 `EMAIL_BACKEND=smtp` and configure `SMTP_HOST / SMTP_PORT / SMTP_USERNAME /
 SMTP_PASSWORD`.
@@ -428,8 +437,10 @@ SMTP_PASSWORD`.
 **OAuth** — add `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` (and/or GitHub
 equivalents) to `.env`. Providers without credentials are silently disabled.
 
-**Logout semantics (stateless JWT)** — `/auth/v1/logout` revokes the
-**refresh** token; the access token remains valid until its `exp` claim. This
+**Logout semantics (stateless JWT)** — `/auth/v1/logout` revokes **refresh**
+tokens (`scope=local` for this session and its rotated descendants, `global`
+for all, `others` for all but this one); the access token remains valid until
+its `exp` claim. This
 is the standard stateless-JWT posture (same as Supabase Auth, Auth0, Cognito):
 both supython and PostgREST verify access tokens from the JWKS with **no
 per-request DB lookup**, so there is no place to consult a server-side
@@ -530,6 +541,12 @@ need any claim beyond the user UUID.
 | `AUTH_RATE_LIMIT_RECOVER_PER_WINDOW` | `3` | `/auth/v1/recover` attempts per IP/window |
 | `AUTH_RATE_LIMIT_OTP_PER_WINDOW` | `5` | `/auth/v1/otp` attempts per IP/window |
 | `AUTH_RATE_LIMIT_MAGICLINK_PER_WINDOW` | `5` | `/auth/v1/magiclink` attempts per IP/window |
+| `AUTH_RATE_LIMIT_CONFIRM_PER_WINDOW` | `5` | `/auth/v1/confirm/*` attempts per IP/window |
+| `AUTH_REQUIRE_EMAIL_CONFIRMATION` | `false` | Require new signups to confirm their email (signup returns 202 without tokens; sign-in refused with `email_not_confirmed` until `/auth/v1/confirm/verify`) |
+| `OAUTH_REDIRECT_ALLOWLIST` | *(empty)* | Comma-separated origins an OAuth `redirect_uri` may target. Empty fails closed — OAuth sign-in is refused until configured |
+| `TRUSTED_PROXIES` | *(empty)* | Comma-separated IPs/CIDRs of reverse proxies. When the TCP peer is trusted, rate limiting and audit logs use the rightmost untrusted `X-Forwarded-For` hop; empty ignores the header entirely |
+| `EMAIL_CHANGE_TOKEN_TTL` | `3600` | Email-change confirmation token lifetime in seconds (both inboxes must confirm) |
+| `SIGNUP_CONFIRM_TOKEN_TTL` | `86400` | Signup confirmation token lifetime in seconds (24 h) |
 
 **`AUTHENTICATOR_PASSWORD`** — the password used for the `authenticator` Postgres
 role that PostgREST connects as.  Defaults to `authenticator` (matches the

{supython-0.1.14 → supython-0.1.15}/README.md

@@ -348,20 +348,29 @@ supython dev
 
 | Endpoint | Method | Purpose |
 |---|---|---|
-| `/auth/v1/signup` | POST | Create account, return token pair |
+| `/auth/v1/signup` | POST | Create account; returns a token pair, or `202` + confirmation email when `AUTH_REQUIRE_EMAIL_CONFIRMATION` is on |
+| `/auth/v1/confirm/verify` | GET / POST | GET renders a confirm page; POST redeems the signup-confirmation token |
+| `/auth/v1/confirm/resend` | POST | Re-send the signup confirmation email |
 | `/auth/v1/token` | POST | Password login |
 | `/auth/v1/refresh` | POST | Rotate refresh token (reuse detection built in) |
-| `/auth/v1/logout` | POST | Revoke refresh token |
-| `/auth/v1/user` | GET | Return the caller's user (JWT required) |
+| `/auth/v1/logout` | POST | Sign out — `scope`: `local` (default) / `global` / `others` |
+| `/auth/v1/user` | GET | Return the caller's user, incl. `user_metadata` / `app_metadata` (JWT required) |
+| `/auth/v1/user` | PUT | Change password, OR start an email change / merge `data` into `user_metadata` |
+| `/auth/v1/email_change/verify` | GET / POST | Confirm one side of a dual-confirmation email change |
 | `/auth/v1/recover` | POST | Request password-reset email |
-| `/auth/v1/recover/verify` | POST | Verify reset token, set new password |
+| `/auth/v1/recover/verify` | POST | Verify reset token, set new password (revokes all sessions) |
 | `/auth/v1/magiclink` | POST | Request magic-link email |
-| `/auth/v1/magiclink/verify` | GET | Verify magic-link token (`?token=…`) |
+| `/auth/v1/magiclink/verify` | GET / POST | GET renders a confirm page; POST redeems the magic-link token |
 | `/auth/v1/otp` | POST | Request email OTP |
 | `/auth/v1/otp/verify` | POST | Verify OTP code |
-| `/auth/v1/authorize/{provider}` | GET | Start OAuth flow (redirect to provider) |
+| `/auth/v1/authorize/{provider}` | GET | Start OAuth flow (redirect to provider; `redirect_uri` must be allowlisted) |
 | `/auth/v1/callback/{provider}` | GET | Handle OAuth callback, redirect with tokens |
 
+Emailed verify links (signup confirm, magic link, email change) are
+**GET landing pages** that consume nothing — the token is redeemed by the
+form **POST** they submit, so mail-scanner GET prefetch can't burn a token
+or leak a session.
+
 **Email backend** — set `EMAIL_BACKEND=console` (default, logs to stdout) or
 `EMAIL_BACKEND=smtp` and configure `SMTP_HOST / SMTP_PORT / SMTP_USERNAME /
 SMTP_PASSWORD`.
@@ -369,8 +378,10 @@ SMTP_PASSWORD`.
 **OAuth** — add `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` (and/or GitHub
 equivalents) to `.env`. Providers without credentials are silently disabled.
 
-**Logout semantics (stateless JWT)** — `/auth/v1/logout` revokes the
-**refresh** token; the access token remains valid until its `exp` claim. This
+**Logout semantics (stateless JWT)** — `/auth/v1/logout` revokes **refresh**
+tokens (`scope=local` for this session and its rotated descendants, `global`
+for all, `others` for all but this one); the access token remains valid until
+its `exp` claim. This
 is the standard stateless-JWT posture (same as Supabase Auth, Auth0, Cognito):
 both supython and PostgREST verify access tokens from the JWKS with **no
 per-request DB lookup**, so there is no place to consult a server-side
@@ -471,6 +482,12 @@ need any claim beyond the user UUID.
 | `AUTH_RATE_LIMIT_RECOVER_PER_WINDOW` | `3` | `/auth/v1/recover` attempts per IP/window |
 | `AUTH_RATE_LIMIT_OTP_PER_WINDOW` | `5` | `/auth/v1/otp` attempts per IP/window |
 | `AUTH_RATE_LIMIT_MAGICLINK_PER_WINDOW` | `5` | `/auth/v1/magiclink` attempts per IP/window |
+| `AUTH_RATE_LIMIT_CONFIRM_PER_WINDOW` | `5` | `/auth/v1/confirm/*` attempts per IP/window |
+| `AUTH_REQUIRE_EMAIL_CONFIRMATION` | `false` | Require new signups to confirm their email (signup returns 202 without tokens; sign-in refused with `email_not_confirmed` until `/auth/v1/confirm/verify`) |
+| `OAUTH_REDIRECT_ALLOWLIST` | *(empty)* | Comma-separated origins an OAuth `redirect_uri` may target. Empty fails closed — OAuth sign-in is refused until configured |
+| `TRUSTED_PROXIES` | *(empty)* | Comma-separated IPs/CIDRs of reverse proxies. When the TCP peer is trusted, rate limiting and audit logs use the rightmost untrusted `X-Forwarded-For` hop; empty ignores the header entirely |
+| `EMAIL_CHANGE_TOKEN_TTL` | `3600` | Email-change confirmation token lifetime in seconds (both inboxes must confirm) |
+| `SIGNUP_CONFIRM_TOKEN_TTL` | `86400` | Signup confirmation token lifetime in seconds (24 h) |
 
 **`AUTHENTICATOR_PASSWORD`** — the password used for the `authenticator` Postgres
 role that PostgREST connects as.  Defaults to `authenticator` (matches the

{supython-0.1.14 → supython-0.1.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supython"
-version = "0.1.14"
+version = "0.1.15"
 description = "A lightweight Postgres-first BaaS framework for Python"
 readme = "README.md"
 requires-python = ">=3.11"

{supython-0.1.14 → supython-0.1.15}/src/supython/auth/providers/__init__.py

@@ -7,10 +7,17 @@ from typing import Any
 
 @dataclass
 class ProviderProfile:
-    """Normalised identity returned by any OAuth provider."""
+    """Normalised identity returned by any OAuth provider.
+
+    ``email_verified`` must be True only when the provider itself vouches for
+    ownership of ``email``. It defaults to False so a provider that never sets
+    it fails closed: the auth service refuses to create or link an account by
+    email on an unverified profile (pre-hijack defence).
+    """
 
     provider_user_id: str
     email: str
+    email_verified: bool = False
     raw: dict[str, Any] = field(default_factory=dict)
 
 

supython-0.1.15/src/supython/auth/providers/github.py

@@ -0,0 +1,50 @@
+"""GitHub OAuth2 provider."""
+
+from authlib.integrations.httpx_client import AsyncOAuth2Client
+
+from . import ProviderProfile
+from .oauth import OAuthProvider
+
+
+class GitHubProvider(OAuthProvider):
+    name = "github"
+    AUTHORIZE_URL = "https://github.com/login/oauth/authorize"
+    # GitHub requires Accept: application/json to return JSON (not form-encoded).
+    TOKEN_URL = "https://github.com/login/oauth/access_token"
+    USERINFO_URL = "https://api.github.com/user"
+    EMAILS_URL = "https://api.github.com/user/emails"
+    DEFAULT_SCOPE = "read:user user:email"
+
+    async def _build_profile(
+        self, client: AsyncOAuth2Client, data: dict
+    ) -> ProviderProfile:
+        # The public profile email on /user is optional and carries no
+        # verified flag, so it must not be trusted for account linking.
+        # /user/emails (covered by the user:email scope) lists every address
+        # with primary/verified bits; only a verified one may be used.
+        email, verified = "", False
+        resp = await client.get(self.EMAILS_URL)
+        if resp.status_code == 200:
+            entries = [e for e in resp.json() if e.get("verified")]
+            primary = [e for e in entries if e.get("primary")]
+            chosen = primary[0] if primary else (entries[0] if entries else None)
+            if chosen:
+                email, verified = chosen["email"], True
+        # Fall back to the public profile email for display only — the
+        # service layer refuses email matching when verified is False.
+        if not email:
+            email = data.get("email") or ""
+        return ProviderProfile(
+            provider_user_id=str(data["id"]),
+            email=email,
+            email_verified=verified,
+            raw=data,
+        )
+
+    def _profile_from_userinfo(self, data: dict) -> ProviderProfile:
+        return ProviderProfile(
+            provider_user_id=str(data["id"]),
+            email=data.get("email") or "",
+            email_verified=False,
+            raw=data,
+        )

{supython-0.1.14 → supython-0.1.15}/src/supython/auth/providers/google.py

@@ -12,8 +12,12 @@ class GoogleProvider(OAuthProvider):
     DEFAULT_SCOPE = "openid email profile"
 
     def _profile_from_userinfo(self, data: dict) -> ProviderProfile:
+        # OIDC userinfo carries `email_verified`; Google may serve it as a
+        # bool or the string "true" depending on endpoint version.
+        verified = data.get("email_verified")
         return ProviderProfile(
             provider_user_id=data["sub"],
             email=data.get("email", ""),
+            email_verified=verified is True or verified == "true",
             raw=data,
         )

{supython-0.1.14 → supython-0.1.15}/src/supython/auth/providers/oauth.py

@@ -50,6 +50,17 @@ class OAuthProvider(Provider):
             resp = await client.get(self.USERINFO_URL)
             resp.raise_for_status()
             data: dict = resp.json()
+            return await self._build_profile(client, data)
+
+    async def _build_profile(
+        self, client: AsyncOAuth2Client, data: dict
+    ) -> ProviderProfile:
+        """Turn the userinfo payload into a profile.
+
+        Runs while the authenticated ``client`` is still open so providers that
+        need extra API calls (e.g. GitHub's /user/emails) can override this
+        instead of re-implementing ``exchange``.
+        """
         return self._profile_from_userinfo(data)
 
     def _profile_from_userinfo(self, data: dict) -> ProviderProfile: