regstack 0.1.1__tar.gz → 0.2.1__tar.gz

{regstack-0.1.1 → regstack-0.2.1}/.github/workflows/publish.yml

@@ -30,7 +30,10 @@ jobs:
         run: |
           tag="${GITHUB_REF##*/}"            # e.g. v0.1.0
           tag_version="${tag#v}"             # e.g. 0.1.0
-          pkg_version=$(uv run python -c 'from regstack.version import __version__; print(__version__)')
+          # Read version from pyproject.toml directly — importing the package
+          # would pull in optional-extra dependencies (e.g. pymongo) that
+          # aren't installed in this build job.
+          pkg_version=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')
           if [ "$tag_version" != "$pkg_version" ]; then
             echo "Tag $tag does not match package version $pkg_version" >&2
             exit 1

regstack-0.2.1/.github/workflows/test.yml

@@ -0,0 +1,147 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    services:
+      mongodb:
+        image: mongo:7
+        ports:
+          - 27017:27017
+        options: >-
+          --health-cmd "mongosh --quiet --eval 'db.runCommand({ping:1}).ok' --port 27017"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+          --health-start-period 10s
+      postgres:
+        image: postgres:16
+        ports:
+          - 5432:5432
+        env:
+          POSTGRES_USER: regstack
+          POSTGRES_PASSWORD: regstack
+          POSTGRES_DB: regstack
+        options: >-
+          --health-cmd "pg_isready -U regstack"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+          --health-start-period 10s
+    env:
+      # Drives the parametrized backend fixture in tests/conftest.py.
+      # Connect as superuser so the per-test fixture can CREATE/DROP DATABASE.
+      REGSTACK_TEST_POSTGRES_URL: postgresql+asyncpg://regstack:regstack@localhost:5432
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Pin Python ${{ matrix.python-version }}
+        run: uv python pin ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --extra dev
+
+      - name: ruff check
+        run: uv run ruff check src tests
+
+      - name: ruff format check
+        run: uv run ruff format --check src tests
+
+      - name: pytest (parallel, all backends)
+        run: uv run python -m pytest -n auto --tb=short
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - run: uv python pin 3.11
+      - run: uv sync --extra docs --extra dev
+      - run: uv run sphinx-build -b html -W --keep-going docs docs/_build/html
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html
+
+  base-install-smoketest:
+    # Catches the kind of regression that broke 0.2.0: an unconditional
+    # `from bson import ...` (or any other optional-extra import) at module
+    # top level makes `import regstack` fail for any user who didn't opt
+    # into the `mongo` extra. The unit test of the same name exercises the
+    # equivalent in-process via meta_path blocking; this job verifies the
+    # actual built wheel installs and imports against a clean Python.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - run: uv python pin 3.11
+      - name: Build wheel
+        run: uv build --wheel
+      - name: Install wheel into a clean venv (no extras)
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --upgrade pip
+          /tmp/smoke/bin/pip install dist/regstack-*.whl
+      - name: Import smoketest
+        run: |
+          /tmp/smoke/bin/python -c "
+          import regstack
+          from regstack import RegStack, RegStackConfig
+          assert RegStack.__module__ == 'regstack.app'
+          print('ok', regstack.__version__)
+          "
+      - name: SQLite end-to-end smoketest
+        run: |
+          /tmp/smoke/bin/python <<'PY'
+          import asyncio, secrets, tempfile
+          from pathlib import Path
+          from regstack import RegStack, RegStackConfig
+          from regstack.models.user import BaseUser
+
+          async def main() -> None:
+              with tempfile.TemporaryDirectory() as td:
+                  cfg = RegStackConfig.load(
+                      toml_path=Path("/dev/null"),
+                      secrets_env_path=Path("/dev/null"),
+                      jwt_secret=secrets.token_urlsafe(64),
+                      database_url=f"sqlite+aiosqlite:///{td}/rs.db",
+                      require_verification=False,
+                      allow_registration=True,
+                      rate_limit_disabled=True,
+                  )
+                  rs = RegStack(config=cfg)
+                  await rs.install_schema()
+                  user = await rs.users.create(
+                      BaseUser(email="a@b.com", hashed_password="h", is_verified=True)
+                  )
+                  assert user.id
+                  await rs.aclose()
+                  print("sqlite ok")
+
+          asyncio.run(main())
+          PY

regstack-0.2.1/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. The
+authoritative copy lives at
+[`docs/changelog.md`](docs/changelog.md) and is rendered into the
+Sphinx docs.
+
+## 0.2.1 — 2026-04-28
+
+Hotfix for 0.2.0: `import regstack` failed on a base install because
+several modules in the import path (`models/_objectid.py`,
+`backends/protocols.py`, four routers, and the SQL `mfa_code_repo`)
+had unconditional `from bson …` / `from regstack.backends.mongo …`
+imports — but `pymongo` became an optional `mongo` extra in 0.2.0.
+Added a CI smoketest that builds the wheel and imports it in a
+no-extras venv, plus an in-process regression test that blocks `bson`
+/ `pymongo` via `sys.meta_path`.
+
+## 0.2.0 — 2026-04-28
+
+Multi-backend support — SQLite (default), Postgres, MongoDB — switched
+by `database_url` URL scheme. Bundled Alembic migrations for SQL
+backends. Embedding API change: `RegStack(config=, db=)` →
+`RegStack(config=, backend=None)`. README + core docs rewritten for
+less-expert readers (problem framing, hyperlinks to external
+standards, comparison vs Auth0/Clerk/Keycloak/fastapi-users).
+
+See [`docs/changelog.md`](docs/changelog.md) for the full per-feature
+breakdown.
+
+## 0.1.1 — 2026-04-27
+
+- Rewrite README relative links as absolute URLs so they resolve on the
+  PyPI project page. README-only release.
+
+## 0.1.0 — 2026-04-27
+
+First tagged release. Bundles M1–M6 from the development plan into a
+single Apache-2.0 package on PyPI.
+
+See [`docs/changelog.md`](docs/changelog.md) for the per-milestone
+breakdown of M1 through M6.

{regstack-0.1.1 → regstack-0.2.1}/CLAUDE.md

@@ -287,6 +287,30 @@ collections.** The full suite must pass under `pytest -n auto` reliably —
 flaky tests are bugs, not noise. Time-dependent assertions use the
 `frozen_clock` fixture, never `time.sleep` or wall-clock delays.
 
+### A test run that doesn't cover every backend is a failing test
+
+The whole point of the SQL + Mongo abstraction is parity. **Reporting
+"all tests passed" when the run only exercised one or two backends is a
+lie.** Treat any partial-backend run as red until it's been re-run
+across the full matrix.
+
+Concretely:
+
+- `inv test-sqlite` is fine for tight inner-loop iteration, but it is
+  **not** a release gate.
+- Before declaring a feature done — and definitely before merging /
+  tagging — run `inv test-all`, which exercises sqlite + mongo +
+  postgres in one go. Use `inv db-up` first to bring the local services
+  up if they aren't already (`inv db-status` reports what's running).
+- The CI matrix runs all three backends on every push. A green local
+  `inv test-sqlite` followed by a CI failure on `mongo` or `postgres`
+  is the failure pattern this rule exists to prevent.
+- A test that's `mongo`-only or `sqlite`-only by design must
+  short-circuit the parametrized fixture (see how
+  `tests/integration/test_indexes.py` does it with a local
+  `backend_kind = "mongo"` fixture override). Skipping silently because
+  a service isn't running doesn't count.
+
 ## Conventions
 
 - **Python 3.11+.** Use `from __future__ import annotations` in every module.

regstack-0.2.1/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: regstack
+Version: 0.2.1
+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
+Author-email: Joe Drumgoole <joe@joedrumgoole.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: auth,fastapi,mongodb,registration,users
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiosmtplib>=3.0
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: alembic>=1.13
+Requires-Dist: click>=8.1
+Requires-Dist: dnspython>=2.6
+Requires-Dist: email-validator>=2.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pwdlib[argon2]>=0.2.1
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyjwt>=2.8
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Provides-Extra: dev
+Requires-Dist: anyio>=4.3; extra == 'dev'
+Requires-Dist: asyncpg>=0.29; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: invoke>=2.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pymongo>=4.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.1; extra == 'docs'
+Requires-Dist: myst-parser>=3.0; extra == 'docs'
+Requires-Dist: sphinx-autobuild>=2024.4; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
+Requires-Dist: sphinx>=7.3; extra == 'docs'
+Provides-Extra: mongo
+Requires-Dist: pymongo>=4.9; extra == 'mongo'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: ses
+Requires-Dist: aioboto3>=12.3; extra == 'ses'
+Provides-Extra: sns
+Requires-Dist: aioboto3>=12.3; extra == 'sns'
+Provides-Extra: twilio
+Requires-Dist: twilio>=9.0; extra == 'twilio'
+Description-Content-Type: text/markdown
+
+# regstack
+
+[![CI](https://github.com/jdrumgoole/regstack/actions/workflows/test.yml/badge.svg)](https://github.com/jdrumgoole/regstack/actions/workflows/test.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/built%20with-FastAPI-009688.svg)](https://fastapi.tiangolo.com/)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://github.com/jdrumgoole/regstack/blob/main/LICENSE)
+
+**Production-grade user accounts for your [FastAPI](https://fastapi.tiangolo.com/)
+app — without the vendor lock-in, the second service to run, or the homegrown
+auth bugs.**
+
+`pip install regstack`, point it at SQLite (default), [PostgreSQL](https://www.postgresql.org/),
+or [MongoDB](https://www.mongodb.com/), and you have register / login /
+verify-email / reset-password / change-email / delete-account / optional SMS
+two-factor / admin endpoints / themable HTML pages — all behind a small Python
+API and one config file.
+
+📚 **Docs:** <https://regstack.readthedocs.io>
+&nbsp;·&nbsp;
+🧪 **Try it:** [`examples/sqlite`](https://github.com/jdrumgoole/regstack/tree/main/examples/sqlite)
+&nbsp;·&nbsp;
+🛡️ **Security model:** [security guide](https://regstack.readthedocs.io/en/latest/security.html)
+
+---
+
+## The problem regstack solves
+
+Every web application that has users eventually needs the same dozen
+endpoints: register, log in, log out, verify email, reset a forgotten
+password, change password, change email, delete account, list users for
+the admin panel, lock out brute-force attackers, and ideally a second
+factor. Every one of those endpoints has a well-known way to get
+subtly wrong:
+
+- **Password hashing.** Use [Argon2](https://en.wikipedia.org/wiki/Argon2)
+  (the [PHC winner](https://www.password-hashing.net/)), not MD5, SHA-1,
+  bcrypt-without-pepper, or — somehow still common — plain text.
+- **Token revocation.** A [JWT](https://datatracker.ietf.org/doc/html/rfc7519)
+  is signed and self-contained: the server can't "log it out" unless you
+  build a revocation list. Forget this and a stolen token works until it
+  expires.
+- **Account enumeration.** A login or password-reset endpoint that
+  responds differently for "user exists" vs "user doesn't" lets an
+  attacker harvest your customer list. See
+  [OWASP WSTG-IDNT-04](https://owasp.org/www-project-web-security-testing-guide/v42/4-Web_Application_Security_Testing/03-Identity_Management_Testing/04-Testing_for_Account_Enumeration_and_Guessable_User_Account).
+- **Bulk session invalidation.** When a user changes their password
+  because they think they were compromised, every existing token they
+  hold should stop working immediately. Most homegrown JWT layers don't
+  do this.
+- **One-time tokens.** Verification and password-reset tokens should be
+  random, hashed at rest, single-use, and expire fast. Storing the raw
+  token in the database is a "now your DB backup is also a credential
+  dump" mistake.
+- **Phone numbers.** SMS codes need [E.164](https://en.wikipedia.org/wiki/E.164)-validated
+  numbers, attempt limits, and an upstream provider. Wiring all of that
+  yourself for a single feature is rarely worth it.
+
+Doing all of these correctly, with tests, is two to four weeks of
+engineering for a competent team. Doing them once and embedding the
+result everywhere is what regstack is for.
+
+## What you get
+
+```
+✔ Email + password registration with email verification
+✔ JWT login (RFC 7519) with per-token revoke AND bulk revoke
+✔ Forgot / reset password — anti-enumeration: identical responses
+✔ Change password (revokes old tokens) / change email (re-verify)
+✔ Delete account
+✔ Optional SMS two-factor (TOTP-style 6-digit codes over SMS)
+✔ Server-side login lockout (HTTP 429 + Retry-After)
+✔ Admin endpoints (list / disable / delete users, stats)
+✔ 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 wizard (`regstack init`) and config validator (`regstack doctor`)
+✔ Three storage backends: SQLite, PostgreSQL, MongoDB — chosen by URL
+```
+
+Every feature is opt-in. Mount only the JSON router for a headless
+backend; flip `enable_ui_router` to also get the bundled SSR pages.
+Skip the SMS extras and you don't pull `twilio` or `aioboto3`.
+
+## Why not just use…?
+
+There are real alternatives. Here's why regstack might still be the
+right call.
+
+| Alternative | Why you might pick it | Why you might pick regstack instead |
+|---|---|---|
+| **[Auth0](https://auth0.com/) / [Clerk](https://clerk.com/) / [WorkOS](https://workos.com/) / [Stytch](https://stytch.com/)** (hosted SaaS) | Zero ops. Polished UI. Enterprise SSO out of the box. | Cost scales per-user. Your auth lives on someone else's servers. Your customer list is in their database. Vendor lock-in is real and migrations are painful. |
+| **[Keycloak](https://www.keycloak.org/) / [Authentik](https://goauthentik.io/) / [Authelia](https://www.authelia.com/) / [Ory Kratos](https://www.ory.sh/kratos/)** (self-hosted IAM) | Full identity platform. SAML, OIDC, federation. | A separate Java/Go service to run, monitor, back up, upgrade, and reason about. Heavyweight for "let users sign up". Schema lives outside your app. |
+| **[fastapi-users](https://fastapi-users.github.io/fastapi-users/)** | Same language, same framework. Good registration / login primitives. | Doesn't ship verification flows, anti-enumeration, bulk revoke, SMS MFA, admin endpoints, or themable pages — you build those. regstack is the longer tail. |
+| **Roll your own** | Total control. No dependency to learn. | You re-solve every bullet from "The problem" above, including the ones you didn't know existed yet. Two to four engineering weeks, then forever to maintain. |
+
+regstack's bet is that for most FastAPI apps the right answer is
+**embed a small Python library that owns the boring 80% correctly, and
+keep the user table in your own database** — not "stand up a separate
+auth product" and not "write the boring 80% from scratch each time".
+
+## 30-second start
+
+```bash
+git clone https://github.com/jdrumgoole/regstack && cd regstack
+uv sync --extra dev
+
+# Generate a JWT signing secret. SQLite is the default backend, no DB to install.
+export REGSTACK_JWT_SECRET=$(python -c 'import secrets; print(secrets.token_urlsafe(64))')
+
+uv run uvicorn examples.sqlite.main:app --reload
+```
+
+Then visit <http://localhost:8000/account/login> in your browser, or
+register from the command line:
+
+```bash
+curl -X POST http://localhost:8000/api/auth/register \
+    -H 'content-type: application/json' \
+    -d '{"email":"alice@example.com","password":"hunter2hunter2","full_name":"Alice"}'
+```
+
+The bundled example serves themed SSR pages at `/account/*`, prints
+verification / reset links and SMS codes to stdout (the `console`
+email/SMS backends), and shows how a host overrides regstack's default
+look by serving its own `theme.css`.
+
+Want PostgreSQL or MongoDB instead? Set `REGSTACK_DATABASE_URL` to a
+`postgresql+asyncpg://...` or `mongodb://...` URL and install the matching
+extra (`uv sync --extra postgres` or `uv sync --extra mongo`). The
+schema is created on first boot.
+
+## Embed in your own app
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from regstack import RegStack, RegStackConfig
+
+
+config = RegStackConfig.load()             # env vars + regstack.toml
+regstack = RegStack(config=config)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await regstack.install_schema()        # idempotent: runs migrations / creates indexes
+    yield
+    await regstack.aclose()
+
+
+app = FastAPI(lifespan=lifespan)
+app.include_router(regstack.router,    prefix=config.api_prefix)
+app.include_router(regstack.ui_router, prefix=config.ui_prefix)   # optional
+app.mount(config.static_prefix, regstack.static_files)            # optional
+```
+
+That is the whole integration. The rest of the surface area —
+extending the user model, registering hooks (`user_registered`,
+`password_reset`, …), supplying your own email service — is in the
+[embedding guide](https://regstack.readthedocs.io/en/latest/embedding.html).
+
+## Documentation
+
+| Page | What's there |
+|---|---|
+| [Quickstart](https://regstack.readthedocs.io/en/latest/quickstart.html) | Install, wizard, minimal embed |
+| [Configuration](https://regstack.readthedocs.io/en/latest/configuration.html) | Every `RegStackConfig` field, env vars, TOML layout |
+| [Architecture](https://regstack.readthedocs.io/en/latest/architecture.html) | Façade, backends, repos, hooks, lifecycle |
+| [Security model](https://regstack.readthedocs.io/en/latest/security.html) | Threat model, JWT scheme, anti-enumeration, MFA |
+| [Embedding](https://regstack.readthedocs.io/en/latest/embedding.html) | Custom backends, hooks, multi-tenant |
+| [Theming](https://regstack.readthedocs.io/en/latest/theming.html) | CSS variables, template overrides |
+| [CLI](https://regstack.readthedocs.io/en/latest/cli.html) | `init`, `create-admin`, `doctor` |
+| [API reference](https://regstack.readthedocs.io/en/latest/api.html) | Public types, generated from source |
+
+The same docs are also browsable as Markdown in [`docs/`](https://github.com/jdrumgoole/regstack/tree/main/docs).
+
+## Status
+
+Alpha. Single-file SQLite is the default and runs with no infrastructure;
+PostgreSQL and MongoDB backends pass the same parametrized integration
+suite. The next tagged release is `v0.2.0`. See the
+[changelog](https://regstack.readthedocs.io/en/latest/changelog.html)
+for the per-milestone breakdown.
+
+## Contributing
+
+Issues and pull requests welcome at
+<https://github.com/jdrumgoole/regstack>. Before opening a PR, please
+run the test suite and the linter — both should be green:
+
+```bash
+uv sync --extra dev
+uv run python -m invoke test-all   # SQLite + Mongo + Postgres in parallel
+uv run python -m invoke lint       # ruff + format check + mypy
+```
+
+`invoke test-sqlite` is the fast inner-loop variant that needs no
+database services. `invoke test-all` is what CI runs and what gates a
+release. Each pytest-xdist worker isolates its own database, so the
+full suite is safe to re-run while you iterate.
+
+Security disclosures: see [SECURITY.md](https://github.com/jdrumgoole/regstack/blob/main/SECURITY.md).
+
+## License
+
+[Apache License 2.0](https://github.com/jdrumgoole/regstack/blob/main/LICENSE) © 2026 Joe Drumgoole.