kantu-auth 0.1.0__tar.gz

kantu_auth-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local dev artifacts
+*.db
+.env
+.env.*
+!.env.example
+
+# Runtime service state
+dump.rdb
+
+frontend

kantu_auth-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to Kantu Auth are documented here. The project follows
+[Semantic Versioning](https://semver.org/) while its public API is pre-1.0.
+
+## [Unreleased]
+
+### Security
+
+- Validate proxy peers and forwarded IP chains with explicit trusted CIDRs.
+- Prevent account enumeration through duplicate registration responses.
+- Prevent implicit same-email Google account linking and linked-identity replacement.
+- Bind Google account-link state to the authorizing active session and make
+  concurrent link completion first-writer-wins.
+- Require authenticated, step-up-protected Google-only password setup.
+- Invalidate undelivered Google password-setup tokens and return a controlled
+  `503` for email import, configuration, delivery, or queueing failures.
+- Refresh verified provider emails only for passwordless Google-created
+  accounts, rejecting collisions without merging local identities.
+- Bind Google session-exchange tokens to the provider identity.
+- Revoke sessions and notify the account after Google unlinking.
+- Issue a fresh session ID for every authenticated login and serialize
+  same-user session mutations so revoked access tokens cannot be reactivated.
+- Rotate refresh tokens with a conditional database update so concurrent reuse
+  cannot produce two successful rotations.
+- Retry only SQLite lock conflicts during concurrent same-device login while
+  preserving fresh session IDs and surfacing unrelated database failures.
+- Use a consistent `User` → reset-token → session lock order for password
+  changes and resets, with conditional one-time reset-token consumption.
+- Require a recent, session-bound password or Google proof before unenrolled
+  users can enroll 2FA or perform sensitive Google account actions; enrolled
+  users must continue to use their 2FA step-up.
+- Fail closed for enrolled two-factor users when 2FA or Redis is unavailable.
+- Send verification and reset secrets in frontend URL fragments and support
+  body-based email-verification confirmation.
+
+### Added
+
+- Initial alpha version of the reusable FastAPI authentication package and
+  `kantu-auth init` application scaffold.
+- Dedicated Google login, exchange, password-setup, and linking rate limits.
+- Public `require_two_factor`, `require_sensitive_auth`, and
+  `require_google_only_user` dependencies.
+- Safe `google_linked` account state in user responses.
+- Python 3.11–3.14 continuous-integration matrix and distribution checks.
+
+### Removed
+
+- Removed the deprecated misspelled `fastapi_auth.adpters` compatibility
+  namespace; migrate imports to `fastapi_auth.adapters`.
+- Removed the undocumented `/auth/google/auth/add-password/request` alias; use
+  authenticated `POST /auth/google/password/request` with an empty JSON body.

kantu_auth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ukasha-hacks
+
+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.

kantu_auth-0.1.0/PKG-INFO

@@ -0,0 +1,468 @@
+Metadata-Version: 2.5
+Name: kantu-auth
+Version: 0.1.0
+Summary: Reusable authentication for FastAPI with secure sessions, email verification, two-factor authentication, and optional OAuth.
+Project-URL: Repository, https://github.com/ukasha-hacks/fastapi_auth
+Project-URL: Documentation, https://github.com/ukasha-hacks/fastapi_auth#readme
+Author: ukasha-hacks
+License: MIT License
+        
+        Copyright (c) 2026 ukasha-hacks
+        
+        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.
+License-File: LICENSE
+Keywords: authentication,fastapi,jwt,oauth,two-factor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.18.5
+Requires-Dist: bcrypt<4.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic[email]>=2.7
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30
+Requires-Dist: sqlmodel>=0.0.21
+Requires-Dist: typer>=0.15
+Provides-Extra: all
+Requires-Dist: aiosmtplib>=3.0; extra == 'all'
+Requires-Dist: aiosqlite>=0.20; extra == 'all'
+Requires-Dist: asyncpg>=0.29; extra == 'all'
+Requires-Dist: celery>=5.3; extra == 'all'
+Requires-Dist: cryptography>=42; extra == 'all'
+Requires-Dist: google-auth>=2.30; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: jinja2>=3.1; extra == 'all'
+Requires-Dist: pyotp>=2.9.0; extra == 'all'
+Requires-Dist: qrcode[pil]>=7.4; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: urllib3>=2.0; extra == 'all'
+Provides-Extra: celery
+Requires-Dist: aiosmtplib>=3.0; extra == 'celery'
+Requires-Dist: celery>=5.3; extra == 'celery'
+Requires-Dist: jinja2>=3.1; extra == 'celery'
+Provides-Extra: dev
+Requires-Dist: aiosmtplib>=3.0; extra == 'dev'
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: celery>=5.3; extra == 'dev'
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: fakeredis>=2.23; extra == 'dev'
+Requires-Dist: google-auth>=2.30; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: jinja2>=3.1; extra == 'dev'
+Requires-Dist: pyotp>=2.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: qrcode[pil]>=7.4; extra == 'dev'
+Requires-Dist: redis>=5.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=6.1; extra == 'dev'
+Requires-Dist: urllib3>=2.0; extra == 'dev'
+Provides-Extra: email
+Requires-Dist: aiosmtplib>=3.0; extra == 'email'
+Requires-Dist: jinja2>=3.1; extra == 'email'
+Provides-Extra: encryption
+Requires-Dist: cryptography>=42; extra == 'encryption'
+Provides-Extra: google
+Requires-Dist: aiosmtplib>=3.0; extra == 'google'
+Requires-Dist: google-auth>=2.30; extra == 'google'
+Requires-Dist: httpx>=0.27; extra == 'google'
+Requires-Dist: jinja2>=3.1; extra == 'google'
+Requires-Dist: redis>=5.0; extra == 'google'
+Requires-Dist: urllib3>=2.0; extra == 'google'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: qr
+Requires-Dist: qrcode[pil]>=7.4; extra == 'qr'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.20; extra == 'sqlite'
+Provides-Extra: turnstile
+Requires-Dist: httpx>=0.27; extra == 'turnstile'
+Provides-Extra: two-factor
+Requires-Dist: cryptography>=42; extra == 'two-factor'
+Requires-Dist: pyotp>=2.9.0; extra == 'two-factor'
+Requires-Dist: qrcode[pil]>=7.4; extra == 'two-factor'
+Requires-Dist: redis>=5.0; extra == 'two-factor'
+Description-Content-Type: text/markdown
+
+# Kantu Auth
+
+Kantu Auth is a reusable authentication package for FastAPI. It owns the
+authentication models, services, dependencies, and routers; your application
+owns its database engine, settings, migrations, and deployment.
+
+The package currently provides:
+
+- email/password registration and login;
+- short-lived access tokens and rotating refresh-token sessions;
+- session listing, per-session revocation, and logout-all;
+- password changes and one-time password-reset tokens;
+- optional email verification;
+- optional TOTP two-factor authentication, recovery codes, and email OTP;
+- optional Google OAuth login and account linking;
+- optional Redis-backed rate limiting;
+- optional Cloudflare Turnstile checks;
+- SMTP or custom email delivery, inline or through Celery; and
+- an application scaffold generated by `kantu-auth init`.
+
+> Kantu Auth is currently pre-1.0. Review the [security checklist](docs/security.md),
+> run your own threat model, and test the integration before using it in
+> production.
+
+## Install
+
+Install the package with only the features your application uses:
+
+```bash
+pip install "kantu-auth[sqlite,email]" uvicorn
+```
+
+For development from this repository:
+
+```bash
+git clone https://github.com/ukasha-hacks/fastapi_auth.git
+cd fastapi_auth
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+The distribution and command are named `kantu-auth`. The Python import remains
+`fastapi_auth` for compatibility during the pre-1.0 rename.
+
+### Optional dependencies
+
+| Extra | Use it for |
+| --- | --- |
+| `sqlite` | Async SQLite through `aiosqlite` |
+| `postgres` | Async PostgreSQL through `asyncpg` |
+| `redis` | Rate limiting and other Redis-backed features |
+| `email` | Jinja email templates and async SMTP |
+| `celery` | Queued email delivery; includes the email dependencies |
+| `qr` | QR data URLs returned by TOTP setup |
+| `encryption` | Encryption of stored TOTP secrets |
+| `two-factor` | Redis, QR generation, and TOTP-secret encryption; add `email` for emailed OTPs |
+| `turnstile` | Cloudflare Turnstile verification |
+| `google` | Google OAuth with PKCE; includes Redis and password-setup email support |
+| `all` | Every runtime integration |
+| `dev` | The local test toolchain |
+
+## Initialize an application
+
+From the root of a FastAPI project, run:
+
+```bash
+kantu-auth init
+```
+
+The command creates an integration you can edit and own:
+
+```text
+.
+├── .env.example
+├── KANTU_AUTH_SETUP.md
+└── app
+    ├── __init__.py
+    ├── main.py
+    ├── alembic.ini
+    ├── core
+    │   ├── __init__.py
+    │   ├── celery_app.py
+    │   ├── config.py
+    │   └── db.py
+    └── migrations
+        ├── README
+        ├── env.py
+        ├── script.py.mako
+        └── versions
+```
+
+Existing files are skipped. Use `--dest PATH` to target another directory and
+use `--force` only when you intentionally want to overwrite matching files:
+
+```bash
+kantu-auth init --dest ./my-api
+kantu-auth init --dest ./my-api --force
+```
+
+Then configure and start the generated app:
+
+```bash
+cp .env.example .env
+# Replace JWT_SECRET_KEY and review every enabled feature.
+
+alembic -c app/alembic.ini revision --autogenerate -m "init auth"
+alembic -c app/alembic.ini upgrade head
+uvicorn app.main:app --reload
+```
+
+The generated `.env` is read by the generated host `AppSettings`, so it uses
+ordinary names such as `DATABASE_URL` and `JWT_SECRET_KEY`. The host validates
+them and passes the relevant values to Kantu Auth.
+
+See [CLI and scaffold](docs/cli.md) for the generated-file contract and upgrade
+guidance.
+
+## Integrate without the scaffold
+
+Kantu Auth does not create or own a global database engine. Build your engine
+and session factory, configure the package, and inject the factory during app
+startup:
+
+```python
+import os
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from fastapi_auth import configure, get_auth_router, set_session_factory
+
+engine = create_async_engine("sqlite+aiosqlite:///./kantu.db")
+session_factory = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+configure(
+    APP_NAME="My API",
+    JWT_SECRET_KEY=os.environ["JWT_SECRET_KEY"],
+    FRONTEND_URL="http://localhost:3000",
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    set_session_factory(session_factory)
+    try:
+        yield
+    finally:
+        from fastapi_auth.redis_client import close_redis_client
+
+        await close_redis_client()
+        await engine.dispose()
+
+
+app = FastAPI(lifespan=lifespan)
+app.include_router(get_auth_router(), prefix="/api/v1")
+```
+
+Use Alembic migrations in deployed environments. Import the models in the
+Alembic environment before assigning `SQLModel.metadata` so autogeneration can
+see every auth table; the generated scaffold already does this.
+
+### Direct environment configuration
+
+If you do not call `configure()`, Kantu Auth reads its own values lazily from
+the environment with a `KANTU_AUTH_` prefix:
+
+```bash
+export KANTU_AUTH_JWT_SECRET_KEY="$(openssl rand -hex 32)"
+KANTU_AUTH_FRONTEND_URL=https://app.example.com
+KANTU_AUTH_REDIS_URL=redis://localhost:6379/0
+KANTU_AUTH_ENABLE_TWO_FACTOR=true
+```
+
+Programmatic `configure()` rejects unknown names, which catches misspelled
+security settings. See [configuration](docs/configuration.md) for every setting,
+unit, dependency, and feature prerequisite.
+
+## Authentication flow
+
+1. Register with `POST /auth/register`.
+2. If email verification is enabled, confirm the one-time link before login.
+3. Log in with `POST /auth/login`.
+4. If 2FA is disabled, the response contains access and refresh tokens. If 2FA
+   is enabled, it contains a short-lived challenge for
+   `POST /auth/two-factor/verify`.
+5. Send the access token as `Authorization: Bearer <token>`.
+6. Exchange the refresh token at `POST /auth/refresh`. Successful refreshes
+   rotate the token; replaying an older token revokes the session.
+
+Registration deliberately returns the same `201` response for a new or an
+existing email address. Do not make your frontend replace that neutral message
+with an account-existence error.
+
+All documented request bodies reject unknown fields. Passwords must be 8–128
+characters and satisfy the rules implemented in `fastapi_auth.validators`.
+
+The exact route catalogue and optional-router requirements are in
+[routes](docs/routes.md).
+
+### Protect a host-application route with recent authentication
+
+Kantu Auth exports its sensitive-action dependency for routes owned by your API:
+
+```python
+from typing import Annotated
+
+from fastapi import Depends
+from fastapi_auth import require_sensitive_auth
+from fastapi_auth.models import User
+
+
+@app.delete("/billing/account")
+async def delete_billing_account(
+    user: Annotated[User, Depends(require_sensitive_auth)],
+):
+    return {"deleted_for": user.id}
+```
+
+Enrolled users must first call `POST /auth/two-factor/validate`. Unenrolled
+users prove their current password at `POST /auth/reauth/password`, while
+Google-only users use `GET /auth/google/reauth/request`. Every proof is bound
+to the current session and expires quickly. Redis failures and contradictory
+disabled-feature configuration fail closed with `503`.
+
+The separate `require_two_factor` dependency remains available when a route
+should let unenrolled users pass without a recent primary-credential proof.
+
+## Optional features
+
+Optional routers are disabled by default and must be both installed and
+configured:
+
+```python
+import os
+
+configure(
+    JWT_SECRET_KEY=os.environ["JWT_SECRET_KEY"],
+    REDIS_URL="redis://localhost:6379/0",
+    ENABLE_TWO_FACTOR=True,
+    ENABLE_EMAIL_VERIFICATION=True,
+)
+
+app.include_router(get_auth_router())
+```
+
+Two-factor authentication, rate limiting, and Google OAuth rely on Redis for
+security state. Google OAuth also requires its client ID, client secret, and
+redirect URI. Turnstile requires its secret. Invalid feature combinations fail
+during settings validation or router construction rather than silently running
+partially configured.
+
+TOTP and recovery-code 2FA come from the `two-factor` extra. The optional
+`/auth/two-factor/send-otp` email path also needs the `email` extra, a sender,
+and working SMTP or a custom adapter.
+
+### Google login, linking, and password setup
+
+Install `kantu-auth[google]`, enable Google, configure email delivery, and set
+separate login and link callback URIs. Begin login with
+`POST /auth/google/login`, send the user to the returned URL, then exchange the
+callback's short `google_token` exactly once at `POST /auth/google/session`.
+
+Kantu Auth never links accounts merely because Google returns the same email.
+An existing user signs in locally and starts `GET /auth/google/link/request`
+with a Bearer token after satisfying the appropriate session-bound recent-auth
+proof. A linked identity cannot be silently replaced. Link state is bound to
+that active session, and concurrent callbacks cannot replace the first identity
+to complete.
+
+A passwordless Google user can request password setup only for their own
+authenticated account:
+
+```http
+POST /auth/google/password/request
+Authorization: Bearer <access-token>
+Content-Type: application/json
+
+{}
+```
+
+There is no target email field. The route is separately rate-limited and uses
+the authenticated account's email. If delivery or queueing fails, the setup
+token is invalidated and the route returns `503`. Unlinking Google requires a
+local password, revokes every session, and sends a security notification.
+
+### Reverse proxies
+
+Do not trust `X-Forwarded-For` from the public internet. Either leave
+`TRUST_PROXY_HEADERS=false` and configure Uvicorn's trusted forwarding peers,
+or set `TRUST_PROXY_HEADERS=true`, list exact `TRUSTED_PROXY_CIDRS`, and run
+Uvicorn with `--no-proxy-headers` so Kantu Auth can verify the socket peer.
+See [configuration](docs/configuration.md#reverse-proxies-and-client-ips).
+
+## Email delivery
+
+For SMTP delivery, install the email extra and configure a sender:
+
+```bash
+pip install "kantu-auth[email]"
+
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USERNAME=mailer
+SMTP_PASSWORD=replace-me
+SMTP_FROM_EMAIL=no-reply@example.com
+SMTP_FROM_NAME=My API
+SMTP_START_TLS=true
+SMTP_USE_TLS=false
+```
+
+Without a Celery broker, sending is awaited inline. With
+`CELERY_BROKER_URL`, messages are queued through the stable
+`fastapi_auth.send_email` task. Custom transports can implement the small
+`EmailAdapter` protocol; built-in templates can be selectively overridden.
+
+See [email adapters and templates](docs/email-adapters.md) for examples and
+worker setup.
+
+## Documentation
+
+- [CLI and generated scaffold](docs/cli.md)
+- [Configuration reference](docs/configuration.md)
+- [Routes and authentication flows](docs/routes.md)
+- [Email adapters and templates](docs/email-adapters.md)
+- [Security and production checklist](docs/security.md)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+python -m compileall -q src app
+python -m build
+python -m twine check dist/*
+```
+
+When changing a route or setting, update its focused document and tests in the
+same change. Do not commit `.env`, `.env.local`, database dumps, or generated
+tokens.
+
+## License
+
+Kantu Auth is available under the MIT License. See [LICENSE](LICENSE).