regstack 0.1.0__py3-none-any.whl

regstack/cli/admin.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import click
+
+from regstack.cli._runtime import open_regstack
+
+
+@click.command(
+    name="create-admin",
+    help="Create or promote a superuser. Idempotent — re-running flips an existing user to admin.",
+)
+@click.option("--email", required=True, help="Admin email address.")
+@click.option(
+    "--password",
+    default=None,
+    help="Password. If omitted you will be prompted (with confirmation).",
+)
+@click.option(
+    "--config",
+    "toml_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to regstack.toml (default: search cwd / $REGSTACK_CONFIG).",
+)
+def create_admin(email: str, password: str | None, toml_path: Path | None) -> None:
+    if password is None:
+        password = click.prompt("Password", hide_input=True, confirmation_prompt=True)
+    if len(password) < 8:
+        raise click.UsageError("Password must be at least 8 characters.")
+
+    asyncio.run(_run(email=email, password=password, toml_path=toml_path))
+
+
+async def _run(*, email: str, password: str, toml_path: Path | None) -> None:
+    async with open_regstack(toml_path) as rs:
+        user = await rs.bootstrap_admin(email, password)
+        verb = "promoted to admin" if user.is_superuser else "created"
+        click.echo(
+            click.style(f"User {user.email} {verb} (id={user.id}).", fg="green"),
+            file=sys.stderr,
+        )

regstack/cli/doctor.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+import dns.resolver
+from pymongo import AsyncMongoClient
+
+from regstack.cli._runtime import load_runtime_config
+from regstack.db.client import make_client
+from regstack.email.factory import build_email_service
+
+
+@dataclass(slots=True)
+class CheckResult:
+    name: str
+    ok: bool
+    detail: str
+
+
+@click.command(
+    name="doctor",
+    help="Read-only validation of the loaded regstack configuration.",
+)
+@click.option(
+    "--config",
+    "toml_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to regstack.toml (default: search cwd / $REGSTACK_CONFIG).",
+)
+@click.option(
+    "--check-dns",
+    is_flag=True,
+    help="Run SPF / DKIM / MX lookups for the sender domain.",
+)
+@click.option(
+    "--send-test-email",
+    "test_recipient",
+    default=None,
+    help="Send a probe email to this address through the configured backend.",
+)
+def doctor(toml_path: Path | None, check_dns: bool, test_recipient: str | None) -> None:
+    results = asyncio.run(
+        _run(toml_path=toml_path, check_dns=check_dns, test_recipient=test_recipient)
+    )
+    failed = sum(1 for r in results if not r.ok)
+    for r in results:
+        symbol = click.style("✔", fg="green") if r.ok else click.style("✘", fg="red")
+        click.echo(f"{symbol} {r.name}: {r.detail}")
+    if failed:
+        click.echo(click.style(f"\n{failed} check(s) failed.", fg="red"), err=True)
+    sys.exit(failed)
+
+
+async def _run(
+    *, toml_path: Path | None, check_dns: bool, test_recipient: str | None
+) -> list[CheckResult]:
+    out: list[CheckResult] = []
+
+    config = load_runtime_config(toml_path)
+
+    secret_value = config.jwt_secret.get_secret_value()
+    if not secret_value:
+        out.append(CheckResult("jwt secret", False, "missing — run `regstack init`"))
+    elif len(secret_value) < 32:
+        out.append(
+            CheckResult("jwt secret", False, f"too short ({len(secret_value)} chars; need ≥32)")
+        )
+    else:
+        out.append(CheckResult("jwt secret", True, f"present ({len(secret_value)} chars)"))
+
+    out.append(await _check_mongo(config))
+
+    out.append(await _check_indexes(config))
+
+    out.append(_check_email_factory(config))
+
+    if check_dns:
+        out.extend(_check_dns(config))
+
+    if test_recipient:
+        out.append(await _send_test_email(config, test_recipient))
+
+    return out
+
+
+async def _check_mongo(config) -> CheckResult:
+    client: AsyncMongoClient = make_client(config)
+    try:
+        await client.admin.command("ping")
+        names = await client.list_database_names()
+        present = config.mongodb_database in names
+        detail = (
+            f"reachable; database {config.mongodb_database!r} "
+            f"{'exists' if present else 'will be created on first use'}"
+        )
+        return CheckResult("mongodb", True, detail)
+    except Exception as exc:
+        return CheckResult("mongodb", False, f"unreachable: {exc}")
+    finally:
+        await client.aclose()
+
+
+async def _check_indexes(config) -> CheckResult:
+    client: AsyncMongoClient = make_client(config)
+    try:
+        db = client[config.mongodb_database]
+        users_idx = await db[config.user_collection].index_information()
+        bl_idx = await db[config.blacklist_collection].index_information()
+        missing: list[str] = []
+        if "email_unique" not in users_idx:
+            missing.append(f"{config.user_collection}.email_unique")
+        if "jti_unique" not in bl_idx:
+            missing.append(f"{config.blacklist_collection}.jti_unique")
+        if missing:
+            return CheckResult(
+                "indexes", False, f"missing: {', '.join(missing)} (call install_indexes)"
+            )
+        return CheckResult("indexes", True, "core indexes present")
+    except Exception as exc:
+        return CheckResult("indexes", False, f"check failed: {exc}")
+    finally:
+        await client.aclose()
+
+
+def _check_email_factory(config) -> CheckResult:
+    try:
+        service = build_email_service(config.email)
+    except Exception as exc:
+        return CheckResult(
+            "email backend", False, f"backend {config.email.backend!r} failed to instantiate: {exc}"
+        )
+    return CheckResult("email backend", True, f"{config.email.backend} → {type(service).__name__}")
+
+
+def _check_dns(config) -> list[CheckResult]:
+    sender = config.email.from_address
+    try:
+        domain = sender.split("@", 1)[1]
+    except IndexError:
+        return [CheckResult("dns sender", False, f"invalid sender: {sender!r}")]
+    out: list[CheckResult] = []
+    out.append(_dig(domain, "MX", "dns mx"))
+    out.append(_dig(domain, "TXT", "dns spf", needle="v=spf1"))
+    out.append(_dig(f"_dmarc.{domain}", "TXT", "dns dmarc", needle="v=DMARC1"))
+    return out
+
+
+def _dig(name: str, rtype: str, label: str, *, needle: str | None = None) -> CheckResult:
+    try:
+        answers = dns.resolver.resolve(name, rtype, lifetime=5.0)
+    except dns.resolver.NXDOMAIN:
+        return CheckResult(label, False, f"{name} → NXDOMAIN")
+    except (dns.resolver.NoAnswer, dns.resolver.NoNameservers, dns.exception.DNSException) as exc:
+        return CheckResult(label, False, f"{name} → {exc}")
+    if needle is not None:
+        joined = "\n".join(str(rdata) for rdata in answers)
+        if needle not in joined:
+            return CheckResult(label, False, f"no {needle!r} record on {name}")
+    return CheckResult(label, True, f"{name} ok ({len(answers)} record(s))")
+
+
+async def _send_test_email(config, to: str) -> CheckResult:
+    from regstack.email.base import EmailMessage
+
+    try:
+        service = build_email_service(config.email)
+        await service.send(
+            EmailMessage(
+                to=to,
+                subject=f"[{config.app_name}] regstack doctor probe",
+                html="<p>regstack doctor probe — if you can read this, your email backend works.</p>",
+                text="regstack doctor probe — if you can read this, your email backend works.",
+                from_address=config.email.from_address,
+                from_name=config.email.from_name,
+            )
+        )
+        return CheckResult(
+            "email send", True, f"probe delivered to {to} via {config.email.backend}"
+        )
+    except Exception as exc:
+        return CheckResult("email send", False, f"send failed: {exc}")

regstack/cli/init.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import click
+
+from regstack.config.secrets import generate_secret
+
+CONFIG_FILE = "regstack.toml"
+SECRETS_FILE = "regstack.secrets.env"
+
+
+@click.command(help="Interactive wizard that writes regstack.toml + regstack.secrets.env.")
+@click.option(
+    "--target",
+    "target_dir",
+    type=click.Path(file_okay=False, dir_okay=True, path_type=Path),
+    default=Path.cwd,
+    show_default="current directory",
+    help="Directory to write config files into.",
+)
+@click.option("--force", is_flag=True, help="Overwrite existing config files without prompting.")
+def init(target_dir: Path, *, force: bool) -> None:
+    target_dir = Path(target_dir).resolve()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    config_path = target_dir / CONFIG_FILE
+    secrets_path = target_dir / SECRETS_FILE
+
+    if (config_path.exists() or secrets_path.exists()) and not force:
+        click.confirm(
+            f"Config already exists at {config_path} or {secrets_path}. Overwrite?",
+            abort=True,
+        )
+
+    click.echo(click.style("regstack init — app configuration only.\n", bold=True))
+    click.echo("This wizard never provisions infrastructure. It only writes config files.\n")
+
+    # --- App identity ---
+    app_name = click.prompt("App name", default="MyApp")
+    base_url = click.prompt("Public base URL", default="http://localhost:8000")
+    parsed = urlsplit(base_url)
+    cookie_default = parsed.hostname or ""
+    cookie_domain = click.prompt(
+        "Cookie domain (blank for none)", default=cookie_default, show_default=True
+    )
+    behind_proxy = click.confirm("Behind a reverse proxy (X-Forwarded-* headers)?", default=False)
+
+    # --- MongoDB ---
+    mongodb_url = click.prompt("MongoDB connection URL", default="mongodb://localhost:27017")
+    mongodb_database = click.prompt("MongoDB database", default=app_name.lower().replace(" ", "_"))
+
+    # --- JWT ---
+    if click.confirm("Auto-generate a 64-byte JWT secret?", default=True):
+        jwt_secret = generate_secret(64)
+    else:
+        jwt_secret = click.prompt("JWT secret", hide_input=True, confirmation_prompt=True)
+    jwt_ttl_seconds = int(click.prompt("JWT lifetime in seconds", default=7200, type=int))
+    transport = click.prompt(
+        "Token transport", type=click.Choice(["bearer", "cookie"]), default="bearer"
+    )
+
+    # --- Email ---
+    email_backend = click.prompt(
+        "Email backend",
+        type=click.Choice(["console", "smtp", "ses"]),
+        default="console",
+    )
+    if email_backend != "console":
+        click.echo(
+            click.style(
+                f"Note: {email_backend!r} backend lands in M2; the wizard will write your "
+                "config, but the running app will refuse to send mail until then.",
+                fg="yellow",
+            )
+        )
+    sender_default = cookie_default if cookie_default and "." in cookie_default else "example.com"
+    from_address = click.prompt("Sender email address", default=f"noreply@{sender_default}")
+    from_name = click.prompt("Sender display name", default=app_name)
+    smtp_host = smtp_port = smtp_user = smtp_pass = ses_region = None
+    smtp_starttls = True
+    if email_backend == "smtp":
+        smtp_host = click.prompt("SMTP host")
+        smtp_port = int(click.prompt("SMTP port", default=587, type=int))
+        smtp_starttls = click.confirm("Use STARTTLS?", default=True)
+        smtp_user = click.prompt("SMTP username", default="")
+        smtp_pass = click.prompt("SMTP password", default="", hide_input=True) or None
+    elif email_backend == "ses":
+        ses_region = click.prompt("AWS region", default="eu-west-1")
+
+    # --- SMS (skip unless 2FA wanted) ---
+    enable_sms_2fa = click.confirm("Enable SMS-based 2FA?", default=False)
+    sms_backend = "null"
+    if enable_sms_2fa:
+        sms_backend = click.prompt(
+            "SMS backend", type=click.Choice(["sns", "twilio"]), default="sns"
+        )
+
+    # --- Features ---
+    enable_admin_router = click.confirm("Enable JSON admin router?", default=False)
+    enable_ui_router = click.confirm("Enable server-rendered UI pages?", default=False)
+    allow_registration = click.confirm("Allow self-service registration?", default=True)
+    require_verification = click.confirm("Require email verification before login?", default=False)
+
+    config_text = _render_toml(
+        app_name=app_name,
+        base_url=base_url,
+        cookie_domain=cookie_domain or None,
+        behind_proxy=behind_proxy,
+        mongodb_database=mongodb_database,
+        jwt_ttl_seconds=jwt_ttl_seconds,
+        transport=transport,
+        require_verification=require_verification,
+        allow_registration=allow_registration,
+        enable_admin_router=enable_admin_router,
+        enable_ui_router=enable_ui_router,
+        enable_sms_2fa=enable_sms_2fa,
+        email_backend=email_backend,
+        from_address=from_address,
+        from_name=from_name,
+        smtp_host=smtp_host,
+        smtp_port=smtp_port,
+        smtp_starttls=smtp_starttls,
+        smtp_username=smtp_user,
+        ses_region=ses_region,
+        sms_backend=sms_backend,
+    )
+    secrets_text = _render_secrets(
+        jwt_secret=jwt_secret,
+        mongodb_url=mongodb_url,
+        smtp_password=smtp_pass,
+    )
+
+    config_path.write_text(config_text, encoding="utf-8")
+    secrets_path.write_text(secrets_text, encoding="utf-8")
+    secrets_path.chmod(0o600)
+
+    click.echo()
+    click.echo(click.style("Wrote ", fg="green") + str(config_path))
+    click.echo(click.style("Wrote ", fg="green") + str(secrets_path) + "  (chmod 600)")
+    click.echo()
+    click.echo(
+        "Next: load the config in your app with `RegStackConfig.load()` and "
+        "include `regstack.router` on a FastAPI app."
+    )
+
+
+def _render_toml(
+    *,
+    app_name: str,
+    base_url: str,
+    cookie_domain: str | None,
+    behind_proxy: bool,
+    mongodb_database: str,
+    jwt_ttl_seconds: int,
+    transport: str,
+    require_verification: bool,
+    allow_registration: bool,
+    enable_admin_router: bool,
+    enable_ui_router: bool,
+    enable_sms_2fa: bool,
+    email_backend: str,
+    from_address: str,
+    from_name: str,
+    smtp_host: str | None,
+    smtp_port: int | None,
+    smtp_starttls: bool,
+    smtp_username: str | None,
+    ses_region: str | None,
+    sms_backend: str,
+) -> str:
+    lines = [
+        "# regstack.toml — generated by `regstack init`. Re-run to regenerate.",
+        f'app_name = "{app_name}"',
+        f'base_url = "{base_url}"',
+    ]
+    if cookie_domain:
+        lines.append(f'cookie_domain = "{cookie_domain}"')
+    lines.extend(
+        [
+            f"behind_proxy = {str(behind_proxy).lower()}",
+            "",
+            f'mongodb_database = "{mongodb_database}"',
+            "",
+            f"jwt_ttl_seconds = {jwt_ttl_seconds}",
+            f'transport = "{transport}"',
+            "",
+            f"require_verification = {str(require_verification).lower()}",
+            f"allow_registration = {str(allow_registration).lower()}",
+            f"enable_admin_router = {str(enable_admin_router).lower()}",
+            f"enable_ui_router = {str(enable_ui_router).lower()}",
+            f"enable_sms_2fa = {str(enable_sms_2fa).lower()}",
+            "",
+            "[email]",
+            f'backend = "{email_backend}"',
+            f'from_address = "{from_address}"',
+            f'from_name = "{from_name}"',
+        ]
+    )
+    if email_backend == "smtp":
+        lines.extend(
+            [
+                f'smtp_host = "{smtp_host}"',
+                f"smtp_port = {smtp_port}",
+                f"smtp_starttls = {str(smtp_starttls).lower()}",
+            ]
+        )
+        if smtp_username:
+            lines.append(f'smtp_username = "{smtp_username}"')
+    elif email_backend == "ses":
+        lines.append(f'ses_region = "{ses_region}"')
+    lines.extend(["", "[sms]", f'backend = "{sms_backend}"', ""])
+    return "\n".join(lines)
+
+
+def _render_secrets(
+    *,
+    jwt_secret: str,
+    mongodb_url: str,
+    smtp_password: str | None,
+) -> str:
+    lines = [
+        "# regstack.secrets.env — keep out of version control.",
+        f"REGSTACK_JWT_SECRET={jwt_secret}",
+        f"REGSTACK_MONGODB_URL={mongodb_url}",
+    ]
+    if smtp_password:
+        lines.append(f"REGSTACK_EMAIL__SMTP_PASSWORD={smtp_password}")
+    return "\n".join(lines) + "\n"
+
+
+if __name__ == "__main__":
+    init(standalone_mode=True)
+    sys.exit(0)

regstack/config/__init__.py

@@ -0,0 +1,4 @@
+from regstack.config.loader import load_config
+from regstack.config.schema import EmailConfig, RegStackConfig, SmsConfig
+
+__all__ = ["EmailConfig", "RegStackConfig", "SmsConfig", "load_config"]

regstack/config/loader.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from regstack.config.schema import RegStackConfig
+
+_DEFAULT_TOML_NAMES = ("regstack.toml",)
+_DEFAULT_SECRETS_NAMES = ("regstack.secrets.env",)
+
+
+def _find_first(names: tuple[str, ...]) -> Path | None:
+    cwd = Path.cwd()
+    for name in names:
+        candidate = cwd / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    with path.open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def _parse_dotenv(path: Path) -> dict[str, str]:
+    """Minimal .env parser — `KEY=value` per line, no shell features."""
+    out: dict[str, str] = {}
+    for raw in path.read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if (value.startswith('"') and value.endswith('"')) or (
+            value.startswith("'") and value.endswith("'")
+        ):
+            value = value[1:-1]
+        out[key] = value
+    return out
+
+
+def _flatten_for_env(d: Mapping[str, Any], prefix: str = "REGSTACK_") -> dict[str, str]:
+    out: dict[str, str] = {}
+    for key, value in d.items():
+        full_key = f"{prefix}{key.upper()}"
+        if isinstance(value, Mapping):
+            out.update(_flatten_for_env(value, prefix=f"{full_key}__"))
+        elif isinstance(value, list):
+            out[full_key] = ",".join(str(item) for item in value)
+        elif isinstance(value, bool):
+            out[full_key] = "true" if value else "false"
+        elif value is None:
+            continue
+        else:
+            out[full_key] = str(value)
+    return out
+
+
+def load_config(
+    toml_path: Path | str | None = None,
+    secrets_env_path: Path | str | None = None,
+    **overrides: object,
+) -> RegStackConfig:
+    """Build a ``RegStackConfig`` by merging defaults, TOML, env, and kwargs.
+
+    Highest priority wins:
+        kwargs > os.environ > secrets.env > TOML > defaults.
+    """
+    env_overlay: dict[str, str] = {}
+
+    toml_candidate: Path | None
+    if toml_path is not None:
+        toml_candidate = Path(toml_path)
+    elif (env_path := os.environ.get("REGSTACK_CONFIG")) is not None:
+        toml_candidate = Path(env_path)
+    else:
+        toml_candidate = _find_first(_DEFAULT_TOML_NAMES)
+    if toml_candidate is not None and toml_candidate.is_file():
+        env_overlay.update(_flatten_for_env(_read_toml(toml_candidate)))
+
+    secrets_candidate: Path | None
+    if secrets_env_path is not None:
+        secrets_candidate = Path(secrets_env_path)
+    else:
+        secrets_candidate = _find_first(_DEFAULT_SECRETS_NAMES)
+    if secrets_candidate is not None and secrets_candidate.is_file():
+        env_overlay.update(_parse_dotenv(secrets_candidate))
+
+    # Real environment wins over TOML and secrets file.
+    for key, value in os.environ.items():
+        if key.startswith("REGSTACK_"):
+            env_overlay[key] = value
+
+    # pydantic-settings reads from os.environ; we apply our merged overlay
+    # by patching it for the duration of construction.
+    saved: dict[str, str | None] = {}
+    try:
+        for key, value in env_overlay.items():
+            saved[key] = os.environ.get(key)
+            os.environ[key] = value
+        return RegStackConfig(**overrides)  # type: ignore[arg-type]
+    finally:
+        for key, prev in saved.items():
+            if prev is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = prev