supython 0.1.12__tar.gz → 0.1.13__tar.gz

{supython-0.1.12 → supython-0.1.13}/CHANGELOG.md

@@ -30,6 +30,33 @@ Each entry links the relevant `PROJECT.md` section and decision-log row
 
 ---
 
+## [0.1.13] — 2026-07-16
+
+### Added
+- `POST /auth/v1/magiclink` accepts an optional `redirect_url`: when its origin
+  is in the new `MAGIC_LINK_REDIRECT_ALLOWLIST` setting, `GET
+  /auth/v1/magiclink/verify` 302-redirects the browser to it with the token
+  pair in the fragment (the same shape as the OAuth callback), instead of
+  returning JSON. Omitting `redirect_url` keeps the existing JSON response.
+  Lets a consumer send a magic link straight to its own SPA route (e.g. an
+  invite-accept page) rather than the API's bare verify endpoint.
+- `POST /auth/v1/magiclink` accepts an optional `ttl` (seconds), clamped to
+  `[60, MAGIC_LINK_MAX_TTL]` (new setting, default 7 days). Lets a single
+  caller mint a longer-lived link (e.g. a multi-day operator invite) without
+  moving `MAGIC_LINK_TOKEN_TTL`, which every other magic-link request still
+  uses unchanged.
+- Migration `0016_magic_link_redirect.sql`: nullable `auth.one_time_tokens.redirect_url`.
+
+### Security
+- `redirect_url` is validated against an explicit origin allowlist before any
+  email is sent (empty allowlist ⇒ every redirect is rejected, fail-closed);
+  a non-allowlisted origin, embedded credentials (`user:pass@host`), or a
+  non-http(s) scheme all reject the request with `400 invalid_redirect`. The
+  target is stored server-side on the one-time token, not echoed through the
+  emailed link, so an intercepted link can't be repointed at a different origin.
+
+---
+
 ## [0.1.12] — 2026-07-01
 
 ### Fixed
@@ -318,6 +345,7 @@ v0.1–v0.7 plus a v1.1.x admin track; see §19 decision log
 ---
 
 
+[0.1.13]: https://github.com/Tkeby/supython/releases/tag/v0.1.13
 [0.1.12]: https://github.com/Tkeby/supython/releases/tag/v0.1.12
 [0.1.11]: https://github.com/Tkeby/supython/releases/tag/v0.1.11
 [0.1.10]: https://github.com/Tkeby/supython/releases/tag/v0.1.10

{supython-0.1.12 → supython-0.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.12
+Version: 0.1.13
 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

{supython-0.1.12 → supython-0.1.13}/pyproject.toml

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

{supython-0.1.12 → supython-0.1.13}/src/supython/auth/router.py

@@ -2,8 +2,18 @@ from typing import Annotated
 from uuid import UUID
 
 import jwt
-from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request, status
-from fastapi.responses import RedirectResponse
+from fastapi import (
+    APIRouter,
+    Depends,
+    Header,
+    HTTPException,
+    Query,
+    Request,
+    Response,
+    status,
+)
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse, RedirectResponse
 
 from .. import db, tokens
 from ..settings import get_settings
@@ -198,24 +208,54 @@ async def verify_recover(payload: RecoverVerifyRequest, request: Request) -> Tok
 
 @router.post("/magiclink", status_code=202, dependencies=[Depends(_rl_magiclink)])
 async def request_magic_link(payload: MagicLinkRequest) -> None:
-    async with db.acquire() as conn:
-        await service.request_magic_link(conn, payload.email)
+    try:
+        async with db.acquire() as conn:
+            await service.request_magic_link(
+                conn,
+                payload.email,
+                redirect_url=payload.redirect_url,
+                ttl=payload.ttl,
+            )
+    except service.AuthError as exc:
+        # Currently only invalid_redirect (400) — a bad email is filtered by
+        # EmailStr at the schema layer before this handler ever runs.
+        raise _auth_error(exc) from exc
 
 
 @router.get(
     "/magiclink/verify",
-    response_model=TokenResponse,
     dependencies=[Depends(_rl_magiclink)],
 )
 async def verify_magic_link(
     token: Annotated[str, Query(description="Raw magic-link token from the email")],
-) -> TokenResponse:
+) -> Response:
+    """Verify a magic-link token.
+
+    Legacy/JSON callers (no ``redirect_url`` at request time) get the same
+    ``TokenResponse`` body as always. A caller that requested a redirect gets a
+    302 to that URL with the token pair in the fragment — the same shape as the
+    OAuth callback (`oauth_callback` below) — so a browser landing here from an
+    emailed link ends up on the SPA's own page with a session, not looking at
+    raw JSON.
+    """
     try:
         async with db.acquire() as conn:
-            result = await service.verify_magic_link(conn, token)
+            user, access, refresh, ttl, redirect_url = await service.verify_magic_link(
+                conn, token
+            )
     except service.AuthError as exc:
         raise _auth_error(exc) from exc
-    return _to_token_response(*result)
+    if redirect_url:
+        fragment = (
+            f"access_token={access}"
+            f"&refresh_token={refresh}"
+            f"&expires_in={ttl}"
+            f"&token_type=bearer"
+        )
+        return RedirectResponse(f"{redirect_url}#{fragment}", status_code=302)
+    return JSONResponse(
+        jsonable_encoder(_to_token_response(user, access, refresh, ttl))
+    )
 
 
 @router.post("/otp", status_code=202, dependencies=[Depends(_rl_otp)])

{supython-0.1.12 → supython-0.1.13}/src/supython/auth/schemas.py

@@ -17,6 +17,8 @@ MAX_PASSWORD_LEN = 128
 # chars in practice). 4096 keeps a generous head-room for any future
 # encoding while still rejecting "1 MB token" abuse.
 MAX_TOKEN_LEN = 4096
+# Redirect URLs are ordinary web URLs; 2048 is the de-facto browser cap.
+MAX_REDIRECT_URL_LEN = 2048
 
 EmailField = Annotated[EmailStr, Field(max_length=MAX_EMAIL_LEN)]
 PasswordField = Annotated[
@@ -68,6 +70,17 @@ class RecoverVerifyRequest(BaseModel):
 
 class MagicLinkRequest(BaseModel):
     email: EmailField
+    # Where /auth/v1/magiclink/verify should send the browser after issuing
+    # tokens: a 302 to this URL with the token pair in the fragment (as OAuth
+    # does), instead of a JSON response. Must match MAGIC_LINK_REDIRECT_
+    # ALLOWLIST or the request is rejected 400. Omit for the JSON flow.
+    redirect_url: Annotated[
+        str | None, Field(default=None, max_length=MAX_REDIRECT_URL_LEN)
+    ] = None
+    # Per-request token lifetime in seconds, clamped to [60, MAGIC_LINK_MAX_TTL].
+    # Omit to use MAGIC_LINK_TOKEN_TTL. Lets a caller mint a longer-lived link
+    # (e.g. an operator invite) without changing the global default.
+    ttl: Annotated[int | None, Field(default=None, ge=1)] = None
 
 
 class OtpRequest(BaseModel):

{supython-0.1.12 → supython-0.1.13}/src/supython/auth/service.py

@@ -6,6 +6,7 @@ import logging
 import secrets
 from datetime import UTC, datetime, timedelta
 from typing import Any
+from urllib.parse import urlsplit
 from uuid import UUID
 
 import asyncpg
@@ -82,19 +83,26 @@ async def _store_one_time_token(
     user_id: UUID,
     token_type: str,
     ttl_seconds: int,
+    *,
+    redirect_url: str | None = None,
 ) -> str:
-    """Generate, sha256-hash, and store a one-time token. Returns the raw token."""
+    """Generate, sha256-hash, and store a one-time token. Returns the raw token.
+
+    ``redirect_url`` is stored only for magic-link tokens (recover/otp pass
+    None ⇒ NULL); verify reads it back to decide between a 302 and JSON.
+    """
     raw = secrets.token_urlsafe(32)
     expires_at = datetime.now(UTC) + timedelta(seconds=ttl_seconds)
     await conn.execute(
         """
-        insert into auth.one_time_tokens (user_id, type, token_hash, expires_at)
-        values ($1, $2, $3, $4)
+        insert into auth.one_time_tokens (user_id, type, token_hash, expires_at, redirect_url)
+        values ($1, $2, $3, $4, $5)
         """,
         user_id,
         token_type,
         _sha256(raw),
         expires_at,
+        redirect_url,
     )
     return raw
 
@@ -110,7 +118,7 @@ async def _verify_one_time_token(
     if email is not None:
         row = await conn.fetchrow(
             """
-            select ott.id as ott_id, u.id, u.email, u.created_at
+            select ott.id as ott_id, ott.redirect_url, u.id, u.email, u.created_at
             from auth.one_time_tokens ott
             join auth.users u on u.id = ott.user_id
             where ott.token_hash = $1
@@ -126,7 +134,7 @@ async def _verify_one_time_token(
     else:
         row = await conn.fetchrow(
             """
-            select ott.id as ott_id, u.id, u.email, u.created_at
+            select ott.id as ott_id, ott.redirect_url, u.id, u.email, u.created_at
             from auth.one_time_tokens ott
             join auth.users u on u.id = ott.user_id
             where ott.token_hash = $1
@@ -354,17 +362,85 @@ async def verify_recover(
     return user, access, refresh, ttl
 
 
+def _url_origin(url: str) -> str | None:
+    """Return the ``scheme://host[:port]`` origin of an absolute http(s) URL.
+
+    Returns None for anything that isn't a well-formed absolute http(s) URL, or
+    that carries embedded credentials (``user:pass@host``) — those have no place
+    in a redirect target and are a classic obfuscation vector. Origins are
+    lower-cased so comparison is case-insensitive on scheme/host.
+    """
+    try:
+        parts = urlsplit(url)
+    except ValueError:
+        return None
+    if parts.scheme not in ("http", "https") or not parts.netloc or "@" in parts.netloc:
+        return None
+    return f"{parts.scheme}://{parts.netloc}".lower()
+
+
+def validate_magic_link_redirect(redirect_url: str, allowlist_csv: str) -> str:
+    """Return ``redirect_url`` when its origin is allowlisted, else raise.
+
+    ``allowlist_csv`` is the comma-separated ``MAGIC_LINK_REDIRECT_ALLOWLIST``
+    setting. An empty allowlist rejects every redirect (the feature is off and
+    fails closed). Matching is by origin only, so any path/query/fragment under
+    an allowlisted origin is accepted. Raises ``AuthError('invalid_redirect')``
+    (400) on any miss — the caller turns that into an HTTP 400.
+    """
+    origin = _url_origin(redirect_url)
+    if origin is None:
+        raise AuthError(
+            "invalid_redirect", "redirect_url must be an absolute http(s) URL", 400
+        )
+    allowed = {
+        o for entry in allowlist_csv.split(",") if (o := _url_origin(entry.strip()))
+    }
+    if origin not in allowed:
+        raise AuthError(
+            "invalid_redirect", "redirect_url origin is not allowlisted", 400
+        )
+    return redirect_url
+
+
+def _clamp_magic_link_ttl(ttl: int | None, settings: Any) -> int:
+    """Resolve the effective magic-link TTL in seconds.
+
+    ``None`` ⇒ the ``magic_link_token_ttl`` default. A supplied value is clamped
+    to ``[60, magic_link_max_ttl]`` so a caller can neither mint a link that
+    expires too fast to click nor one that outlives the configured ceiling.
+    """
+    if ttl is None:
+        return settings.magic_link_token_ttl
+    return max(60, min(ttl, settings.magic_link_max_ttl))
+
+
 async def request_magic_link(
-    conn: asyncpg.Connection, email: str
+    conn: asyncpg.Connection,
+    email: str,
+    *,
+    redirect_url: str | None = None,
+    ttl: int | None = None,
 ) -> None:
+    s = get_settings()
+    # Validate the redirect before the user lookup: a bad redirect is a client
+    # error regardless of whether the email exists, and checking it here keeps
+    # the email-enumeration silence below intact (unknown emails still 202).
+    if redirect_url is not None:
+        validate_magic_link_redirect(redirect_url, s.magic_link_redirect_allowlist)
     row = await conn.fetchrow(
         "select id from auth.users where email = $1", email
     )
     if not row:
         return
-    s = get_settings()
     async with conn.transaction():
-        raw = await _store_one_time_token(conn, row["id"], "magic_link", s.magic_link_token_ttl)
+        raw = await _store_one_time_token(
+            conn,
+            row["id"],
+            "magic_link",
+            _clamp_magic_link_ttl(ttl, s),
+            redirect_url=redirect_url,
+        )
         verify_url = f"{s.site_url}/auth/v1/magiclink/verify?token={raw}"
         await mail.dispatch(
             conn,
@@ -379,7 +455,7 @@ async def request_magic_link(
 
 async def verify_magic_link(
     conn: asyncpg.Connection, token: str
-) -> tuple[UserResponse, str, str, int]:
+) -> tuple[UserResponse, str, str, int, str | None]:
     row = await _verify_one_time_token(conn, token, "magic_link")
     user = _row_to_user(row)
     async with conn.transaction():
@@ -388,7 +464,9 @@ async def verify_magic_link(
             row["ott_id"],
         )
         access, refresh, ttl = await _issue_pair(conn, user)
-    return user, access, refresh, ttl
+    # redirect_url is None for legacy/JSON callers; the router 302-redirects
+    # (OAuth-style, tokens in the fragment) only when it is set.
+    return user, access, refresh, ttl, row["redirect_url"]
 
 
 async def request_otp(

supython-0.1.13/src/supython/migrations/0016_magic_link_redirect.sql

@@ -0,0 +1,15 @@
+-- Magic-link redirect target.
+--
+-- When a POST /auth/v1/magiclink request carries a redirect_url (validated
+-- against MAGIC_LINK_REDIRECT_ALLOWLIST at request time), it is stored on the
+-- one-time token here. GET /auth/v1/magiclink/verify then 302-redirects the
+-- browser to that SPA URL with the token pair in the fragment — mirroring the
+-- OAuth callback — instead of returning JSON. Storing the target server-side
+-- (rather than echoing it in the emailed link) means an attacker who intercepts
+-- the link cannot repoint it at a token-stealing origin.
+--
+-- Null ⇒ legacy behaviour: verify returns a JSON TokenResponse. Backfill-safe
+-- (nullable, no default), so existing rows keep working.
+
+alter table auth.one_time_tokens
+    add column if not exists redirect_url text;

{supython-0.1.12 → supython-0.1.13}/src/supython/settings.py

@@ -82,6 +82,19 @@ class Settings(BaseSettings):
     recover_token_ttl: int = 3600
     magic_link_token_ttl: int = 15 * 60
     otp_token_ttl: int = 10 * 60
+
+    # Ceiling for a per-request magic-link lifetime. A POST /auth/v1/magiclink
+    # may pass its own `ttl` (e.g. a multi-day operator invite) without moving
+    # the magic_link_token_ttl default that ordinary sign-in links use; the
+    # requested value is clamped to [60, magic_link_max_ttl].
+    magic_link_max_ttl: int = 60 * 60 * 24 * 7  # 7 days
+
+    # Comma-separated origins (scheme://host[:port]) a magic-link `redirect_url`
+    # may target. Empty ⇒ redirects are disabled and verify keeps returning
+    # JSON. A redirect_url whose origin is not listed is rejected 400 at request
+    # time, so an attacker can't aim a victim's emailed link at a token-stealing
+    # site. Example: MAGIC_LINK_REDIRECT_ALLOWLIST=https://app.example.com,http://localhost:5173
+    magic_link_redirect_allowlist: str = ""
     auth_rate_limit_enabled: bool = True
     auth_rate_limit_window_seconds: int = 60
     auth_rate_limit_token_per_window: int = 10