fastapi-startkit-auth 0.3.0__py3-none-any.whl

fastapi_startkit_auth-0.3.0.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: fastapi-startkit-auth
+Version: 0.3.0
+Summary: Laravel-style authentication for FastAPI: OAuth2/JWT authorization server, cookie/session guard, SPA + CSRF protection, and Sanctum-style API tokens.
+Keywords: fastapi,oauth2,jwt,auth,passport,sanctum,authentication,authorization,security,tokens,session,cookie,csrf,spa,starter-kit
+Author: Bedram Tamang
+Author-email: Bedram Tamang <tmgbedu@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pyjwt>=2.8
+Requires-Dist: bcrypt>=4.1
+Requires-Dist: pydantic>=2
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: masonite-orm>=2.18 ; extra == 'masoniteorm'
+Requires-Dist: fastapi-startkit>=0.51 ; python_full_version >= '3.12' and extra == 'startkit'
+Requires-Dist: pytest>=8 ; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23 ; extra == 'test'
+Requires-Dist: httpx>=0.27 ; extra == 'test'
+Requires-Python: >=3.9
+Project-URL: Homepage, https://github.com/fastapi-startkit/fastapi-startkit-auth
+Project-URL: Repository, https://github.com/fastapi-startkit/fastapi-startkit-auth
+Project-URL: Issues, https://github.com/fastapi-startkit/fastapi-startkit-auth/issues
+Project-URL: Changelog, https://github.com/fastapi-startkit/fastapi-startkit-auth/releases
+Provides-Extra: masoniteorm
+Provides-Extra: startkit
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# fastapi-startkit-auth
+
+Passport-style OAuth2 + JWT authentication for FastAPI.
+
+`fastapi-startkit-auth` brings the ergonomics of [Laravel Passport](https://laravel.com/docs/13.x/passport)
+to FastAPI: a config-driven guard/provider/passwords model layered on top of
+OAuth2 grants and signed JWT access tokens (per the
+[FastAPI security tutorial](https://fastapi.tiangolo.com/tutorial/security/oauth2-jwt/)).
+
+## Features
+
+| Area | What you get |
+| --- | --- |
+| **Config layer** | `AuthConfig` (`default` / `guards` / `providers` / `passwords`) + `AuthProvider` that registers into the app |
+| **Password grant** | OAuth2 password grant → signed JWT access tokens with expiry (`/oauth/token`, `/token`) |
+| **Refresh tokens** | Opaque refresh tokens with **rotation** and configurable TTL |
+| **Personal access tokens** | Named, long-lived tokens with scopes/abilities |
+| **Client credentials** | Machine-to-machine grant |
+| **Authorization code + PKCE** | Browser/SPA flow with S256 & plain PKCE |
+| **Clients** | Register / list / delete confidential & public clients |
+| **Revocation & introspection** | RFC 7009 revoke + RFC 7662 introspect |
+| **Password reset** | `password_reset_tokens` flow with configurable `expire` + `throttle` |
+| **Guards & deps** | `current_user`, `optional_user`, `require_scopes` FastAPI dependencies |
+| **Pluggable providers** | In-memory, generic ORM/masoniteorm model, or any custom `UserProvider` |
+
+## Installation
+
+```bash
+pip install fastapi-startkit-auth
+# optional ORM provider driver
+pip install "fastapi-startkit-auth[masoniteorm]"
+```
+
+> Uses `bcrypt` directly (not `passlib`, which imports the `crypt` stdlib module
+> removed in Python 3.13+), so it runs on modern Python.
+
+## Quickstart
+
+```python
+from fastapi import Depends
+from fastapi_startkit_auth import Application, AuthProvider, AuthConfig, current_user, require_scopes
+from myapp.models import User  # any active-record-style model
+
+
+class Config(AuthConfig):
+    key = "change-me-to-a-long-random-secret"   # JWT signing key
+
+    default = {"guard": "api", "passwords": "users"}
+    guards = {"api": {"driver": "passport", "provider": "users"}}
+    providers = {"users": {"driver": "masoniteorm", "model": User}}
+    passwords = {
+        "users": {"provider": "users", "table": "password_reset_tokens",
+                  "expire": 60, "throttle": 60},
+    }
+
+
+app = Application([(AuthProvider, Config)])
+api = app.api  # the underlying FastAPI instance
+
+
+@api.get("/me")
+def me(user=Depends(current_user)):
+    return user
+
+
+@api.get("/reports")
+def reports(ctx=Depends(require_scopes("reports:read"))):
+    return {"ok": True}
+```
+
+Serve it:
+
+```bash
+uvicorn myapp:app        # Application is ASGI-callable
+uvicorn myapp:app.api    # or serve the FastAPI instance directly
+```
+
+## Configuration
+
+`AuthConfig` mirrors Laravel's `config/auth.php` and adds JWT/token knobs:
+
+```python
+class AuthConfig:
+    default   = {"guard": "api", "passwords": "users"}
+    guards    = {"api": {"driver": "passport", "provider": "users"}}
+    providers = {"users": {"driver": "masoniteorm", "model": User}}
+    passwords = {"users": {"provider": "users", "table": "password_reset_tokens",
+                            "expire": 60, "throttle": 60}}
+
+    # token settings (all optional, sensible defaults shown)
+    key                        = None          # JWT secret (required in production)
+    algorithm                  = "HS256"
+    access_token_ttl           = 3600          # seconds
+    refresh_token_ttl          = 60 * 60 * 24 * 14
+    personal_access_token_ttl  = 60 * 60 * 24 * 365
+    authorization_code_ttl     = 600
+    bcrypt_rounds              = 12
+```
+
+### Provider drivers
+
+| driver | meaning |
+| --- | --- |
+| `masoniteorm` / `orm` / `model` | wrap a model exposing `find(id)` and `where(field, value).first()` |
+| `memory` | in-memory dict store (`users=[...]`) — great for tests/demos |
+| `instance` | pass a ready `UserProvider` via `{"instance": ...}` |
+| `factory` | pass a zero-arg callable returning a `UserProvider` |
+
+Any object implementing the `UserProvider` protocol
+(`retrieve_by_id`, `retrieve_by_credentials`, `validate_credentials`,
+`get_identifier`, `update_password`) is a valid provider.
+
+## HTTP endpoints
+
+| Method & path | Purpose |
+| --- | --- |
+| `POST /oauth/token` | Unified token endpoint: `password`, `refresh_token`, `client_credentials`, `authorization_code` |
+| `POST /token` | Simple password grant (FastAPI-tutorial style) |
+| `POST /oauth/authorize` | Approve an auth-code request (requires an authenticated user) → returns `code` |
+| `POST /oauth/introspect` | RFC 7662 token introspection (**requires client authentication**) |
+| `POST /oauth/revoke` | RFC 7009 access/refresh token revocation (**requires client authentication**) |
+| `POST/GET /oauth/clients`, `DELETE /oauth/clients/{id}` | Client registration & management |
+| `POST/GET /oauth/personal-access-tokens`, `DELETE .../{jti}` | Personal access tokens |
+| `POST /password/email` | Trigger a password-reset token (delivered out-of-band; see below) |
+| `POST /password/reset` | Reset the password with a token |
+
+### Password resets
+
+`POST /password/email` always returns the same generic response whether or not
+the account exists (no user enumeration) and **never** puts the token in the
+response body. Configure how the token reaches the user with a notifier:
+
+```python
+class AuthConfig(BaseAuthConfig):
+    password_reset_notifier = staticmethod(lambda email, token: send_email(email, token))
+    # debug_expose_reset_token = True   # DEV ONLY: echo the token in the response
+```
+
+The `code_challenge` for public clients is mandatory — a public (secretless)
+client cannot obtain an authorization code without PKCE, and codes are verified
+against the `code_verifier` at exchange.
+
+### Example: password grant
+
+```bash
+curl -X POST localhost:8000/oauth/token \
+  -d grant_type=password -d username=ada@example.com -d password=secret -d scope="read write"
+# → { "access_token": "...", "token_type": "Bearer", "expires_in": 3600,
+#     "refresh_token": "...", "scope": "read write" }
+```
+
+### Example: authorization code + PKCE
+
+1. `POST /oauth/authorize` with a bearer token and `code_challenge` → returns a single-use `code`.
+2. `POST /oauth/token` with `grant_type=authorization_code`, the `code`, and the `code_verifier`.
+
+## Scopes / abilities
+
+Tokens carry scopes; enforce them with the `require_scopes` dependency:
+
+```python
+require_scopes("posts:write")               # must have this scope
+require_scopes("a", "b")                     # must have all
+require_scopes("a", "b", mode="any")         # must have at least one
+```
+
+`*` is a wildcard scope that satisfies any check. Inside a handler you can also
+inspect the `AuthContext` (`ctx.can(...)`, `ctx.can_any(...)`, `ctx.scopes`).
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+## Releasing
+
+Releases are cut from `main` with the release script (maintainers only):
+
+```bash
+./bin/release.sh          # patch bump
+./bin/release.sh minor    # or: major
+```
+
+The script bumps the version, builds sdist + wheel, validates them with
+`twine check`, uploads to PyPI, then commits, tags `vX.Y.Z`, and creates a
+GitHub release. It requires `uv`, `gh` (authenticated), and PyPI credentials
+for `twine` (e.g. a `pypi-*` API token via `TWINE_USERNAME=__token__` /
+`TWINE_PASSWORD` or `~/.pypirc`).
+
+## License
+
+MIT

fastapi_startkit_auth-0.3.0.dist-info/RECORD

@@ -0,0 +1,57 @@
+fastapi_startkit_auth/__init__.py,sha256=1ypHry59Yyfl5xXbMVb2jbRnTwCVNmnwPOnaN29s7cM,3340
+fastapi_startkit_auth/apitokens/__init__.py,sha256=zsQKxwUaPQyohbKz5d70q30Gxo4bmEt-h90BY_W3IMM,363
+fastapi_startkit_auth/apitokens/manager.py,sha256=IQ38VzFmIuhBeCiWsy4CBcwv63cc1GfwM0LQqRqnWsQ,4419
+fastapi_startkit_auth/apitokens/models.py,sha256=_U2NbhxzGTeHnGnUQR4VeMsdlQ9DdbfruRzSkp1e7BI,918
+fastapi_startkit_auth/apitokens/repository.py,sha256=Il6M-MM4-n_jlYcX8kItC_1EmrV5HZ6LQKR_chT3TBE,3774
+fastapi_startkit_auth/apitokens/sql.py,sha256=Y8omXmW9xg0EKZobHhyoQCo7nXqWHxyhkyUAh5nvObI,4706
+fastapi_startkit_auth/application.py,sha256=NgO_6d66GBwOfGzYXrIr7sQ5YsL4t1DlG7K9ynYa3u4,1323
+fastapi_startkit_auth/clients/__init__.py,sha256=paTMVVVzZeqbRkMSLpDkVz4ZFNXLcPNKudKhao0h4xY,126
+fastapi_startkit_auth/clients/models.py,sha256=_6RWJsw6XwgE__dFnaN0lHdtE_EbUuCk9JhLyeFi89A,852
+fastapi_startkit_auth/clients/repository.py,sha256=bJS5FvqV7X3c8LVOvCBjoPYhSrRUfwbkszbhKXWgvgw,2194
+fastapi_startkit_auth/config.py,sha256=jGFz2GR40JfoP2kaX7YYVSgTvUZ-X8Y8pMsNkKsMx7I,4505
+fastapi_startkit_auth/dependencies.py,sha256=GkbuyM2gTf2GIc78d0hB2s30I_Av5tKklO53g7FgC-c,3304
+fastapi_startkit_auth/exceptions.py,sha256=z0yUnocN_95lvxVZhq5j85Uql1RY4n6yXHQZpsoqRCc,2255
+fastapi_startkit_auth/facade.py,sha256=n5A9frFBxikDTyoFlO6rXV7lC8vPBDHZLGiGeKXzDjI,3989
+fastapi_startkit_auth/grants/__init__.py,sha256=3oJFX3rN8yIxiT5CJEBCSG_IrCuPqSaDyF7AxXAedOk,355
+fastapi_startkit_auth/grants/authorization_code.py,sha256=RJv3uaritCA-0cLKBeTsOlxmPux_uv60UQNtnxutjTw,3208
+fastapi_startkit_auth/grants/client_credentials.py,sha256=KWP3OTMrGB5AkunpAPUwd5kfe7bXtNPnLO2AY0MyEao,577
+fastapi_startkit_auth/grants/password.py,sha256=z9Y0Us4nZIF_QQoZxQuWG72BuP3pKrJ4UtcPPh16OSs,1402
+fastapi_startkit_auth/grants/pkce.py,sha256=CWfdDWcdIIueYUsS_ZXelcI3o1TBSC4rOjTkYT4Exjg,867
+fastapi_startkit_auth/grants/refresh.py,sha256=k00kTBPRQVUqt1-lDxHyjK3wn2NbubGHI1gK7O2-8bw,454
+fastapi_startkit_auth/guards/__init__.py,sha256=jcIuIEsQZTjVW2b9UZVWvqUqHqUVvV_4exkdOjOWOUI,200
+fastapi_startkit_auth/guards/guard.py,sha256=JGx-k5dKii8E69F2A8wm7KjMgapoWfrISKsLH7l0GNA,2930
+fastapi_startkit_auth/guards/session.py,sha256=PBlBOulTY74znX3Bk4k2nHj4pkEfCHkaNuwzVPdNnd0,3326
+fastapi_startkit_auth/guards/token.py,sha256=cBfGHqNi_dgirE1ylA30hGHy714vv8_TW-tmzCBCLm0,2038
+fastapi_startkit_auth/manager.py,sha256=NFDE6X80lezs1IzgBmQY6z9yCFH07KIMbuO_XJdfoXs,13893
+fastapi_startkit_auth/middleware/__init__.py,sha256=IPU2ueWzRMMy8vqbzU8VLlCN-unh1S52iv-VIe8wrWk,123
+fastapi_startkit_auth/middleware/csrf.py,sha256=5zmz0UqS-VGBkTHNyMRWZ1829AplimMCh4VFcLsxd7I,6244
+fastapi_startkit_auth/middleware/session.py,sha256=gbqfcuIYbEDU1GSskKRUNk9ExDUQrjZysdG4C7-s8eY,4122
+fastapi_startkit_auth/passwords/__init__.py,sha256=rwG43cwCe_XK5MTIXgBS7QWHhgybvEUi8Pu6rtg5XfY,198
+fastapi_startkit_auth/passwords/broker.py,sha256=w5_Gpt8jsmhHbkDW58YGhVs24yykzoHgKZffuQeQO38,2929
+fastapi_startkit_auth/passwords/repository.py,sha256=y9Mx2TmJJ53mMOZZkiq861Mgo2wWNVdreViXEHEu-uE,1264
+fastapi_startkit_auth/provider.py,sha256=HYS11h7h_MV8lXoXA8F9exa7C7DF5acLiCw1Wbjb-bk,2708
+fastapi_startkit_auth/providers/__init__.py,sha256=yX-7Mv0nINduWBcDCQY0tNZ-Ei1FT-6xmiRZN3LNLek,124
+fastapi_startkit_auth/providers/base.py,sha256=Zt7PtHY0iWDyecbtz7kF-tO-SdIDg-99e_rvcmUYzI0,1488
+fastapi_startkit_auth/providers/memory.py,sha256=IRlBc2QZd_n4Y-2J5dKqD2xX6UAk3P6_f6c1NMIpj1E,2551
+fastapi_startkit_auth/providers/model.py,sha256=hplnIKX2xMbSzpsidKno3sgcLc57Wh9dUETMGdika-4,2425
+fastapi_startkit_auth/publishable/cors.py,sha256=rcgH4K7wGhFqM_pjk7aLfzUg60GVOZskEOS3AfJtty0,1415
+fastapi_startkit_auth/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_startkit_auth/routes.py,sha256=Vggj_VEYGecApgEl--7-dm2f1aDLMlhwEsvnkJML3uA,14352
+fastapi_startkit_auth/routes_spa.py,sha256=YSMoQOTU9BRDtcIcU8lc1YMXc3WfFEWtfszD7pWZiTg,1441
+fastapi_startkit_auth/security/__init__.py,sha256=djDbh1s-pHXxaSpzz4htxzfpDf5LFp4n9voK35mm2Hw,122
+fastapi_startkit_auth/security/hashing.py,sha256=DoNBte1krYbKmsgGxzmj3ozzrimYPByNv2FAESsco_U,1302
+fastapi_startkit_auth/security/jwt.py,sha256=HRUU5PFctewSFs3J3NvAYoJPcd15pHf4CgWCjNMNkP0,1568
+fastapi_startkit_auth/sessions/__init__.py,sha256=2itWqr2pE4c68jf5MurjB8O39UxdEalcaYHaS_gqXkY,209
+fastapi_startkit_auth/sessions/models.py,sha256=wS67vZCfmnAM-laO3P0Umh2GKb10fYgzNKDOMdiUk-0,964
+fastapi_startkit_auth/sessions/sql.py,sha256=YQhOL_WmvVvIO7upfYb8FbguSUU3PXzlI5wu_wIsuO0,5268
+fastapi_startkit_auth/sessions/state.py,sha256=YS71XVkbqeehgI5h6u8drVtcAAj8oOUWmbkKJugOhlo,499
+fastapi_startkit_auth/sessions/store.py,sha256=Rsm-vy5L8-ChNbm0FFtrmX6_aVO07cZsRyMGbMmIlsw,3365
+fastapi_startkit_auth/startkit.py,sha256=xy475PN3DMs0Lm3lwBmMfHT_UEzbW6xMxBj2fS2qI0U,1407
+fastapi_startkit_auth/tokens/__init__.py,sha256=I_lkDpM4FT753QGCuBLHnCnrarEoI-srRcM4FsRwrE8,247
+fastapi_startkit_auth/tokens/models.py,sha256=nb7MJ7XKr2Q38-0xR-o9DL3aBe2tg1J8Z0y1Zw6E-fA,1734
+fastapi_startkit_auth/tokens/repository.py,sha256=20mUrjsGKwM5iYusVTDGQxGs-kwuHfnQI-V3rxKeFWw,4266
+fastapi_startkit_auth/tokens/service.py,sha256=TCu6nUS_3AlVQbREee5CM-EGq_eA4wRDSQ3pt-VfSAg,6448
+fastapi_startkit_auth-0.3.0.dist-info/licenses/LICENSE,sha256=hzOerAuIkzIMJRcRsvB1ui45yso-JACJesM5TzO_PIQ,1073
+fastapi_startkit_auth-0.3.0.dist-info/WHEEL,sha256=GuAqCqoyQuys5_R4zkHUJFlKXw4RpRLNzo31-ui90WQ,81
+fastapi_startkit_auth-0.3.0.dist-info/METADATA,sha256=Hean_dpyS_NDd5UIVtjbFgWNs3RD4lWNA0D9D81ke_8,9519
+fastapi_startkit_auth-0.3.0.dist-info/RECORD,,

fastapi_startkit_auth-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.12
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_startkit_auth-0.3.0.dist-info/licenses/LICENSE

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