parbaked 0.4.0__tar.gz

parbaked-0.4.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Env / secrets
+.env
+.env.local
+*.db
+*.sqlite
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+*.log

parbaked-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Leighton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parbaked-0.4.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: parbaked
+Version: 0.4.0
+Summary: A par-baked starter for PoC apps: signup-with-approval auth, rate limiting, and (soon) deploy scaffolding for fly.io
+Project-URL: Homepage, https://github.com/saml7n/parbaked
+Project-URL: Repository, https://github.com/saml7n/parbaked
+Project-URL: Issues, https://github.com/saml7n/parbaked/issues
+Author: Sam Leighton
+License: MIT
+License-File: LICENSE
+Keywords: auth,fastapi,fly.io,poc,scaffold,starter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: bcrypt>=4.1
+Requires-Dist: email-validator>=2.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic-settings>=2.1
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyjwt>=2.8
+Requires-Dist: slowapi>=0.1.9
+Requires-Dist: sqlmodel>=0.0.16
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# parbaked
+
+**A par-baked starter for FastAPI PoCs.** Signup with admin approval, rate limiting, and an admin dashboard — set up in one line.
+
+> If you ship PoCs on fly.io, two things eventually bite you: anyone on the internet can spin up accounts in a loop (and run up your bill), and you write the same auth boilerplate every time. parbaked is the slice between "I have an idea" and "this is safe to put online."
+
+## 30-second quickstart
+
+```bash
+uvx parbaked new myapp
+cd myapp
+make dev
+```
+
+Open `http://localhost:8000`, sign up. Open `http://localhost:8000/auth/admin` and log in as `admin` with the password printed in your terminal. Approve yourself. Log in. Done.
+
+You now have a working PoC with:
+
+- Signup + login + JWT sessions
+- Admin-approval gate (nobody gets in until you click approve)
+- Built-in admin dashboard with pending/active/rejected queues
+- Per-IP rate limiting (5/min signup, 10/min login by default)
+- SQLite DB and secrets auto-created on first run
+
+## Add to an existing FastAPI app
+
+```python
+from fastapi import FastAPI
+from parbaked import Parbaked
+
+app = FastAPI()
+parbaked = Parbaked(app)   # ← that's the whole setup
+```
+
+That gives you `/auth/signup`, `/auth/login`, `/auth/me`, `/auth/admin`, and approval magic links. On first boot you'll see:
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║  parbaked v0.2.0 is running                                    ║
+╠════════════════════════════════════════════════════════════════╣
+║  Sign up at:   http://localhost:8000/auth/signup               ║
+║  Admin panel:  http://localhost:8000/auth/admin                ║
+║  Admin user:   admin                                           ║
+║  Admin pass:   z703EwDKmEKL9S6SaO39uuRq                        ║
+║  Email out:    Console (printed below)                         ║
+║  Database:     sqlite:///./parbaked.db                         ║
+║                                                                ║
+║  ⚠ Auto-generated secrets stored in .parbaked.json             ║
+║    Add it to .gitignore. For prod, set env vars instead.       ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
+Protect your own routes:
+
+```python
+from fastapi import Depends
+
+@app.get("/profile")
+def profile(user = Depends(parbaked.current_user)):
+    return {"email": user.email, "name": user.name}
+```
+
+## Why an approval gate?
+
+Without one:
+
+- Anyone on the internet can sign up to your PoC
+- Even with rate limits, sustained traffic can autoscale you onto a bill
+- You can't show it to a friend without also showing it to bots
+
+With one:
+
+- Pending accounts can't log in. Period.
+- You see every signup. Click approve in your inbox or in the dashboard.
+- Bots can fill the database with junk, but they can't *do* anything — and rate limits cap the junk.
+
+The approval flow uses **HMAC-signed magic links** (no DB state) AND a **built-in web dashboard** (HTTP-basic-auth gated). Use whichever you prefer — email's nicer for low volume, the dashboard's nicer when you want to see the queue.
+
+## Configuration
+
+Everything has sensible defaults. Override via env vars (prefix `PARBAKED_`) or by passing args to `Parbaked()`:
+
+| Env var | Default | What it does |
+|---|---|---|
+| `JWT_SECRET` | *(auto-generated)* | Session token signing key |
+| `APPROVAL_TOKEN_SECRET` | *(auto-generated)* | Magic-link signing key |
+| `ADMIN_PASSWORD` | *(auto-generated)* | Dashboard login password (user is always `admin`) |
+| `ADMIN_EMAIL` | unset | Where signup-approval emails go (dashboard works without this) |
+| `APP_NAME` | `"My App"` | Used in email subjects |
+| `APP_URL` | `http://localhost:8000` | Public URL for magic links |
+| `EMAIL_TRANSPORT` | `console` | `console` (dev) or `smtp` |
+| `SMTP_HOST` / `_PORT` / `_USER` / `_PASSWORD` / `_FROM` | — | SMTP credentials if transport is `smtp` |
+| `RATELIMIT_SIGNUP` | `5/minute` | Per-IP signup limit |
+| `RATELIMIT_LOGIN` | `10/minute` | Per-IP login limit |
+| `DATABASE_URL` | `sqlite:///./parbaked.db` | Standard SQLAlchemy URL |
+
+Auto-generated secrets get persisted to `.parbaked.json` (chmod 600). In production, set them as env vars instead.
+
+## Security posture
+
+What protects you from a bill:
+
+- **Per-IP rate limits** on signup and login (slowapi)
+- **No email enumeration** — signup with an existing email and login with a wrong password return generic errors
+- **Approval gate** — even if someone gets past the rate limit, they can't do anything until you click approve
+- **bcrypt** for passwords, **HS256 JWT** for sessions, **audience-scoped JWT** for magic links so a session token can never be replayed as approval (and vice versa)
+
+What's on the roadmap (and isn't here yet):
+
+- **v0.3** — Deploy scaffolding: opinionated `Dockerfile`, `fly.toml` with `auto_stop_machines = "stop"` + hard max-machines cap, `make tunnel` recipe using `cloudflared tunnel --url http://localhost:8000` (no auth needed; ephemeral trycloudflare.com URL).
+- **v0.4** — Pluggable CAPTCHA on signup (Cloudflare Turnstile / hCaptcha).
+- **v0.5** — Resend / SendGrid / SES email transports.
+
+## React/TypeScript components
+
+Drop-in components for if you're building a React frontend. They ship as **source** in `src/parbaked/frontend/` — copy them into your `web/src/`:
+
+- `SignupForm.tsx`
+- `LoginForm.tsx`
+- `PendingScreen.tsx`
+
+Tailwind classes, no internal dependencies. See `src/parbaked/frontend/README.md`.
+
+## When you need more control
+
+The one-call `Parbaked(app)` is the simple case. If you want to wire pieces yourself:
+
+```python
+from parbaked import ParbakedConfig
+from parbaked.auth import build_auth_router, make_current_user
+from parbaked.email import ConsoleEmail
+from parbaked.ratelimit import install_rate_limiting
+
+config = ParbakedConfig(jwt_secret="...", admin_email="you@example.com")
+limiter = install_rate_limiting(app, config)
+app.include_router(
+    build_auth_router(config, get_session, ConsoleEmail(), limiter=limiter)
+)
+current_user = make_current_user(config, get_session)
+```
+
+Same building blocks, no smart defaults. Use this when you want a custom email transport, your own admin dashboard, or to wire parbaked into a non-trivial app structure.
+
+## Install
+
+```bash
+pip install parbaked
+# or
+uv add parbaked
+```
+
+Requires Python 3.11+.
+
+## Develop / contribute
+
+```bash
+git clone https://github.com/saml7n/parbaked
+cd parbaked
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest
+```
+
+Issues and PRs welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

parbaked-0.4.0/README.md

@@ -0,0 +1,168 @@
+# parbaked
+
+**A par-baked starter for FastAPI PoCs.** Signup with admin approval, rate limiting, and an admin dashboard — set up in one line.
+
+> If you ship PoCs on fly.io, two things eventually bite you: anyone on the internet can spin up accounts in a loop (and run up your bill), and you write the same auth boilerplate every time. parbaked is the slice between "I have an idea" and "this is safe to put online."
+
+## 30-second quickstart
+
+```bash
+uvx parbaked new myapp
+cd myapp
+make dev
+```
+
+Open `http://localhost:8000`, sign up. Open `http://localhost:8000/auth/admin` and log in as `admin` with the password printed in your terminal. Approve yourself. Log in. Done.
+
+You now have a working PoC with:
+
+- Signup + login + JWT sessions
+- Admin-approval gate (nobody gets in until you click approve)
+- Built-in admin dashboard with pending/active/rejected queues
+- Per-IP rate limiting (5/min signup, 10/min login by default)
+- SQLite DB and secrets auto-created on first run
+
+## Add to an existing FastAPI app
+
+```python
+from fastapi import FastAPI
+from parbaked import Parbaked
+
+app = FastAPI()
+parbaked = Parbaked(app)   # ← that's the whole setup
+```
+
+That gives you `/auth/signup`, `/auth/login`, `/auth/me`, `/auth/admin`, and approval magic links. On first boot you'll see:
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║  parbaked v0.2.0 is running                                    ║
+╠════════════════════════════════════════════════════════════════╣
+║  Sign up at:   http://localhost:8000/auth/signup               ║
+║  Admin panel:  http://localhost:8000/auth/admin                ║
+║  Admin user:   admin                                           ║
+║  Admin pass:   z703EwDKmEKL9S6SaO39uuRq                        ║
+║  Email out:    Console (printed below)                         ║
+║  Database:     sqlite:///./parbaked.db                         ║
+║                                                                ║
+║  ⚠ Auto-generated secrets stored in .parbaked.json             ║
+║    Add it to .gitignore. For prod, set env vars instead.       ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
+Protect your own routes:
+
+```python
+from fastapi import Depends
+
+@app.get("/profile")
+def profile(user = Depends(parbaked.current_user)):
+    return {"email": user.email, "name": user.name}
+```
+
+## Why an approval gate?
+
+Without one:
+
+- Anyone on the internet can sign up to your PoC
+- Even with rate limits, sustained traffic can autoscale you onto a bill
+- You can't show it to a friend without also showing it to bots
+
+With one:
+
+- Pending accounts can't log in. Period.
+- You see every signup. Click approve in your inbox or in the dashboard.
+- Bots can fill the database with junk, but they can't *do* anything — and rate limits cap the junk.
+
+The approval flow uses **HMAC-signed magic links** (no DB state) AND a **built-in web dashboard** (HTTP-basic-auth gated). Use whichever you prefer — email's nicer for low volume, the dashboard's nicer when you want to see the queue.
+
+## Configuration
+
+Everything has sensible defaults. Override via env vars (prefix `PARBAKED_`) or by passing args to `Parbaked()`:
+
+| Env var | Default | What it does |
+|---|---|---|
+| `JWT_SECRET` | *(auto-generated)* | Session token signing key |
+| `APPROVAL_TOKEN_SECRET` | *(auto-generated)* | Magic-link signing key |
+| `ADMIN_PASSWORD` | *(auto-generated)* | Dashboard login password (user is always `admin`) |
+| `ADMIN_EMAIL` | unset | Where signup-approval emails go (dashboard works without this) |
+| `APP_NAME` | `"My App"` | Used in email subjects |
+| `APP_URL` | `http://localhost:8000` | Public URL for magic links |
+| `EMAIL_TRANSPORT` | `console` | `console` (dev) or `smtp` |
+| `SMTP_HOST` / `_PORT` / `_USER` / `_PASSWORD` / `_FROM` | — | SMTP credentials if transport is `smtp` |
+| `RATELIMIT_SIGNUP` | `5/minute` | Per-IP signup limit |
+| `RATELIMIT_LOGIN` | `10/minute` | Per-IP login limit |
+| `DATABASE_URL` | `sqlite:///./parbaked.db` | Standard SQLAlchemy URL |
+
+Auto-generated secrets get persisted to `.parbaked.json` (chmod 600). In production, set them as env vars instead.
+
+## Security posture
+
+What protects you from a bill:
+
+- **Per-IP rate limits** on signup and login (slowapi)
+- **No email enumeration** — signup with an existing email and login with a wrong password return generic errors
+- **Approval gate** — even if someone gets past the rate limit, they can't do anything until you click approve
+- **bcrypt** for passwords, **HS256 JWT** for sessions, **audience-scoped JWT** for magic links so a session token can never be replayed as approval (and vice versa)
+
+What's on the roadmap (and isn't here yet):
+
+- **v0.3** — Deploy scaffolding: opinionated `Dockerfile`, `fly.toml` with `auto_stop_machines = "stop"` + hard max-machines cap, `make tunnel` recipe using `cloudflared tunnel --url http://localhost:8000` (no auth needed; ephemeral trycloudflare.com URL).
+- **v0.4** — Pluggable CAPTCHA on signup (Cloudflare Turnstile / hCaptcha).
+- **v0.5** — Resend / SendGrid / SES email transports.
+
+## React/TypeScript components
+
+Drop-in components for if you're building a React frontend. They ship as **source** in `src/parbaked/frontend/` — copy them into your `web/src/`:
+
+- `SignupForm.tsx`
+- `LoginForm.tsx`
+- `PendingScreen.tsx`
+
+Tailwind classes, no internal dependencies. See `src/parbaked/frontend/README.md`.
+
+## When you need more control
+
+The one-call `Parbaked(app)` is the simple case. If you want to wire pieces yourself:
+
+```python
+from parbaked import ParbakedConfig
+from parbaked.auth import build_auth_router, make_current_user
+from parbaked.email import ConsoleEmail
+from parbaked.ratelimit import install_rate_limiting
+
+config = ParbakedConfig(jwt_secret="...", admin_email="you@example.com")
+limiter = install_rate_limiting(app, config)
+app.include_router(
+    build_auth_router(config, get_session, ConsoleEmail(), limiter=limiter)
+)
+current_user = make_current_user(config, get_session)
+```
+
+Same building blocks, no smart defaults. Use this when you want a custom email transport, your own admin dashboard, or to wire parbaked into a non-trivial app structure.
+
+## Install
+
+```bash
+pip install parbaked
+# or
+uv add parbaked
+```
+
+Requires Python 3.11+.
+
+## Develop / contribute
+
+```bash
+git clone https://github.com/saml7n/parbaked
+cd parbaked
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest
+```
+
+Issues and PRs welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

parbaked-0.4.0/examples/README.md

@@ -0,0 +1,17 @@
+# parbaked examples
+
+Runnable, version-pinned examples. Each file is a complete FastAPI app — copy, paste, run.
+
+Run any of them with:
+
+```bash
+uv run uvicorn examples.<filename>:app --reload
+```
+
+| File | What it shows |
+|---|---|
+| [`minimal.py`](minimal.py) | The 4-line setup. Zero config. |
+| [`with_smtp.py`](with_smtp.py) | Real email via SMTP (Resend / SES / Gmail / anything). |
+| [`protected_routes.py`](protected_routes.py) | Using `parbaked.current_user` to gate your own routes. |
+| [`per_user_data.py`](per_user_data.py) | Adding a per-user table that joins on `users.id` — the right way to extend the schema. |
+| [`custom_emails.py`](custom_emails.py) | Overriding the email body copy without forking parbaked. |

parbaked-0.4.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "parbaked"
+version = "0.4.0"
+description = "A par-baked starter for PoC apps: signup-with-approval auth, rate limiting, and (soon) deploy scaffolding for fly.io"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Sam Leighton" }]
+requires-python = ">=3.11"
+keywords = ["fastapi", "auth", "starter", "scaffold", "fly.io", "poc"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "sqlmodel>=0.0.16",
+    "pydantic>=2.5",
+    "pydantic-settings>=2.1",
+    "bcrypt>=4.1",
+    "pyjwt>=2.8",
+    "slowapi>=0.1.9",
+    "email-validator>=2.1",
+    "typer>=0.12",
+    "jinja2>=3.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.27",
+    "ruff>=0.4",
+]
+
+[project.scripts]
+parbaked = "parbaked.cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/saml7n/parbaked"
+Repository = "https://github.com/saml7n/parbaked"
+Issues = "https://github.com/saml7n/parbaked/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/parbaked"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/parbaked", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+extend-safe-fixes = ["UP"]
+
+[tool.ruff.lint.flake8-bugbear]
+# These callables in default arguments are the canonical patterns for FastAPI
+# / Typer and are intentional, not a B008 bug.
+extend-immutable-calls = [
+    "fastapi.Depends",
+    "fastapi.Header",
+    "fastapi.Query",
+    "fastapi.Cookie",
+    "fastapi.Body",
+    "fastapi.Path",
+    "fastapi.File",
+    "fastapi.Form",
+    "typer.Argument",
+    "typer.Option",
+]

parbaked-0.4.0/src/parbaked/__init__.py

@@ -0,0 +1,20 @@
+"""parbaked — a par-baked starter for PoC apps.
+
+Public API re-exports the most commonly used pieces so consumers can do:
+
+    from parbaked import ParbakedConfig, auth_router, get_current_user
+"""
+
+__version__ = "0.4.0"
+
+from parbaked.app import Parbaked
+from parbaked.auth.deps import make_current_user
+from parbaked.auth.router import build_auth_router
+from parbaked.config import ParbakedConfig
+
+__all__ = [
+    "Parbaked",
+    "ParbakedConfig",
+    "build_auth_router",
+    "make_current_user",
+]