regstack 0.7.0__tar.gz → 0.8.0__tar.gz

{regstack-0.7.0 → regstack-0.8.0}/CHANGELOG.md

@@ -7,6 +7,39 @@ Sphinx docs.
 
 ## Unreleased
 
+## 0.8.0 — 2026-05-19
+
+`regstack ses setup` guided wizard, plus two security fixes from
+the 2026-05-18 daily review.
+
+**Added: `regstack ses setup`.** A pywebview wizard for the SES
+email backend, mirroring the existing `regstack oauth setup` flow.
+Nine steps walk through region selection, credential source
+(`profile` / `explicit` / `chain`), sender-domain identity
+verification (via SES `GetIdentityVerificationAttributes`),
+sandbox detection (via `GetAccount` with `GetSendQuota` heuristic
+fallback for IAM-restricted policies), and a live test send.
+Non-clobbering tomlkit + secrets.env merge. Headless
+`--print-only` mode for CI / scripting. Gated behind the joint
+extra: `pip install 'regstack[wizard,ses]'`.
+
+**Fixed: theme-designer preview no longer ships well-known credentials
+in the wheel.** `designer.html` had `alice@example.com` /
+`hunter2hunter2` as `value=` attributes on its login-form preview;
+flipped to `placeholder=` so the wheel doesn't carry well-known
+example creds that could be mistaken for real fixtures.
+(Daily security review 2026-05-18 · I-1.)
+
+**Fixed: Google OAuth token-exchange error no longer echoes the
+response body.** `exchange_code()` previously raised
+`OAuthTokenExchangeError(f"... {body!r}")` on the rare 200-without-id_token
+edge case. The body can contain a live short-lived `access_token` in
+that path, and the OAuth router logs the exception text at WARNING.
+Dropped `{body!r}` from the message; regression test in
+`tests/unit/test_oauth_google.py` pins that a planted token never
+appears in the exception's `str()` or `args`.
+(Daily security review 2026-05-18 · I-2.)
+
 ## 0.7.0 — 2026-05-17
 
 Two-week sprint that lands the `regstack validate` end-to-end probe,

{regstack-0.7.0 → regstack-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.7.0
+Version: 0.8.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
@@ -151,7 +151,7 @@ result everywhere is what regstack is for.
 ✔ 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 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)
+✔ 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), `regstack doctor` (config validator), and `regstack validate` (end-to-end probe of a deployed install)
 ✔ Three storage backends: SQLite, PostgreSQL, MongoDB — chosen by URL
 ```
 

{regstack-0.7.0 → regstack-0.8.0}/README.md

@@ -72,7 +72,7 @@ result everywhere is what regstack is for.
 ✔ 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 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)
+✔ 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), `regstack doctor` (config validator), and `regstack validate` (end-to-end probe of a deployed install)
 ✔ Three storage backends: SQLite, PostgreSQL, MongoDB — chosen by URL
 ```
 

{regstack-0.7.0 → regstack-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "regstack"
-version = "0.7.0"
+version = "0.8.0"
 description = "Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB."
 readme = "README.md"
 requires-python = ">=3.11"

{regstack-0.7.0 → regstack-0.8.0}/src/regstack/cli/__main__.py

@@ -9,26 +9,40 @@ from regstack.cli.migrate import migrate as migrate_cmd
 from regstack.cli.validate.cli import validate as validate_cmd
 from regstack.version import __version__
 
-_WIZARD_EXTRA_HINT = (
-    "The {subcommand} command requires the optional 'wizard' extra "
-    "(pywebview + tomlkit + uvicorn). Install with "
-    "`pip install regstack[wizard]` or `uv sync --extra wizard`."
-)
+_EXTRA_BLURB = {
+    "wizard": "'wizard' extra (pywebview + tomlkit + uvicorn)",
+    "ses": "'ses' extra (aioboto3 for AWS API calls)",
+    "oauth": "'oauth' extra (pyjwt[crypto] for OAuth ID-token verification)",
+}
 
 
-def _missing_wizard_extra(subcommand: str) -> click.Command:
+def _missing_extra(subcommand: str, *extras: str) -> click.Command:
     """Click command that prints a clear install hint and exits non-zero.
 
-    Used as the fallback when a wizard subcommand is invoked but the
-    ``wizard`` extra isn't installed — gives a one-line actionable
-    message instead of an ImportError traceback from deep inside the
-    wizard package.
+    Used as the fallback when a wizard subcommand is invoked but one or
+    more of the required optional extras is not installed. Gives a
+    one-line actionable message instead of an ImportError traceback
+    from deep inside the wizard package.
+
+    Args:
+        subcommand: Display name of the subcommand (e.g.
+            ``"regstack ses setup"``). Used in the error message.
+        *extras: One or more extra names the subcommand requires. The
+            hint instructs the operator to install all of them
+            together via a single ``pip install regstack[a,b,...]``.
     """
     name = subcommand.split()[-1]
-
-    @click.command(name=name, help="(needs `regstack[wizard]`)")
+    blurbs = ", ".join(_EXTRA_BLURB.get(x, f"'{x}' extra") for x in extras)
+    extras_arg = ",".join(extras)
+    hint = (
+        f"The `{subcommand}` command requires the {blurbs}. "
+        f"Install with `pip install 'regstack[{extras_arg}]'` "
+        f"or `uv sync {' '.join(f'--extra {x}' for x in extras)}`."
+    )
+
+    @click.command(name=name, help=f"(needs `regstack[{extras_arg}]`)")
     def _stub() -> None:
-        click.echo(_WIZARD_EXTRA_HINT.format(subcommand=f"`{subcommand}`"), err=True)
+        click.echo(hint, err=True)
         raise SystemExit(2)
 
     return _stub
@@ -53,7 +67,7 @@ class _LazyOauthGroup(click.Group):
         try:
             from regstack.wizard.oauth_google.cli import setup as setup_cmd
         except ImportError:
-            return _missing_wizard_extra("regstack oauth setup")
+            return _missing_extra("regstack oauth setup", "wizard")
         return setup_cmd
 
 
@@ -69,10 +83,32 @@ class _LazyThemeGroup(click.Group):
         try:
             from regstack.wizard.theme_designer.cli import design as design_cmd
         except ImportError:
-            return _missing_wizard_extra("regstack theme design")
+            return _missing_extra("regstack theme design", "wizard")
         return design_cmd
 
 
+class _LazySesGroup(click.Group):
+    """Same lazy-import pattern for the SES setup wizard.
+
+    Needs BOTH ``wizard`` (pywebview, uvicorn, tomlkit for the SPA
+    shell) AND ``ses`` (aioboto3 for AWS API calls). The hint surfaces
+    the joint install command so an operator missing either gets a
+    single actionable fix.
+    """
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return ["setup"]
+
+    def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
+        if name != "setup":
+            return None
+        try:
+            from regstack.wizard.ses.cli import setup as setup_cmd
+        except ImportError:
+            return _missing_extra("regstack ses setup", "wizard", "ses")
+        return setup_cmd
+
+
 @click.group(help="regstack — embeddable account registration for FastAPI apps.")
 @click.version_option(__version__, prog_name="regstack")
 def cli() -> None:
@@ -86,6 +122,7 @@ cli.add_command(migrate_cmd)
 cli.add_command(validate_cmd)
 cli.add_command(_LazyOauthGroup(name="oauth", help="OAuth provider setup wizards."))
 cli.add_command(_LazyThemeGroup(name="theme", help="Theme designer for the SSR pages."))
+cli.add_command(_LazySesGroup(name="ses", help="SES email backend setup wizard."))
 
 
 def main() -> None:

{regstack-0.7.0 → regstack-0.8.0}/src/regstack/email/ses.py

@@ -15,7 +15,11 @@ class SesEmailService(EmailService):
 
     def __init__(self, config: EmailConfig) -> None:
         try:
-            import aioboto3  # type: ignore[import-not-found]  # noqa: F401  (import-time check)
+            # Bare `type: ignore` because aioboto3 lacks py.typed; with
+            # the ses extra installed mypy emits import-untyped, without
+            # it import-not-found. A compound code list trips
+            # unused-ignore in whichever environment doesn't match.
+            import aioboto3  # type: ignore  # noqa: F401  (import-time check)
         except ImportError as exc:
             raise RuntimeError(
                 "The SES email backend requires the 'ses' extra. "

{regstack-0.7.0 → regstack-0.8.0}/src/regstack/oauth/providers/google.py

@@ -152,7 +152,7 @@ class GoogleProvider(OAuthProvider):
             )
         except KeyError as exc:
             raise OAuthTokenExchangeError(
-                f"google token response missing field {exc.args[0]!r}: {body!r}"
+                f"google token response missing field {exc.args[0]!r}"
             ) from exc
 
     async def verify_id_token(

{regstack-0.7.0 → regstack-0.8.0}/src/regstack/sms/sns.py

@@ -15,7 +15,7 @@ class SnsSmsService(SmsService):
 
     def __init__(self, config: SmsConfig) -> None:
         try:
-            import aioboto3  # type: ignore[import-not-found]  # noqa: F401
+            import aioboto3  # type: ignore  # noqa: F401
         except ImportError as exc:
             raise RuntimeError(
                 "The SNS SMS backend requires the 'sns' extra. "

regstack-0.8.0/src/regstack/version.py

@@ -0,0 +1 @@
+__version__ = "0.8.0"

regstack-0.8.0/src/regstack/wizard/ses/__init__.py

@@ -0,0 +1,5 @@
+"""Guided wizard for configuring the SES email backend.
+
+See ``regstack ses setup`` for the operator entry point. The wizard
+mirrors the structure of :mod:`regstack.wizard.oauth_google`.
+"""

regstack-0.8.0/src/regstack/wizard/ses/_aws.py

@@ -0,0 +1,315 @@
+"""Thin async wrapper around aioboto3 for the SES wizard's AWS calls.
+
+Split into its own module so the routes layer can patch the public
+functions in tests without touching ``aioboto3.Session`` directly.
+
+Three calls live here:
+
+- :func:`probe_credentials` — STS ``GetCallerIdentity``. Cheapest
+  way to confirm the chosen credential source actually authenticates;
+  doesn't require any SES permission.
+- :func:`probe_sender_identity` — SES ``GetIdentityVerificationAttributes``
+  on both the full email and the domain. Reports per-identity status.
+- :func:`probe_sandbox_state` — SES ``GetAccount`` (preferred) with a
+  fallback to ``GetSendQuota`` heuristic. Tolerant of ``AccessDenied``:
+  returns "unknown" rather than raising so a least-privilege IAM
+  policy doesn't block the wizard.
+- :func:`send_test_email` — SES ``SendEmail`` for the live probe at
+  step 6.
+
+All four return small typed result dataclasses the routes layer
+shovels into the SPA response payload.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+try:
+    import aioboto3  # type: ignore  # aioboto3 lacks py.typed; CI lints without --extra ses
+except ImportError as _exc:  # pragma: no cover — extras gate
+    aioboto3 = None
+    _IMPORT_ERROR: ImportError | None = _exc
+else:
+    _IMPORT_ERROR = None
+
+
+CredentialSource = Literal["profile", "explicit", "chain"]
+VerificationStatus = Literal["verified", "pending", "failed", "unknown"]
+
+
+@dataclass(slots=True, frozen=True)
+class CredentialProbe:
+    ok: bool
+    account_id: str | None = None
+    arn: str | None = None
+    error: str | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class IdentityProbe:
+    address_status: VerificationStatus
+    domain_status: VerificationStatus
+    error: str | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class SandboxProbe:
+    in_sandbox: bool
+    detection: Literal["api", "quota_heuristic", "unknown"]
+    error: str | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class TestSendProbe:
+    ok: bool
+    message_id: str | None = None
+    error: str | None = None
+
+
+def aws_available() -> bool:
+    """Whether the ``ses`` extra (aioboto3) is importable.
+
+    Used by the routes layer to short-circuit AWS-touching steps
+    with a clear error when the extra is missing — though the lazy
+    click group should catch this at invocation time, the test suite
+    exercises the routes directly without going through click.
+    """
+    return aioboto3 is not None
+
+
+def _session(
+    *,
+    source: CredentialSource,
+    profile: str | None,
+    access_key_id: str | None,
+    secret_access_key: str | None,
+) -> Any:
+    if aioboto3 is None:  # pragma: no cover — extras gate
+        raise RuntimeError(
+            "aioboto3 not installed — install the 'ses' extra: `pip install 'regstack[ses]'`."
+        )
+    if source == "profile":
+        return aioboto3.Session(profile_name=profile)
+    if source == "explicit":
+        return aioboto3.Session(
+            aws_access_key_id=access_key_id,
+            aws_secret_access_key=secret_access_key,
+        )
+    return aioboto3.Session()
+
+
+async def probe_credentials(
+    *,
+    region: str,
+    source: CredentialSource,
+    profile: str | None = None,
+    access_key_id: str | None = None,
+    secret_access_key: str | None = None,
+) -> CredentialProbe:
+    """Resolve credentials by calling STS ``GetCallerIdentity``.
+
+    STS is global; the region argument is passed only so a misconfigured
+    profile points at the same region the rest of the wizard uses.
+    """
+    try:
+        session = _session(
+            source=source,
+            profile=profile,
+            access_key_id=access_key_id,
+            secret_access_key=secret_access_key,
+        )
+        async with session.client("sts", region_name=region) as sts:
+            identity = await sts.get_caller_identity()
+    except Exception as exc:
+        return CredentialProbe(ok=False, error=_describe(exc))
+    return CredentialProbe(
+        ok=True,
+        account_id=str(identity.get("Account") or ""),
+        arn=str(identity.get("Arn") or ""),
+    )
+
+
+async def probe_sender_identity(
+    *,
+    region: str,
+    from_address: str,
+    source: CredentialSource,
+    profile: str | None = None,
+    access_key_id: str | None = None,
+    secret_access_key: str | None = None,
+) -> IdentityProbe:
+    """Check SES verification status for the sender's address and domain.
+
+    SES accepts either an email-address-level verification (verify
+    a specific ``noreply@example.com``) or a domain-level verification
+    (verify ``example.com`` and any address under it works). We report
+    both so the SPA can render the right next-step link.
+    """
+    if "@" not in from_address:
+        return IdentityProbe(
+            address_status="unknown",
+            domain_status="unknown",
+            error="from_address missing '@'",
+        )
+    domain = from_address.split("@", 1)[1].lower()
+    try:
+        session = _session(
+            source=source,
+            profile=profile,
+            access_key_id=access_key_id,
+            secret_access_key=secret_access_key,
+        )
+        async with session.client("ses", region_name=region) as ses:
+            result = await ses.get_identity_verification_attributes(
+                Identities=[from_address, domain],
+            )
+    except Exception as exc:
+        return IdentityProbe(
+            address_status="unknown",
+            domain_status="unknown",
+            error=_describe(exc),
+        )
+    attrs = result.get("VerificationAttributes") or {}
+    return IdentityProbe(
+        address_status=_status(attrs.get(from_address, {}).get("VerificationStatus")),
+        domain_status=_status(attrs.get(domain, {}).get("VerificationStatus")),
+    )
+
+
+async def probe_sandbox_state(
+    *,
+    region: str,
+    source: CredentialSource,
+    profile: str | None = None,
+    access_key_id: str | None = None,
+    secret_access_key: str | None = None,
+) -> SandboxProbe:
+    """Detect whether the account is in the SES sandbox.
+
+    Preferred path: ``ses.get_account()['ProductionAccessEnabled']``
+    (added to the SES API in 2021). Fallback: the historic quota
+    heuristic (sandbox accounts have a 200-message-per-day cap that
+    typically isn't increased without a graduation request).
+
+    Tolerant of ``AccessDenied`` on both — some operator IAM
+    policies block ``ses:GetAccount`` even when they allow
+    ``ses:SendEmail``. In that case we return ``in_sandbox=False`` +
+    ``detection="unknown"`` and the routes layer surfaces a non-
+    blocking advisory.
+    """
+    try:
+        session = _session(
+            source=source,
+            profile=profile,
+            access_key_id=access_key_id,
+            secret_access_key=secret_access_key,
+        )
+        async with session.client("ses", region_name=region) as ses:
+            try:
+                account = await ses.get_account()
+                # `ProductionAccessEnabled` is the canonical key. When
+                # absent (older SDK / control-plane version) we drop
+                # to the quota heuristic.
+                if "ProductionAccessEnabled" in account:
+                    return SandboxProbe(
+                        in_sandbox=not bool(account["ProductionAccessEnabled"]),
+                        detection="api",
+                    )
+            except Exception:
+                pass
+
+            quota = await ses.get_send_quota()
+            # Sandbox heuristic: 200 messages/day + 1 message/sec is
+            # the default sandbox cap. Anything strictly above is a
+            # graduated account.
+            max_24h = float(quota.get("Max24HourSend") or 0)
+            max_rate = float(quota.get("MaxSendRate") or 0)
+            in_sandbox = max_24h <= 200.0 and max_rate <= 1.0
+            return SandboxProbe(in_sandbox=in_sandbox, detection="quota_heuristic")
+    except Exception as exc:
+        return SandboxProbe(in_sandbox=False, detection="unknown", error=_describe(exc))
+
+
+async def send_test_email(
+    *,
+    region: str,
+    from_address: str,
+    to_address: str,
+    source: CredentialSource,
+    profile: str | None = None,
+    access_key_id: str | None = None,
+    secret_access_key: str | None = None,
+) -> TestSendProbe:
+    subject = "regstack SES wizard — test send"
+    body = (
+        "This is a test message from the `regstack ses setup` wizard.\n"
+        "If you can read it, your SES configuration is working.\n"
+    )
+    try:
+        session = _session(
+            source=source,
+            profile=profile,
+            access_key_id=access_key_id,
+            secret_access_key=secret_access_key,
+        )
+        async with session.client("ses", region_name=region) as ses:
+            response = await ses.send_email(
+                Source=from_address,
+                Destination={"ToAddresses": [to_address]},
+                Message={
+                    "Subject": {"Data": subject, "Charset": "UTF-8"},
+                    "Body": {"Text": {"Data": body, "Charset": "UTF-8"}},
+                },
+            )
+    except Exception as exc:
+        return TestSendProbe(ok=False, error=_describe(exc))
+    return TestSendProbe(ok=True, message_id=str(response.get("MessageId") or ""))
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _status(raw: Any) -> VerificationStatus:
+    """Map SES's ``VerificationStatus`` strings to our enum.
+
+    SES returns ``"Success"`` for verified, ``"Pending"`` for
+    waiting-on-DNS, ``"Failed"`` for the DNS-record-missing branch,
+    and omits the key entirely for an unknown identity.
+    """
+    if raw == "Success":
+        return "verified"
+    if raw == "Pending":
+        return "pending"
+    if raw == "Failed":
+        return "failed"
+    return "unknown"
+
+
+def _describe(exc: BaseException) -> str:
+    """Short human-readable error string for the SPA.
+
+    Doesn't try to be exhaustive — the operator who can read AWS
+    error codes also knows what they mean. We strip the boto3-specific
+    prefix and cap length so a single long traceback line doesn't
+    blow up the SPA layout.
+    """
+    text = f"{type(exc).__name__}: {exc}"
+    # Cap at 400 chars; SES error bodies are usually shorter.
+    return text[:400]
+
+
+__all__ = [
+    "CredentialProbe",
+    "IdentityProbe",
+    "SandboxProbe",
+    "TestSendProbe",
+    "aws_available",
+    "probe_credentials",
+    "probe_sandbox_state",
+    "probe_sender_identity",
+    "send_test_email",
+]