fastapi-djauth 1.4.0__tar.gz

fastapi_djauth-1.4.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.venv/
+*.sqlite3
+.pytest_cache/
+.ruff_cache/
+uv.lock

fastapi_djauth-1.4.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Cambios
+
+El formato sigue [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y el proyecto usa [versionado semántico](https://semver.org/lang/es/).
+
+## [1.4.0] - 2026-11-11
+
+Primera versión publicada en PyPI.
+
+### Corregido
+- **MySQL, Oracle y SQL Server:** agregar columnas propias (`user_mixin`) a una tabla existente fallaba porque los nombres iban entre comillas dobles y se usaba `ADD COLUMN` en todos los motores. Ahora se usan las comillas y la sintaxis de cada motor.
+- Un controlador asíncrono (`asyncpg`, `aiomysql`…) se rechaza al arrancar con un error claro, en lugar de fallar después. Ya no se elige `asyncpg` automáticamente.
+- **Oracle** no funcionaba: las claves primarias no se generaban (ahora usan `IDENTITY`) y los textos vacíos fallaban, porque Oracle guarda `''` como NULL. Ahora esos textos admiten NULL solo en Oracle y se leen como `''`, igual que hace Django.
+- Las claves primarias usan `IDENTITY` en PostgreSQL, Oracle y SQL Server para las tablas nuevas. Las tablas existentes no cambian.
+
+### Cambiado
+- Versión mínima de SQLAlchemy: 2.0.24, la primera que escapa `#` en las contraseñas al mostrar la URL de conexión.
+- El paquete declara sus tipos (`py.typed`) y pasa `mypy`.
+- Nuevos extras `mssql` (`pymssql`, sin dependencias del sistema) y `oracle` en las pistas de instalación.
+
+### Añadido
+- **Varias bases de datos y routers**, como `DATABASES` y `DATABASE_ROUTERS` de Django: `databases={...}` con alias, `database_routers=[...]` con `db_for_read`, `db_for_write`, `allow_relation` y `allow_migrate`, y `model._meta` con las mismas `app_label` de Django (los routers de Django funcionan tal cual). Sirve también para los modelos de la aplicación (`kit.databases`, `Databases`, `RoutingSession`). Ver [la guía](docs/17-varias-bases-y-routers.md).
+- Seguros de las varias bases: alias `READ_ONLY` que nunca reciben escrituras; contraseñas, sesiones y tokens validados siempre en la base de escritura; lectura y escritura en la misma base dentro de una sesión de escritura; claves foráneas entre bases y alias desconocidos rechazados al arrancar; `allow_relation` comprobado antes de guardar.
+- Guía de [bases de datos](docs/15-bases-de-datos.md): conexión y particularidades de cada motor.
+- CI con Python 3.11 a 3.14 en Linux, Windows y macOS, versiones mínimas de las dependencias, PostgreSQL, MySQL, Oracle y SQL Server reales, `mypy`, `bandit` y `pip-audit`.
+- `djauth startproject`: crea un proyecto FastAPI nuevo con arquitectura por capas, djauth integrado, Alembic, Docker, pruebas y CI; con las versiones probadas o las últimas. Ver [Nuevo proyecto](docs/16-nuevo-proyecto.md).
+- Publicación automática en TestPyPI y PyPI con *Trusted Publishing* y atestaciones firmadas.
+- `CONTRIBUTING.md`, plantillas de issues y de pull requests, Dependabot y `llms.txt`.
+
+## [1.3.0] - 2026-11-11
+
+### Añadido
+- **Historial de cambios del usuario** (tabla `auth_user_history`): cada alta, modificación (valor anterior y nuevo por campo), cambio de contraseña (sin valores) y eliminación, con quién lo hizo, cuándo, desde qué IP y el motivo. Se guarda en la misma transacción que el cambio y se conserva al eliminar el usuario. Solo cambios del usuario: inicios de sesión y demás acciones siguen en el registro general.
+- Rutas `GET /auth/api/user-history` y `GET /auth/api/users/{id}/history`, método `kit.user_history()` y permiso `auth.view_userchange`.
+- Motivo del cambio: `?reason=` en la API, `reason=` en `create_user`, `update_user`, `delete_user` y `set_password`, y un campo en el formulario de la administración.
+- Pestaña *Cambios de usuarios* en la administración.
+- Campos sensibles: `info={"sensitive": True}` en columnas propias y `ExtraField(..., sensitive=True)` registran que cambiaron, sin los valores.
+- Opción `user_history` para desactivarlo.
+
+### Cambiado
+- Los mensajes de error de la conexión a la base sugieren los nombres cortos de motor (`postgresql`, `mysql`…).
+
+## [1.2.0] - 2026-11-10
+
+### Añadido
+- Decoradores `@login_required`, `@permission_required`, `@staff_member_required`, `@superuser_required` y `@user_passes_test`, además de las dependencias `current_user`, `require_perm`, etc.
+
+### Cambiado
+- Los ejemplos usan los nombres cortos de motor (`"ENGINE": "postgresql"`) y ya no dan a entender que hace falta Django. Los nombres de Django se siguen aceptando.
+
+## [1.1.0] - 2026-11-10
+
+### Añadido
+- **Backends de autenticación** (`authentication_backends`), el equivalente de `AUTHENTICATION_BACKENDS` de Django: `ModelBackend`, `AllowAllUsersModelBackend` y `BaseBackend` para escribir los suyos (LDAP, otros sistemas, otras credenciales). Permisos sumados de todos los backends.
+- **Extender el usuario con columnas reales** (`user_mixin`), como `AbstractUser`: aparecen en la API y en la administración, se leen como `user.campo`, y las columnas nuevas se agregan solas a la tabla.
+- **Errores descriptivos**: todas las respuestas llevan `detail`, `code`, `hint` y `errors` por campo; los errores de formato se traducen al español (`422`).
+- **`DATABASES` de Django** (`database={"ENGINE": …, "NAME": …}`): conexión sin escribir la URL, con contraseñas escapadas y elección automática del controlador instalado. Conexiones verificadas antes de usarse.
+- **`username_field`**, el equivalente de `USERNAME_FIELD`: iniciar sesión con el usuario o con el correo (único, sin distinguir mayúsculas, garantizado por la base).
+- Documentación por temas en `docs/`.
+
+### Seguridad
+- Un WebSocket autenticado con cookie debe abrirse desde el mismo origen (evita el secuestro de WebSocket entre sitios, CSWSH).
+- Un administrador que no es superusuario ya no puede modificar ni cambiar la contraseña de usuarios con permisos que él no tiene.
+- El inicio de sesión rechaza peticiones con `Origin` de otro sitio aunque aún no haya cookie.
+- La cookie de sesión se marca `Secure` automáticamente cuando la petición llega por HTTPS.
+
+## [1.0.0] - 2026-11-10
+
+### Añadido
+- Usuarios, grupos (roles) y permisos con el modelo de `django.contrib.auth`.
+- Autenticación por sesión (cookie) o token Bearer opaco y revocable.
+- Administración web, inicio de sesión, "Mi cuenta" y restablecimiento de contraseña.
+- Contraseñas PBKDF2-SHA256 compatibles con Django.
+- Comandos `createsuperuser`, `changepassword` y `listusers`.

fastapi_djauth-1.4.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contribuir a fastapi-djauth
+
+Gracias por querer mejorar el paquete. Esta guía explica cómo preparar el entorno, qué se comprueba en cada cambio y cómo se publica una versión.
+
+## Preparar el entorno
+
+Requiere Python 3.11 o superior. Con [uv](https://docs.astral.sh/uv/) (recomendado):
+
+```bash
+git clone https://github.com/carlosvisbal/fastapi-djauth.git && cd fastapi-djauth
+uv venv && uv pip install -e ".[test]"
+```
+
+O con `pip`: `python -m venv .venv && . .venv/bin/activate && pip install -e ".[test]"`.
+
+## Comprobaciones
+
+Son las mismas que ejecuta la CI en cada pull request:
+
+```bash
+pytest                                        # pruebas
+uvx ruff check djauth tests examples          # errores y estilo
+uvx ruff format --check djauth tests examples # formato
+uvx mypy                                      # tipos
+uvx bandit -q -r djauth                       # análisis de seguridad del código
+```
+
+### Contra PostgreSQL y MySQL reales
+
+Las pruebas usan SQLite. `tests/test_engines.py` repite el flujo principal contra motores reales cuando se le indican:
+
+```bash
+docker run -d --name pg -e POSTGRES_USER=djauth -e POSTGRES_PASSWORD=djauth -e POSTGRES_DB=djauth -p 5432:5432 postgres:17-alpine
+docker run -d --name my -e MYSQL_ROOT_PASSWORD=root -e MYSQL_USER=djauth -e MYSQL_PASSWORD=djauth -e MYSQL_DATABASE=djauth -p 3306:3306 mysql:8.4
+uv pip install -e ".[test,postgres,mysql]"
+
+DJAUTH_TEST_DATABASE_URLS="postgresql+psycopg://djauth:djauth@127.0.0.1:5432/djauth mysql+pymysql://djauth:djauth@127.0.0.1:3306/djauth" \
+  pytest tests/test_engines.py -v
+```
+
+## Qué se espera de un cambio
+
+- **Pruebas:** toda función nueva o error corregido lleva su prueba.
+- **Documentación:** si cambia algo visible, actualice `docs/`, el README y `CHANGELOG.md` (sección "Sin publicar").
+- **Idioma:** la documentación, los mensajes y los comentarios están en español.
+- **Seguridad:** no se aceptan cambios que debiliten las protecciones por defecto (contraseñas, sesiones, CSRF, escalada de privilegios). Si su cambio toca autenticación, sesiones, permisos o datos personales, explique en el pull request su impacto en la seguridad.
+- **Compatibilidad:** se sigue [versionado semántico](https://semver.org/lang/es/). Un cambio que rompa la API pública espera a la siguiente versión mayor.
+
+Las fallas de seguridad **no** se informan en un issue: vea [SECURITY.md](SECURITY.md).
+
+## Publicar una versión (mantenedores)
+
+1. Actualice `__version__` en `djauth/__init__.py`. Es la única fuente de la versión.
+2. Pase las notas de "Sin publicar" en `CHANGELOG.md` a la versión nueva, con la fecha.
+3. Haga commit en `main` y espere a que la CI quede en verde.
+4. Cree la Release en GitHub con la etiqueta `vX.Y.Z`:
+
+   ```bash
+   gh release create vX.Y.Z --title "vX.Y.Z" --notes "Ver CHANGELOG.md"
+   ```
+
+El flujo `publish.yml` comprueba que la etiqueta coincida con la versión y construye el paquete. Luego lo publica en TestPyPI y después en PyPI, este último con aprobación manual en el entorno `pypi`. Al final adjunta los archivos a la Release. No hacen falta contraseñas ni tokens (*Trusted Publishing*).

fastapi_djauth-1.4.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 CARLOS DANIEL VISBAL ATENCIA
+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.

fastapi_djauth-1.4.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: fastapi-djauth
+Version: 1.4.0
+Summary: Usuarios, roles, permisos y administración para FastAPI: sesión o token Bearer, seguro por defecto.
+Project-URL: Homepage, https://github.com/carlosvisbal/fastapi-djauth
+Project-URL: Documentation, https://github.com/carlosvisbal/fastapi-djauth/tree/main/docs
+Project-URL: Changelog, https://github.com/carlosvisbal/fastapi-djauth/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/carlosvisbal/fastapi-djauth/issues
+Project-URL: Source, https://github.com/carlosvisbal/fastapi-djauth
+Project-URL: Security, https://github.com/carlosvisbal/fastapi-djauth/security/policy
+Author: Carlos Daniel Visbal Atencia
+Maintainer: Carlos Daniel Visbal Atencia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: admin,audit,auth,authentication,authorization,bearer,django,fastapi,permissions,rbac,roles,session,users
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Spanish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Session
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic<3.0,>=2.5
+Requires-Dist: sqlalchemy<3.0,>=2.0.24
+Provides-Extra: mssql
+Requires-Dist: pymssql>=2.3; extra == 'mssql'
+Provides-Extra: mysql
+Requires-Dist: pymysql[rsa]>=1.1; extra == 'mysql'
+Provides-Extra: oracle
+Requires-Dist: oracledb>=2.0; extra == 'oracle'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# fastapi-djauth
+
+[![PyPI](https://img.shields.io/pypi/v/fastapi-djauth)](https://pypi.org/project/fastapi-djauth/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-djauth)](https://pypi.org/project/fastapi-djauth/)
+[![CI](https://github.com/carlosvisbal/fastapi-djauth/actions/workflows/ci.yml/badge.svg)](https://github.com/carlosvisbal/fastapi-djauth/actions/workflows/ci.yml)
+[![Tipado](https://img.shields.io/badge/tipado-mypy-blue)](https://github.com/carlosvisbal/fastapi-djauth/blob/main/pyproject.toml)
+[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-green)](https://github.com/carlosvisbal/fastapi-djauth/blob/main/LICENSE)
+
+**Usuarios, roles, permisos y administración para FastAPI.** Sesión por cookie o token Bearer, una vista de administración lista, y la seguridad resuelta.
+
+```python
+from fastapi import Depends, FastAPI
+from djauth import AuthKit, AuthSettings, AuthUser, require_perm
+
+kit = AuthKit(AuthSettings(
+    database={"ENGINE": "postgresql", "NAME": "miapp", "USER": "app", "PASSWORD": "…", "HOST": "localhost"},
+    permissions={"ventas": {"aprobar_pedido": "Puede aprobar pedidos"}},
+)).init()
+
+app = FastAPI()
+
+@app.post("/pedidos/{id}/aprobar")
+def aprobar(id: int, user: AuthUser = Depends(require_perm("ventas.aprobar_pedido"))):
+    return {"aprobado_por": user.username}
+
+kit.install(app)   # API en /auth/api y páginas: /auth/login, /auth/admin, /auth/account
+```
+
+## Qué trae
+
+- **Usuarios, grupos (roles) y permisos** `app.codename`, con `user.has_perm()`, decoradores (`@login_required`, `@permission_required`) o dependencias.
+- **Configurable sin código extra:** conexión a la base por diccionario, inicio de sesión con usuario o con correo, backends de autenticación propios (LDAP, otros sistemas) y columnas propias en el usuario.
+- **Sesión o Bearer:** cookie `HttpOnly` para navegadores, tokens opacos y revocables para APIs; uno, otro o los dos.
+- **Administración web:** usuarios, grupos, permisos y registro de acciones; inicio de sesión, "Mi cuenta" y restablecimiento de contraseña.
+- **Historial de cambios del usuario:** cada alta, modificación (valor anterior y nuevo por campo), cambio de contraseña y baja, con quién, cuándo, desde qué IP y por qué. Nunca guarda contraseñas.
+- **Seguro por defecto:** contraseñas PBKDF2-SHA256, bloqueo por fuerza bruta, CSRF, protección de WebSocket, sin escalada de privilegios entre administradores, cabeceras de seguridad.
+- **Errores descriptivos:** cada error trae mensaje, código fijo, campo afectado y cómo resolverlo.
+- **Cualquier base:** SQLite, PostgreSQL, MySQL/MariaDB, Oracle o SQL Server (SQLAlchemy 2), probadas contra servidores reales en cada cambio.
+- **Varias bases y routers:** `databases` y `database_routers`, como `DATABASES` y `DATABASE_ROUTERS` de Django: réplicas de lectura o una base por área, también para sus propios modelos.
+- **Plantilla de proyecto:** `djauth startproject` crea una aplicación nueva lista para producción.
+
+## Proyecto nuevo en un minuto
+
+```bash
+pip install fastapi-djauth
+djauth startproject inventario --db postgresql
+```
+
+Crea una aplicación FastAPI completa con arquitectura por capas, usuarios y permisos, Alembic, Docker, pruebas y CI. Usted elige las versiones probadas o las últimas de cada librería. Ver [Proyecto nuevo](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/16-nuevo-proyecto.md).
+
+## Instalación
+
+```bash
+pip install fastapi-djauth                      # PyPI
+pip install "fastapi-djauth[postgres]"          # con el controlador de PostgreSQL
+pip install "git+https://github.com/carlosvisbal/fastapi-djauth.git"   # última versión de GitHub
+```
+
+Requiere Python 3.11+.
+
+## Documentación
+
+| | |
+|---|---|
+| **Empezar** | [Proyecto nuevo](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/16-nuevo-proyecto.md) · [Instalación y primer uso](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/01-instalacion.md) · [Configuración](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/02-configuracion.md) · [Bases de datos](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/15-bases-de-datos.md) · [Desde Django](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/13-desde-django.md) |
+| **Usar** | [Proteger rutas](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/03-proteger-rutas.md) · [Sesión o Bearer](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/04-sesion-y-bearer.md) · [Usuarios, grupos y permisos](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/05-usuarios-grupos-permisos.md) |
+| **Personalizar** | [Varias bases y routers](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/17-varias-bases-y-routers.md) · [Backends de autenticación](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/06-backends.md) · [Extender el usuario](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/07-extender-usuario.md) |
+| **Operar** | [Administración web](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/08-administracion.md) · [Historial de cambios](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/14-historial-de-cambios.md) · [Comandos](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/11-comandos.md) · [Seguridad](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/10-seguridad.md) |
+| **Referencia** | [API REST](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/12-api.md) · [Errores](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/09-errores.md) · [Cambios](https://github.com/carlosvisbal/fastapi-djauth/blob/main/CHANGELOG.md) |
+
+¿Viene de Django? Los conceptos y la configuración le resultarán familiares, y puede importar sus usuarios con su contraseña: vea [Desde Django](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/13-desde-django.md). El paquete **no** necesita Django instalado.
+
+Hay un ejemplo completo en [examples/app.py](https://github.com/carlosvisbal/fastapi-djauth/blob/main/examples/app.py).
+
+## Seguridad
+
+Lea [docs/10-seguridad.md](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/10-seguridad.md) antes de poner el servicio en producción. Para informar una vulnerabilidad, use el aviso privado de GitHub ([SECURITY.md](https://github.com/carlosvisbal/fastapi-djauth/blob/main/SECURITY.md)), no un issue público.
+
+## Contribuir
+
+Las contribuciones son bienvenidas. Vea [CONTRIBUTING.md](https://github.com/carlosvisbal/fastapi-djauth/blob/main/CONTRIBUTING.md): cómo preparar el entorno, las pruebas (también contra PostgreSQL y MySQL reales) y el proceso de publicación.
+
+## Licencia
+
+[MIT](https://github.com/carlosvisbal/fastapi-djauth/blob/main/LICENSE) © Carlos Daniel Visbal Atencia

fastapi_djauth-1.4.0/README.md

@@ -0,0 +1,85 @@
+# fastapi-djauth
+
+[![PyPI](https://img.shields.io/pypi/v/fastapi-djauth)](https://pypi.org/project/fastapi-djauth/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-djauth)](https://pypi.org/project/fastapi-djauth/)
+[![CI](https://github.com/carlosvisbal/fastapi-djauth/actions/workflows/ci.yml/badge.svg)](https://github.com/carlosvisbal/fastapi-djauth/actions/workflows/ci.yml)
+[![Tipado](https://img.shields.io/badge/tipado-mypy-blue)](https://github.com/carlosvisbal/fastapi-djauth/blob/main/pyproject.toml)
+[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-green)](https://github.com/carlosvisbal/fastapi-djauth/blob/main/LICENSE)
+
+**Usuarios, roles, permisos y administración para FastAPI.** Sesión por cookie o token Bearer, una vista de administración lista, y la seguridad resuelta.
+
+```python
+from fastapi import Depends, FastAPI
+from djauth import AuthKit, AuthSettings, AuthUser, require_perm
+
+kit = AuthKit(AuthSettings(
+    database={"ENGINE": "postgresql", "NAME": "miapp", "USER": "app", "PASSWORD": "…", "HOST": "localhost"},
+    permissions={"ventas": {"aprobar_pedido": "Puede aprobar pedidos"}},
+)).init()
+
+app = FastAPI()
+
+@app.post("/pedidos/{id}/aprobar")
+def aprobar(id: int, user: AuthUser = Depends(require_perm("ventas.aprobar_pedido"))):
+    return {"aprobado_por": user.username}
+
+kit.install(app)   # API en /auth/api y páginas: /auth/login, /auth/admin, /auth/account
+```
+
+## Qué trae
+
+- **Usuarios, grupos (roles) y permisos** `app.codename`, con `user.has_perm()`, decoradores (`@login_required`, `@permission_required`) o dependencias.
+- **Configurable sin código extra:** conexión a la base por diccionario, inicio de sesión con usuario o con correo, backends de autenticación propios (LDAP, otros sistemas) y columnas propias en el usuario.
+- **Sesión o Bearer:** cookie `HttpOnly` para navegadores, tokens opacos y revocables para APIs; uno, otro o los dos.
+- **Administración web:** usuarios, grupos, permisos y registro de acciones; inicio de sesión, "Mi cuenta" y restablecimiento de contraseña.
+- **Historial de cambios del usuario:** cada alta, modificación (valor anterior y nuevo por campo), cambio de contraseña y baja, con quién, cuándo, desde qué IP y por qué. Nunca guarda contraseñas.
+- **Seguro por defecto:** contraseñas PBKDF2-SHA256, bloqueo por fuerza bruta, CSRF, protección de WebSocket, sin escalada de privilegios entre administradores, cabeceras de seguridad.
+- **Errores descriptivos:** cada error trae mensaje, código fijo, campo afectado y cómo resolverlo.
+- **Cualquier base:** SQLite, PostgreSQL, MySQL/MariaDB, Oracle o SQL Server (SQLAlchemy 2), probadas contra servidores reales en cada cambio.
+- **Varias bases y routers:** `databases` y `database_routers`, como `DATABASES` y `DATABASE_ROUTERS` de Django: réplicas de lectura o una base por área, también para sus propios modelos.
+- **Plantilla de proyecto:** `djauth startproject` crea una aplicación nueva lista para producción.
+
+## Proyecto nuevo en un minuto
+
+```bash
+pip install fastapi-djauth
+djauth startproject inventario --db postgresql
+```
+
+Crea una aplicación FastAPI completa con arquitectura por capas, usuarios y permisos, Alembic, Docker, pruebas y CI. Usted elige las versiones probadas o las últimas de cada librería. Ver [Proyecto nuevo](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/16-nuevo-proyecto.md).
+
+## Instalación
+
+```bash
+pip install fastapi-djauth                      # PyPI
+pip install "fastapi-djauth[postgres]"          # con el controlador de PostgreSQL
+pip install "git+https://github.com/carlosvisbal/fastapi-djauth.git"   # última versión de GitHub
+```
+
+Requiere Python 3.11+.
+
+## Documentación
+
+| | |
+|---|---|
+| **Empezar** | [Proyecto nuevo](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/16-nuevo-proyecto.md) · [Instalación y primer uso](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/01-instalacion.md) · [Configuración](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/02-configuracion.md) · [Bases de datos](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/15-bases-de-datos.md) · [Desde Django](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/13-desde-django.md) |
+| **Usar** | [Proteger rutas](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/03-proteger-rutas.md) · [Sesión o Bearer](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/04-sesion-y-bearer.md) · [Usuarios, grupos y permisos](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/05-usuarios-grupos-permisos.md) |
+| **Personalizar** | [Varias bases y routers](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/17-varias-bases-y-routers.md) · [Backends de autenticación](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/06-backends.md) · [Extender el usuario](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/07-extender-usuario.md) |
+| **Operar** | [Administración web](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/08-administracion.md) · [Historial de cambios](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/14-historial-de-cambios.md) · [Comandos](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/11-comandos.md) · [Seguridad](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/10-seguridad.md) |
+| **Referencia** | [API REST](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/12-api.md) · [Errores](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/09-errores.md) · [Cambios](https://github.com/carlosvisbal/fastapi-djauth/blob/main/CHANGELOG.md) |
+
+¿Viene de Django? Los conceptos y la configuración le resultarán familiares, y puede importar sus usuarios con su contraseña: vea [Desde Django](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/13-desde-django.md). El paquete **no** necesita Django instalado.
+
+Hay un ejemplo completo en [examples/app.py](https://github.com/carlosvisbal/fastapi-djauth/blob/main/examples/app.py).
+
+## Seguridad
+
+Lea [docs/10-seguridad.md](https://github.com/carlosvisbal/fastapi-djauth/blob/main/docs/10-seguridad.md) antes de poner el servicio en producción. Para informar una vulnerabilidad, use el aviso privado de GitHub ([SECURITY.md](https://github.com/carlosvisbal/fastapi-djauth/blob/main/SECURITY.md)), no un issue público.
+
+## Contribuir
+
+Las contribuciones son bienvenidas. Vea [CONTRIBUTING.md](https://github.com/carlosvisbal/fastapi-djauth/blob/main/CONTRIBUTING.md): cómo preparar el entorno, las pruebas (también contra PostgreSQL y MySQL reales) y el proceso de publicación.
+
+## Licencia
+
+[MIT](https://github.com/carlosvisbal/fastapi-djauth/blob/main/LICENSE) © Carlos Daniel Visbal Atencia

fastapi_djauth-1.4.0/SECURITY.md

@@ -0,0 +1,23 @@
+# Política de seguridad
+
+## Versiones con soporte
+
+| Versión | Soporte |
+|---|---|
+| 1.3.x | Sí |
+| < 1.3 | No: actualice a la última versión (1.1.0 corrigió el secuestro de WebSocket entre sitios) |
+
+## Informar una vulnerabilidad
+
+**No abra un issue público.** Use el aviso privado de GitHub: pestaña **Security → Report a vulnerability** en https://github.com/carlosvisbal/fastapi-djauth/security/advisories/new
+
+Incluya, si puede: versión afectada, pasos para reproducirlo y el impacto. Recibirá respuesta en un plazo de 7 días. Una vez corregido, se publica una versión nueva y un aviso con el crédito a quien lo informó (si lo desea).
+
+Lo que protege el módulo y sus límites: [docs/10-seguridad.md](docs/10-seguridad.md).
+
+## Cómo se protege la cadena de publicación
+
+- Los paquetes se publican desde GitHub Actions con *Trusted Publishing*: no existen contraseñas ni tokens de PyPI que robar.
+- Cada versión en PyPI lleva una atestación firmada (PEP 740) que prueba de qué repositorio y flujo salió.
+- Las acciones de GitHub están fijadas por commit, y Dependabot propone sus actualizaciones.
+- En cada cambio se ejecutan pruebas, análisis de tipos (`mypy`), análisis de seguridad del código (`bandit`) y la búsqueda de vulnerabilidades conocidas en las dependencias (`pip-audit`).

fastapi_djauth-1.4.0/djauth/__init__.py

@@ -0,0 +1,82 @@
+"""djauth: usuarios, grupos (roles), permisos y administración al estilo de Django, para FastAPI.
+
+from djauth import AuthKit, AuthSettings, current_user, require_perm
+
+kit = AuthKit(AuthSettings(database_url="sqlite:///auth.sqlite3")).init()
+kit.install(app, protect=True)
+"""
+
+from djauth.api import (
+    AuthMiddleware,
+    Rule,
+    current_user,
+    identify,
+    optional_user,
+    require_perm,
+    require_staff,
+    require_superuser,
+    rule,
+    ws_user,
+)
+from djauth.backends import AllowAllUsersModelBackend, AuthRequest, BaseBackend, ModelBackend
+from djauth.core import SERVICE_USER, AuthKit, AuthUser
+from djauth.database import DatabaseConfigError, url_from_django
+from djauth.decorators import login_required, permission_required, staff_member_required, superuser_required, user_passes_test
+from djauth.errors import (
+    AuthError,
+    InvalidCredentialsError,
+    NotAuthenticatedError,
+    NotFoundError,
+    PermissionDeniedError,
+    TooManyAttemptsError,
+    ValidationError,
+)
+from djauth.hashers import check_password, make_password
+from djauth.routers import BaseRouter, Databases, ModelMeta, RoutingSession, model_meta
+from djauth.settings import AuthSettings, ExtraField
+
+__version__ = "1.4.0"
+
+__all__ = [
+    "SERVICE_USER",
+    "AllowAllUsersModelBackend",
+    "AuthError",
+    "AuthKit",
+    "AuthMiddleware",
+    "AuthRequest",
+    "AuthSettings",
+    "AuthUser",
+    "BaseBackend",
+    "BaseRouter",
+    "DatabaseConfigError",
+    "Databases",
+    "ExtraField",
+    "InvalidCredentialsError",
+    "ModelBackend",
+    "ModelMeta",
+    "NotAuthenticatedError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RoutingSession",
+    "Rule",
+    "TooManyAttemptsError",
+    "ValidationError",
+    "__version__",
+    "check_password",
+    "current_user",
+    "identify",
+    "login_required",
+    "make_password",
+    "model_meta",
+    "optional_user",
+    "permission_required",
+    "require_perm",
+    "require_staff",
+    "require_superuser",
+    "rule",
+    "staff_member_required",
+    "superuser_required",
+    "url_from_django",
+    "user_passes_test",
+    "ws_user",
+]

fastapi_djauth-1.4.0/djauth/__main__.py

@@ -0,0 +1,98 @@
+"""Comandos de administración (como `manage.py`):
+
+    python -m djauth --db sqlite:///auth.sqlite3 createsuperuser --username admin --email a@b.co
+    python -m djauth --db … changepassword admin
+    python -m djauth --db … listusers
+    djauth startproject inventario --db postgresql      # proyecto FastAPI nuevo con djauth integrado
+
+La contraseña se pide por teclado; para scripts, use la variable DJAUTH_PASSWORD.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import sys
+
+from djauth.core import AuthKit
+from djauth.errors import AuthError, ValidationError
+from djauth.settings import AuthSettings
+
+
+def _ask_password() -> str:
+    if env := os.environ.get("DJAUTH_PASSWORD"):
+        return env
+    while True:
+        first = getpass.getpass("Contraseña: ")
+        if first == getpass.getpass("Contraseña (otra vez): "):
+            return first
+        print("Las contraseñas no coinciden.", file=sys.stderr)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m djauth", description="Administración de usuarios de djauth")
+    parser.add_argument(
+        "--db", default=os.environ.get("DJAUTH_DATABASE_URL", "sqlite:///auth.sqlite3"), help="URL de la base de datos"
+    )
+    parser.add_argument("--prefix", default="auth_", help="Prefijo de las tablas")
+    sub = parser.add_subparsers(dest="command", required=True)
+    create = sub.add_parser("createsuperuser", help="Crear un superusuario")
+    create.add_argument("--username", required=True)
+    create.add_argument("--email", default="")
+    change = sub.add_parser("changepassword", help="Cambiar la contraseña de un usuario")
+    change.add_argument("username")
+    sub.add_parser("listusers", help="Listar usuarios")
+    start = sub.add_parser("startproject", help="Crear un proyecto FastAPI nuevo con djauth integrado")
+    start.add_argument("name", help="Nombre del paquete: minúsculas, números y _ (p. ej. inventario)")
+    start.add_argument("directory", nargs="?", help="Carpeta donde crearlo (por defecto ./<name>; debe estar vacía)")
+    start.add_argument("--db", dest="db_engine", choices=("sqlite", "postgresql", "mysql"), default="sqlite")
+    start.add_argument(
+        "--versiones",
+        dest="versions",
+        choices=("probadas", "ultimas"),
+        default="probadas",
+        help="probadas: versiones exactas verificadas con este djauth · ultimas: lo más reciente compatible",
+    )
+    start.add_argument("--titulo", dest="title", help='Nombre visible de la aplicación (p. ej. "Inventario de planta")')
+    start.add_argument("--sin-lock", dest="no_lock", action="store_true", help="No ejecutar `uv lock` al terminar")
+    args = parser.parse_args(argv)
+
+    if args.command == "startproject":
+        from djauth.startproject import main as startproject
+
+        return startproject(args)
+
+    kit = AuthKit(AuthSettings(database_url=args.db, table_prefix=args.prefix)).init()
+    try:
+        if args.command == "createsuperuser":
+            created = kit.create_superuser(
+                args.username, _ask_password(), email=args.email, reason="Creado con djauth createsuperuser."
+            )
+            print(f"Superusuario {created['username']} creado.")
+        elif args.command == "changepassword":
+            user = kit.get_by_username(args.username)
+            if user is None:
+                print(f"No existe el usuario {args.username}.", file=sys.stderr)
+                return 1
+            kit.set_password(user.id, _ask_password(), reason="Cambiada con djauth changepassword.")
+            print(f"Contraseña de {user.username} cambiada; sus sesiones abiertas se cerraron.")
+        elif args.command == "listusers":
+            items, total = kit.list_users(limit=1000)
+            for u in items:
+                flags = "".join(f for f, on in (("S", u["is_superuser"]), ("A", u["is_staff"]), ("-", not u["is_active"])) if on)
+                print(f"{u['id']:>5}  {u['username']:<30} {flags:<3} {', '.join(u['groups'])}")
+            print(f"{total} usuarios")
+    except ValidationError as exc:
+        for field, messages in exc.errors.items():
+            for m in messages:
+                print(f"{field}: {m}", file=sys.stderr)
+        return 1
+    except AuthError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())