lenapi 0.1.3__tar.gz → 0.1.4.1__tar.gz

{lenapi-0.1.3 → lenapi-0.1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lenapi
-Version: 0.1.3
+Version: 0.1.4.1
 Summary: A modern ASGI framework with Pydantic validation, sync and async database access, WebSockets, authentication, and integrated API documentation.
 Author: Maekandex Communication Limitation
 Author-email: "Ifeanyi M. Onovo" <ifeanyi@maekandex.com.ng>
@@ -425,7 +425,7 @@ app.include_router(api)
 
 Rate strings accept seconds, minutes, hours, or days, for example `"10/second"`, `"60/minute"`, and `"1000/day"`. Throttling uses a fixed window that starts with the first request. `ip` counts every request from the client address before authentication. `anonymous` counts public calls and, on routes using `auth=`, all requests from that IP before credentials are verified. This intentionally includes successful logins so repeated password checks are stopped before they consume CPU. `authenticated` counts successful route-level authentication by a stable identity returned from `auth=`. Routes using `BasicAuth` receive a default `ip` limit of 10 requests per minute if no pre-auth `ip` or `anonymous` limit is configured. Set `throttle={}` to deliberately disable the inherited and default limit. Route and router `throttle=` values otherwise override inherited limits; an empty mapping disables inherited limits for that route or router. Endpoint-only auth declared with `Depends(...)` does not supply the identity to the authenticated quota; attach it with `auth=` when you want identity-based quotas.
 
-When a quota is exceeded, LenAPI returns `429 Too Many Requests` with `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` headers. Quota counters use the same security backend as IP cooldowns. Choose `SECURITY_STORAGE = "database"` or `"redis"` in project `settings.py`. Database mode stores state in the internal `lenapi_security_store` table or MongoDB collection, initialized by migrations. Redis mode uses `REDIS_URL` and requires `pip install 'lenapi[redis]'` plus a running Redis server. The generated settings default to database storage and include `REDIS_URL = "redis://127.0.0.1:6379/0"` for switching to Redis. Shared database or Redis storage coordinates limits across workers. `SECURITY_STORAGE = "memory"` keeps counters in each process, so use it only for single-process development. LenAPI uses the ASGI connection's client address and does not trust forwarded-IP headers automatically; configure trusted proxy handling at your deployment edge before relying on IP quotas behind a proxy.
+When a quota is exceeded, LenAPI returns `429 Too Many Requests` with `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` headers. Quota counters use the same security backend as IP cooldowns. Choose `SECURITY_STORAGE = "database"` or `"redis"` in project `settings.py`. Database mode stores state in the internal `lenapi_security_store` table or MongoDB collection, initialized by migrations. Redis mode uses `REDIS_URL` and requires `python -m pip install 'lenapi[redis]'` plus a running Redis server. Run the install command with the same Python environment that starts LenAPI; keep the quotes around the extra in zsh. The generated settings default to database storage and include `REDIS_URL = "redis://127.0.0.1:6379/0"` for switching to Redis. Shared database or Redis storage coordinates limits across workers. `SECURITY_STORAGE = "memory"` keeps counters in each process, so use it only for single-process development. LenAPI uses the ASGI connection's client address and does not trust forwarded-IP headers automatically; configure trusted proxy handling at your deployment edge before relying on IP quotas behind a proxy.
 
 For example, app-level limits are inherited by routes that do not set their own throttle. A route-specific mapping replaces the inherited mapping, so repeat any global scopes that you still want on that route:
 
@@ -1089,7 +1089,31 @@ app.include_router(public)
 
 The framework-backed JWT authenticator checks the submitted username and password against the database `User` model and its stored password hash. `POST /auth/token` accepts `{"username": "...", "password": "..."}` and returns an access token plus a refresh token. Send the access token as `Authorization: Bearer <access_token>`. `POST /auth/refresh` accepts `{"refresh_token": "..."}` and returns replacement tokens. The token and refresh routes are intentionally hidden from Swagger; protected API routes still show their Bearer scheme and Swagger's **Authorize** control. These routes have a default IP limit of 10 requests per minute, including failed credential checks; pass `throttle={"ip": "5/minute"}` to `jwt.router(...)` for a different limit. In production, use shared `SECURITY_STORAGE = "database"` or `"redis"` for refresh replay protection across workers. Refresh tokens are single-use; the in-memory fallback coordinates only within one process.
 
-For a custom user table, create the JWT dependency with `authentication("jwt", user_model=YourUser)`. Basic and JWT can use your model as long as it has the selected identifier column and a `password` column containing LenAPI-compatible password hashes. For Basic, select the identifier with `BASIC_AUTH_FIELD`. Or configure `JWTAuth` with an `authenticate(username, password)` callback. That callback must verify a password hash and return the user's string ID, `(string_id, claims)`, or `None`. `JWTAuth` signs and verifies HS256 tokens, checks expiry and configured issuer, and rejects refresh tokens when used as access tokens. Keep the signing key secret and serve credentials only over HTTPS.
+For a custom user table, create the JWT dependency with `authentication("jwt", user_model=YourUser)`. Basic and JWT can use your model as long as it has the selected identifier column and a `password` column containing LenAPI-compatible password hashes. For Basic, select the identifier with `BASIC_AUTH_FIELD`. JWT defaults to the `username` column; pass `identifier_field="email"` (or another model column) to use a different login identifier. That field name is also used in the `/auth/token` JSON body. Pass the actual `LENAPI` instance with `app=app` when you want refresh-token replay protection to use its shared security store; do not pass a `Router` there.
+
+For example, a custom model with `email` and a hashed `password` can sign in using `{"email": "ada@example.com", "password": "..."}`:
+
+```python
+from lenapi_bootstrap import create_app
+from lenapi import Depends, authentication
+
+app = create_app(__file__, __package__)
+from app.models import Customer
+auth = authentication(
+    "jwt",
+    user_model=Customer,
+    identifier_field="email",
+    app=app,
+)
+
+app.include_router(auth.router())  # POST /auth/token and POST /auth/refresh
+
+@app.get("/profile", auth=auth)
+def profile(identity=Depends(auth)):
+    return {"customer_id": identity["sub"]}
+```
+
+`Customer` must define an `email` column and a `password` column containing a LenAPI-compatible password hash. Your registration or provisioning flow is responsible for collecting the email and storing the password hash. `JWTAuth` signs and verifies HS256 tokens, checks expiry and configured issuer, and rejects refresh tokens when used as access tokens. Keep the signing key secret and serve credentials only over HTTPS.
 
 ## API-key authentication
 
@@ -1903,7 +1927,7 @@ student = Student.create(
 
 `DateField`, `TimeField`, and `DateTimeField` default to the current UTC date or time when no value or explicit default is supplied. Pass `auto_add_now=False` to disable this behavior, or provide your own `default`. `DurationField(weeks=1)` stores a fixed seven-day `timedelta`; add it to a timestamp when calculating an expiry date. Months and years are calendar intervals and should use calendar-aware date arithmetic.
 
-`PositiveIntegerField` and `PositiveBigIntegerField` reject negative values in LenAPI and add a named database `CHECK` constraint, so direct SQL writes are protected too. `EmailField`, `PhoneField`, `IPField`, `URLField`, and `UUIDField` validate values when a model instance is saved. `PhoneField` accepts a leading `+` followed by country code and digits, up to 18 characters total. `IPField` accepts IPv4 and IPv6. `URLField` accepts `http://`, `https://`, and `www.` URLs. Customize messages with `error_messages`, for example `email = model.EmailField(error_messages={"email": "This is not an email"})`; `unique` is also a supported message key for a unique field.
+`PositiveIntegerField` and `PositiveBigIntegerField` reject negative values in LenAPI and add a named database `CHECK` constraint, so direct SQL writes are protected too. `EmailField`, `PhoneField`, `IPField`, `URLField`, and `UUIDField` validate values when a model instance is saved. `PhoneField` accepts either a `+` country-code number or a local number beginning with `0`, up to 18 characters. Declare phone numbers as strings and send them quoted in JSON so leading zeroes are preserved; bare JSON numbers such as `08099448550` are invalid JSON. `IPField` accepts IPv4 and IPv6. `URLField` accepts `http://`, `https://`, and `www.` URLs. Customize messages with `error_messages`, for example `email = model.EmailField(error_messages={"email": "This is not an email"})`; `unique` is also a supported message key for a unique field.
 
 The base model supplies an auto-incrementing integer `id`. A model may declare its own primary key instead; LenAPI will not add a second `id` key:
 
@@ -2082,7 +2106,14 @@ async_total = async_page.total_count
 async_pages = async_page.page_count
 ```
 
-`Student.get.all()` returns all rows synchronously; its async counterpart is `await Student.aget.all()`. For filtered async lists, use `await Student.afilter(...).all()`. `Student.get(...)` builds a single-row lookup; call `.get()` for the model instance or `.exists()` for a boolean. The async single-row counterpart is `await Student.aget(...)`, and its existence check is `await Student.aget(...).exists()`. Multiple matches are an error rather than an arbitrary row selection. `Student.get("field", ...).get(...)` selects one or more columns; one selected column returns a scalar and multiple columns return a mapping. This is a query projection, not a uniqueness constraint. To make the database reject duplicates, declare `unique=True` on the field.
+`Student.get.all()` returns all rows synchronously; its async counterpart is `await Student.aget.all()`. For filtered lists, use `Student.filter(...).all()` or `await Student.afilter(...).all()`. Both sync and async filtered querysets support existence checks:
+
+```python
+has_python_students = Student.filter(course="Python").exists()
+has_python_students_async = await Student.afilter(course="Python").exists()
+```
+
+`Student.get(...)` builds a single-row lookup; call `.get()` for the model instance or `.exists()` for a boolean. The async single-row counterpart is `await Student.aget(...)`, and its existence check is `await Student.aget(...).exists()`. Multiple matches are an error rather than an arbitrary row selection. `Student.get("field", ...).get(...)` selects one or more columns; one selected column returns a scalar and multiple columns return a mapping. This is a query projection, not a uniqueness constraint. To make the database reject duplicates, declare `unique=True` on the field.
 
 ### Fetch related records
 

{lenapi-0.1.3 → lenapi-0.1.4.1}/README.md

@@ -373,7 +373,7 @@ app.include_router(api)
 
 Rate strings accept seconds, minutes, hours, or days, for example `"10/second"`, `"60/minute"`, and `"1000/day"`. Throttling uses a fixed window that starts with the first request. `ip` counts every request from the client address before authentication. `anonymous` counts public calls and, on routes using `auth=`, all requests from that IP before credentials are verified. This intentionally includes successful logins so repeated password checks are stopped before they consume CPU. `authenticated` counts successful route-level authentication by a stable identity returned from `auth=`. Routes using `BasicAuth` receive a default `ip` limit of 10 requests per minute if no pre-auth `ip` or `anonymous` limit is configured. Set `throttle={}` to deliberately disable the inherited and default limit. Route and router `throttle=` values otherwise override inherited limits; an empty mapping disables inherited limits for that route or router. Endpoint-only auth declared with `Depends(...)` does not supply the identity to the authenticated quota; attach it with `auth=` when you want identity-based quotas.
 
-When a quota is exceeded, LenAPI returns `429 Too Many Requests` with `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` headers. Quota counters use the same security backend as IP cooldowns. Choose `SECURITY_STORAGE = "database"` or `"redis"` in project `settings.py`. Database mode stores state in the internal `lenapi_security_store` table or MongoDB collection, initialized by migrations. Redis mode uses `REDIS_URL` and requires `pip install 'lenapi[redis]'` plus a running Redis server. The generated settings default to database storage and include `REDIS_URL = "redis://127.0.0.1:6379/0"` for switching to Redis. Shared database or Redis storage coordinates limits across workers. `SECURITY_STORAGE = "memory"` keeps counters in each process, so use it only for single-process development. LenAPI uses the ASGI connection's client address and does not trust forwarded-IP headers automatically; configure trusted proxy handling at your deployment edge before relying on IP quotas behind a proxy.
+When a quota is exceeded, LenAPI returns `429 Too Many Requests` with `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` headers. Quota counters use the same security backend as IP cooldowns. Choose `SECURITY_STORAGE = "database"` or `"redis"` in project `settings.py`. Database mode stores state in the internal `lenapi_security_store` table or MongoDB collection, initialized by migrations. Redis mode uses `REDIS_URL` and requires `python -m pip install 'lenapi[redis]'` plus a running Redis server. Run the install command with the same Python environment that starts LenAPI; keep the quotes around the extra in zsh. The generated settings default to database storage and include `REDIS_URL = "redis://127.0.0.1:6379/0"` for switching to Redis. Shared database or Redis storage coordinates limits across workers. `SECURITY_STORAGE = "memory"` keeps counters in each process, so use it only for single-process development. LenAPI uses the ASGI connection's client address and does not trust forwarded-IP headers automatically; configure trusted proxy handling at your deployment edge before relying on IP quotas behind a proxy.
 
 For example, app-level limits are inherited by routes that do not set their own throttle. A route-specific mapping replaces the inherited mapping, so repeat any global scopes that you still want on that route:
 
@@ -1037,7 +1037,31 @@ app.include_router(public)
 
 The framework-backed JWT authenticator checks the submitted username and password against the database `User` model and its stored password hash. `POST /auth/token` accepts `{"username": "...", "password": "..."}` and returns an access token plus a refresh token. Send the access token as `Authorization: Bearer <access_token>`. `POST /auth/refresh` accepts `{"refresh_token": "..."}` and returns replacement tokens. The token and refresh routes are intentionally hidden from Swagger; protected API routes still show their Bearer scheme and Swagger's **Authorize** control. These routes have a default IP limit of 10 requests per minute, including failed credential checks; pass `throttle={"ip": "5/minute"}` to `jwt.router(...)` for a different limit. In production, use shared `SECURITY_STORAGE = "database"` or `"redis"` for refresh replay protection across workers. Refresh tokens are single-use; the in-memory fallback coordinates only within one process.
 
-For a custom user table, create the JWT dependency with `authentication("jwt", user_model=YourUser)`. Basic and JWT can use your model as long as it has the selected identifier column and a `password` column containing LenAPI-compatible password hashes. For Basic, select the identifier with `BASIC_AUTH_FIELD`. Or configure `JWTAuth` with an `authenticate(username, password)` callback. That callback must verify a password hash and return the user's string ID, `(string_id, claims)`, or `None`. `JWTAuth` signs and verifies HS256 tokens, checks expiry and configured issuer, and rejects refresh tokens when used as access tokens. Keep the signing key secret and serve credentials only over HTTPS.
+For a custom user table, create the JWT dependency with `authentication("jwt", user_model=YourUser)`. Basic and JWT can use your model as long as it has the selected identifier column and a `password` column containing LenAPI-compatible password hashes. For Basic, select the identifier with `BASIC_AUTH_FIELD`. JWT defaults to the `username` column; pass `identifier_field="email"` (or another model column) to use a different login identifier. That field name is also used in the `/auth/token` JSON body. Pass the actual `LENAPI` instance with `app=app` when you want refresh-token replay protection to use its shared security store; do not pass a `Router` there.
+
+For example, a custom model with `email` and a hashed `password` can sign in using `{"email": "ada@example.com", "password": "..."}`:
+
+```python
+from lenapi_bootstrap import create_app
+from lenapi import Depends, authentication
+
+app = create_app(__file__, __package__)
+from app.models import Customer
+auth = authentication(
+    "jwt",
+    user_model=Customer,
+    identifier_field="email",
+    app=app,
+)
+
+app.include_router(auth.router())  # POST /auth/token and POST /auth/refresh
+
+@app.get("/profile", auth=auth)
+def profile(identity=Depends(auth)):
+    return {"customer_id": identity["sub"]}
+```
+
+`Customer` must define an `email` column and a `password` column containing a LenAPI-compatible password hash. Your registration or provisioning flow is responsible for collecting the email and storing the password hash. `JWTAuth` signs and verifies HS256 tokens, checks expiry and configured issuer, and rejects refresh tokens when used as access tokens. Keep the signing key secret and serve credentials only over HTTPS.
 
 ## API-key authentication
 
@@ -1851,7 +1875,7 @@ student = Student.create(
 
 `DateField`, `TimeField`, and `DateTimeField` default to the current UTC date or time when no value or explicit default is supplied. Pass `auto_add_now=False` to disable this behavior, or provide your own `default`. `DurationField(weeks=1)` stores a fixed seven-day `timedelta`; add it to a timestamp when calculating an expiry date. Months and years are calendar intervals and should use calendar-aware date arithmetic.
 
-`PositiveIntegerField` and `PositiveBigIntegerField` reject negative values in LenAPI and add a named database `CHECK` constraint, so direct SQL writes are protected too. `EmailField`, `PhoneField`, `IPField`, `URLField`, and `UUIDField` validate values when a model instance is saved. `PhoneField` accepts a leading `+` followed by country code and digits, up to 18 characters total. `IPField` accepts IPv4 and IPv6. `URLField` accepts `http://`, `https://`, and `www.` URLs. Customize messages with `error_messages`, for example `email = model.EmailField(error_messages={"email": "This is not an email"})`; `unique` is also a supported message key for a unique field.
+`PositiveIntegerField` and `PositiveBigIntegerField` reject negative values in LenAPI and add a named database `CHECK` constraint, so direct SQL writes are protected too. `EmailField`, `PhoneField`, `IPField`, `URLField`, and `UUIDField` validate values when a model instance is saved. `PhoneField` accepts either a `+` country-code number or a local number beginning with `0`, up to 18 characters. Declare phone numbers as strings and send them quoted in JSON so leading zeroes are preserved; bare JSON numbers such as `08099448550` are invalid JSON. `IPField` accepts IPv4 and IPv6. `URLField` accepts `http://`, `https://`, and `www.` URLs. Customize messages with `error_messages`, for example `email = model.EmailField(error_messages={"email": "This is not an email"})`; `unique` is also a supported message key for a unique field.
 
 The base model supplies an auto-incrementing integer `id`. A model may declare its own primary key instead; LenAPI will not add a second `id` key:
 
@@ -2030,7 +2054,14 @@ async_total = async_page.total_count
 async_pages = async_page.page_count
 ```
 
-`Student.get.all()` returns all rows synchronously; its async counterpart is `await Student.aget.all()`. For filtered async lists, use `await Student.afilter(...).all()`. `Student.get(...)` builds a single-row lookup; call `.get()` for the model instance or `.exists()` for a boolean. The async single-row counterpart is `await Student.aget(...)`, and its existence check is `await Student.aget(...).exists()`. Multiple matches are an error rather than an arbitrary row selection. `Student.get("field", ...).get(...)` selects one or more columns; one selected column returns a scalar and multiple columns return a mapping. This is a query projection, not a uniqueness constraint. To make the database reject duplicates, declare `unique=True` on the field.
+`Student.get.all()` returns all rows synchronously; its async counterpart is `await Student.aget.all()`. For filtered lists, use `Student.filter(...).all()` or `await Student.afilter(...).all()`. Both sync and async filtered querysets support existence checks:
+
+```python
+has_python_students = Student.filter(course="Python").exists()
+has_python_students_async = await Student.afilter(course="Python").exists()
+```
+
+`Student.get(...)` builds a single-row lookup; call `.get()` for the model instance or `.exists()` for a boolean. The async single-row counterpart is `await Student.aget(...)`, and its existence check is `await Student.aget(...).exists()`. Multiple matches are an error rather than an arbitrary row selection. `Student.get("field", ...).get(...)` selects one or more columns; one selected column returns a scalar and multiple columns return a mapping. This is a query projection, not a uniqueness constraint. To make the database reject duplicates, declare `unique=True` on the field.
 
 ### Fetch related records
 

{lenapi-0.1.3 → lenapi-0.1.4.1}/lenapi/__init__.py

@@ -8,7 +8,7 @@ if sys.version_info < (3, 11):
         "on 2026-10-01 and is no longer supported."
     )
 
-__version__ = "0.1.3"
+__version__ = "0.1.4.1"
 
 from .application import Application, LENAPI, Router
 from .background import BackgroundQueue, BackgroundTasks

{lenapi-0.1.3 → lenapi-0.1.4.1}/lenapi/application.py

@@ -681,7 +681,8 @@ class Application(Router):
                 hint = (
                     "Run `python lenora.py migration` to create or update the security store table."
                     if self.security_storage == "database"
-                    else "Install `lenapi[redis]` and check REDIS_URL and Redis availability."
+                    else "Install the Redis extra in the environment running LenAPI with "
+                    "`python -m pip install 'lenapi[redis]'`, then check REDIS_URL and Redis availability."
                 )
                 response = JSONResponse(
                     {"detail": f"Security storage is unavailable. {hint}"}, status_code=503

{lenapi-0.1.3 → lenapi-0.1.4.1}/lenapi/authentication.py

@@ -116,6 +116,7 @@ def jwt_auth(settings, user_model=None, *, identifier_field="username", password
         refresh_token_lifetime_seconds=token.get("REFRESH_LIFETIME_SECONDS", 60 * 60 * 24 * 30),
         issuer=token.get("ISSUER"),
         security_store=security_store,
+        login_field=identifier_field,
         authenticate=(
             _user_authenticator(user_model, identifier_field, password_field)
             if user_model is not None else None
@@ -149,20 +150,38 @@ def webhook(secret, *, tolerance_seconds=300, nonce_store=None):
     return WebhookAuth(secret, tolerance_seconds=tolerance_seconds, nonce_store=nonce_store)
 
 
-def configure(settings, user_model=None, *, security_store=None, api_key_field=None):
+def configure(
+    settings,
+    user_model=None,
+    *,
+    security_store=None,
+    api_key_field=None,
+    identifier_field=None,
+    password_field="password",
+):
     """Build the primary authenticator selected by ``settings.AUTHENTICATION``."""
     if user_model is None:
         from .models import User
 
         user_model = User
     mode = getattr(settings, "AUTHENTICATION", "jwt").lower()
-    identifier_field = getattr(settings, "BASIC_AUTH_FIELD", "username")
+    identifier_field = identifier_field or getattr(settings, "BASIC_AUTH_FIELD", "username")
     if mode == "basic_login":
-        return basic(user_model, identifier_field=identifier_field)
+        return basic(
+            user_model,
+            identifier_field=identifier_field,
+            password_field=password_field,
+        )
     if mode == "api_key":
         return api_key(user_model, field=api_key_field or "api_key")
     if mode == "jwt":
-        return jwt_auth(settings, user_model, security_store=security_store)
+        return jwt_auth(
+            settings,
+            user_model,
+            identifier_field=identifier_field,
+            password_field=password_field,
+            security_store=security_store,
+        )
     if mode == "session":
         options = getattr(settings, "SESSION", {})
         return session(store=security_store, cookie_name=options.get("COOKIE_NAME", "lenapi_session"))
@@ -181,7 +200,16 @@ def configure(settings, user_model=None, *, security_store=None, api_key_field=N
     raise ValueError(f"Unknown AUTHENTICATION mode: {mode}")
 
 
-def authentication_type(auth_type, *, settings, user_model=None, api_key_field=None, app=None):
+def authentication_type(
+    auth_type,
+    *,
+    settings,
+    user_model=None,
+    api_key_field=None,
+    identifier_field=None,
+    password_field="password",
+    app=None,
+):
     """Create the authenticator selected by a project settings module.
 
     ``auth_type`` may be ``"jwt"``, ``"api_key"``, ``"basic_login``,
@@ -208,16 +236,29 @@ def authentication_type(auth_type, *, settings, user_model=None, api_key_field=N
         user_model,
         security_store=getattr(app, "security_store", None),
         api_key_field=api_key_field,
+        identifier_field=identifier_field,
+        password_field=password_field,
     )
     return authenticator
 
 
-def authentication(type="jwt", *, settings=None, user_model=None, api_key_field=None, app=None):
+def authentication(
+    type="jwt",
+    *,
+    settings=None,
+    user_model=None,
+    api_key_field=None,
+    identifier_field=None,
+    password_field="password",
+    app=None,
+):
     """Create a route authentication dependency from project settings.
 
     By default, ``settings`` is imported from the current project and the
-    framework's built-in ``User`` model is used. Pass explicit values when
-    configuring authentication outside a generated project.
+    framework's built-in ``User`` model is used. ``identifier_field`` selects
+    the database field used for JWT/Basic login; for JWT it also names the
+    identifier property in the token endpoint's JSON body. Pass the actual
+    LENAPI instance as ``app`` to share its security store.
     """
     if settings is None:
         try:
@@ -233,6 +274,8 @@ def authentication(type="jwt", *, settings=None, user_model=None, api_key_field=
         settings=settings,
         user_model=user_model,
         api_key_field=api_key_field,
+        identifier_field=identifier_field,
+        password_field=password_field,
         app=app,
     )
 

{lenapi-0.1.3 → lenapi-0.1.4.1}/lenapi/models.py

@@ -372,6 +372,10 @@ class _QuerySet:
         row = result.mappings().first()
         return None if row is None else dict(row)
 
+    def exists(self) -> bool:
+        """Return whether this query matches at least one row."""
+        return self.first() is not None
+
     def one_or_none(self):
         """Return the sole matching row, or raise if the lookup is ambiguous."""
         result = _session().execute(self._statement())
@@ -1234,7 +1238,12 @@ def IPField(max_length: int = 45, **kwargs):
 
 
 def PhoneField(max_length: int = 18, **kwargs):
-    """Declare a string column intended for an international phone number."""
+    """Declare a string phone column accepting international or local numbers.
+
+    International values begin with ``+`` and a country code. Local values may
+    begin with ``0`` (for example, ``"08099448550"``). Store phone numbers as
+    strings so leading zeroes are preserved.
+    """
     info = dict(kwargs.pop("info", {}) or {})
     info["lenapi_validation"] = "phone"
     return _field(String(max_length), info=info, **kwargs)
@@ -1337,8 +1346,14 @@ def _validate_instance(instance):
             valid = isinstance(value, str) and re.fullmatch(r"[^\s@]+@[^\s@]+", value) is not None
             message = _validation_error(column, rule, "Enter a valid email address")
         elif rule == "phone":
-            valid = isinstance(value, str) and re.fullmatch(r"\+[1-9][0-9]{0,16}", value) is not None
-            message = _validation_error(column, rule, "Phone must start with + and contain at most 18 digits")
+            valid = isinstance(value, str) and re.fullmatch(
+                r"(?:\+[1-9][0-9]{0,16}|0[0-9]{7,17})", value
+            ) is not None
+            message = _validation_error(
+                column,
+                rule,
+                "Enter a phone number with +country code or a local number starting with 0 (up to 18 digits)",
+            )
         elif rule == "ip":
             try:
                 ipaddress.ip_address(value)

{lenapi-0.1.3 → lenapi-0.1.4.1}/lenapi/request.py

@@ -332,7 +332,12 @@ class Request:
         return self._body
 
     async def json(self):
-        return json.loads((await self.body()).decode("utf-8"))
+        """Parse a JSON request body, returning HTTP 400 for malformed JSON."""
+        try:
+            text = (await self.body()).decode("utf-8")
+            return json.loads(text)
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise HTTPException(400, "Malformed JSON request body") from exc
 
     async def form(self) -> dict[str, str | UploadFile | list[str | UploadFile]]:
         """Parse URL-encoded or multipart form data, including file uploads."""

{lenapi-0.1.3 → lenapi-0.1.4.1}/lenapi/security.py

@@ -12,7 +12,7 @@ import threading
 import time
 from typing import Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, create_model
 
 from .concurrency import call_sync_or_async
 from .request import Request
@@ -117,6 +117,7 @@ class JWTAuth:
         issuer: str | None = None,
         authenticate=None,
         security_store=None,
+        login_field: str = "username",
     ) -> None:
         key = secret_key.encode("utf-8") if isinstance(secret_key, str) else secret_key
         if not isinstance(key, bytes) or len(key) < 32:
@@ -125,12 +126,15 @@ class JWTAuth:
             raise ValueError("token_lifetime_seconds must be positive")
         if refresh_token_lifetime_seconds <= 0:
             raise ValueError("refresh_token_lifetime_seconds must be positive")
+        if not isinstance(login_field, str) or not login_field.isidentifier() or login_field == "password":
+            raise ValueError("login_field must be a valid model field name other than 'password'")
         self.secret_key = key
         self.token_lifetime_seconds = token_lifetime_seconds
         self.refresh_token_lifetime_seconds = refresh_token_lifetime_seconds
         self.issuer = issuer
         self.authenticate = authenticate
         self.security_store = security_store
+        self.login_field = login_field
         self._refresh_namespace = hashlib.sha256(key).hexdigest()[:32]
         self._used_refresh_tokens: dict[str, float] = {}
         self._refresh_lock = threading.Lock()
@@ -229,15 +233,16 @@ class JWTAuth:
                security_store=None):
         """Build `/auth/token` and `/auth/refresh` routes for an app.
 
-        `authenticate(username, password)` may be supplied here or when
-        constructing the instance. It must return the user's string ID, or
+        `authenticate(identifier, password)` may be supplied here or when
+        constructing the instance. The identifier field name is controlled by
+        `login_field`. The callback must return the user's string ID, or
         `(string_id, claims)`, when credentials are valid; otherwise return None.
         """
         from .application import Router
 
         authenticate = authenticate or self.authenticate
         if authenticate is None:
-            raise ValueError("JWT token routes require an authenticate(username, password) callback")
+            raise ValueError("JWT token routes require an authenticate(identifier, password) callback")
 
         # Keep password verification endpoints rate-limited even when the app
         # has no global throttle configured. An empty mapping explicitly opts
@@ -245,14 +250,21 @@ class JWTAuth:
         token_throttle = {"ip": "10/minute"} if throttle is None else throttle
         refresh_store = security_store if security_store is not None else self.security_store
         router = Router(prefix="/auth")
+        credentials_model = create_model(
+            f"JWTTokenCredentials_{self.login_field}",
+            **{
+                self.login_field: (str, Field(min_length=1)),
+                "password": (str, Field(min_length=1)),
+            },
+        )
 
         @router.post("/token", include_in_schema=False, throttle=token_throttle)
-        async def issue_token(credentials: _Credentials):
+        async def issue_token(credentials: credentials_model):
             user = await call_sync_or_async(
-                authenticate, credentials.username, credentials.password
+                authenticate, getattr(credentials, self.login_field), credentials.password
             )
             if user is None or user is False:
-                raise HTTPException(401, "Invalid username or password")
+                raise HTTPException(401, "Invalid login credentials")
             if isinstance(user, tuple) and len(user) == 2:
                 subject, claims = user
             else:

{lenapi-0.1.3 → lenapi-0.1.4.1}/lenapi/security_store.py

@@ -188,7 +188,11 @@ class RedisSecurityStore:
         try:
             from redis.asyncio import Redis
         except ImportError as exc:
-            raise ValueError("Redis security storage requires `pip install lenapi[redis]`") from exc
+            raise ValueError(
+                "Redis security storage requires the Redis extra. Install it in the same "
+                "environment that runs LenAPI with: `python -m pip install 'lenapi[redis]'`. "
+                "Keep the quotes around the extra in zsh."
+            ) from exc
         self.client = Redis.from_url(url, decode_responses=True)
 
     @staticmethod

{lenapi-0.1.3 → lenapi-0.1.4.1}/lenapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lenapi
-Version: 0.1.3
+Version: 0.1.4.1
 Summary: A modern ASGI framework with Pydantic validation, sync and async database access, WebSockets, authentication, and integrated API documentation.
 Author: Maekandex Communication Limitation
 Author-email: "Ifeanyi M. Onovo" <ifeanyi@maekandex.com.ng>
@@ -425,7 +425,7 @@ app.include_router(api)
 
 Rate strings accept seconds, minutes, hours, or days, for example `"10/second"`, `"60/minute"`, and `"1000/day"`. Throttling uses a fixed window that starts with the first request. `ip` counts every request from the client address before authentication. `anonymous` counts public calls and, on routes using `auth=`, all requests from that IP before credentials are verified. This intentionally includes successful logins so repeated password checks are stopped before they consume CPU. `authenticated` counts successful route-level authentication by a stable identity returned from `auth=`. Routes using `BasicAuth` receive a default `ip` limit of 10 requests per minute if no pre-auth `ip` or `anonymous` limit is configured. Set `throttle={}` to deliberately disable the inherited and default limit. Route and router `throttle=` values otherwise override inherited limits; an empty mapping disables inherited limits for that route or router. Endpoint-only auth declared with `Depends(...)` does not supply the identity to the authenticated quota; attach it with `auth=` when you want identity-based quotas.
 
-When a quota is exceeded, LenAPI returns `429 Too Many Requests` with `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` headers. Quota counters use the same security backend as IP cooldowns. Choose `SECURITY_STORAGE = "database"` or `"redis"` in project `settings.py`. Database mode stores state in the internal `lenapi_security_store` table or MongoDB collection, initialized by migrations. Redis mode uses `REDIS_URL` and requires `pip install 'lenapi[redis]'` plus a running Redis server. The generated settings default to database storage and include `REDIS_URL = "redis://127.0.0.1:6379/0"` for switching to Redis. Shared database or Redis storage coordinates limits across workers. `SECURITY_STORAGE = "memory"` keeps counters in each process, so use it only for single-process development. LenAPI uses the ASGI connection's client address and does not trust forwarded-IP headers automatically; configure trusted proxy handling at your deployment edge before relying on IP quotas behind a proxy.
+When a quota is exceeded, LenAPI returns `429 Too Many Requests` with `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` headers. Quota counters use the same security backend as IP cooldowns. Choose `SECURITY_STORAGE = "database"` or `"redis"` in project `settings.py`. Database mode stores state in the internal `lenapi_security_store` table or MongoDB collection, initialized by migrations. Redis mode uses `REDIS_URL` and requires `python -m pip install 'lenapi[redis]'` plus a running Redis server. Run the install command with the same Python environment that starts LenAPI; keep the quotes around the extra in zsh. The generated settings default to database storage and include `REDIS_URL = "redis://127.0.0.1:6379/0"` for switching to Redis. Shared database or Redis storage coordinates limits across workers. `SECURITY_STORAGE = "memory"` keeps counters in each process, so use it only for single-process development. LenAPI uses the ASGI connection's client address and does not trust forwarded-IP headers automatically; configure trusted proxy handling at your deployment edge before relying on IP quotas behind a proxy.
 
 For example, app-level limits are inherited by routes that do not set their own throttle. A route-specific mapping replaces the inherited mapping, so repeat any global scopes that you still want on that route:
 
@@ -1089,7 +1089,31 @@ app.include_router(public)
 
 The framework-backed JWT authenticator checks the submitted username and password against the database `User` model and its stored password hash. `POST /auth/token` accepts `{"username": "...", "password": "..."}` and returns an access token plus a refresh token. Send the access token as `Authorization: Bearer <access_token>`. `POST /auth/refresh` accepts `{"refresh_token": "..."}` and returns replacement tokens. The token and refresh routes are intentionally hidden from Swagger; protected API routes still show their Bearer scheme and Swagger's **Authorize** control. These routes have a default IP limit of 10 requests per minute, including failed credential checks; pass `throttle={"ip": "5/minute"}` to `jwt.router(...)` for a different limit. In production, use shared `SECURITY_STORAGE = "database"` or `"redis"` for refresh replay protection across workers. Refresh tokens are single-use; the in-memory fallback coordinates only within one process.
 
-For a custom user table, create the JWT dependency with `authentication("jwt", user_model=YourUser)`. Basic and JWT can use your model as long as it has the selected identifier column and a `password` column containing LenAPI-compatible password hashes. For Basic, select the identifier with `BASIC_AUTH_FIELD`. Or configure `JWTAuth` with an `authenticate(username, password)` callback. That callback must verify a password hash and return the user's string ID, `(string_id, claims)`, or `None`. `JWTAuth` signs and verifies HS256 tokens, checks expiry and configured issuer, and rejects refresh tokens when used as access tokens. Keep the signing key secret and serve credentials only over HTTPS.
+For a custom user table, create the JWT dependency with `authentication("jwt", user_model=YourUser)`. Basic and JWT can use your model as long as it has the selected identifier column and a `password` column containing LenAPI-compatible password hashes. For Basic, select the identifier with `BASIC_AUTH_FIELD`. JWT defaults to the `username` column; pass `identifier_field="email"` (or another model column) to use a different login identifier. That field name is also used in the `/auth/token` JSON body. Pass the actual `LENAPI` instance with `app=app` when you want refresh-token replay protection to use its shared security store; do not pass a `Router` there.
+
+For example, a custom model with `email` and a hashed `password` can sign in using `{"email": "ada@example.com", "password": "..."}`:
+
+```python
+from lenapi_bootstrap import create_app
+from lenapi import Depends, authentication
+
+app = create_app(__file__, __package__)
+from app.models import Customer
+auth = authentication(
+    "jwt",
+    user_model=Customer,
+    identifier_field="email",
+    app=app,
+)
+
+app.include_router(auth.router())  # POST /auth/token and POST /auth/refresh
+
+@app.get("/profile", auth=auth)
+def profile(identity=Depends(auth)):
+    return {"customer_id": identity["sub"]}
+```
+
+`Customer` must define an `email` column and a `password` column containing a LenAPI-compatible password hash. Your registration or provisioning flow is responsible for collecting the email and storing the password hash. `JWTAuth` signs and verifies HS256 tokens, checks expiry and configured issuer, and rejects refresh tokens when used as access tokens. Keep the signing key secret and serve credentials only over HTTPS.
 
 ## API-key authentication
 
@@ -1903,7 +1927,7 @@ student = Student.create(
 
 `DateField`, `TimeField`, and `DateTimeField` default to the current UTC date or time when no value or explicit default is supplied. Pass `auto_add_now=False` to disable this behavior, or provide your own `default`. `DurationField(weeks=1)` stores a fixed seven-day `timedelta`; add it to a timestamp when calculating an expiry date. Months and years are calendar intervals and should use calendar-aware date arithmetic.
 
-`PositiveIntegerField` and `PositiveBigIntegerField` reject negative values in LenAPI and add a named database `CHECK` constraint, so direct SQL writes are protected too. `EmailField`, `PhoneField`, `IPField`, `URLField`, and `UUIDField` validate values when a model instance is saved. `PhoneField` accepts a leading `+` followed by country code and digits, up to 18 characters total. `IPField` accepts IPv4 and IPv6. `URLField` accepts `http://`, `https://`, and `www.` URLs. Customize messages with `error_messages`, for example `email = model.EmailField(error_messages={"email": "This is not an email"})`; `unique` is also a supported message key for a unique field.
+`PositiveIntegerField` and `PositiveBigIntegerField` reject negative values in LenAPI and add a named database `CHECK` constraint, so direct SQL writes are protected too. `EmailField`, `PhoneField`, `IPField`, `URLField`, and `UUIDField` validate values when a model instance is saved. `PhoneField` accepts either a `+` country-code number or a local number beginning with `0`, up to 18 characters. Declare phone numbers as strings and send them quoted in JSON so leading zeroes are preserved; bare JSON numbers such as `08099448550` are invalid JSON. `IPField` accepts IPv4 and IPv6. `URLField` accepts `http://`, `https://`, and `www.` URLs. Customize messages with `error_messages`, for example `email = model.EmailField(error_messages={"email": "This is not an email"})`; `unique` is also a supported message key for a unique field.
 
 The base model supplies an auto-incrementing integer `id`. A model may declare its own primary key instead; LenAPI will not add a second `id` key:
 
@@ -2082,7 +2106,14 @@ async_total = async_page.total_count
 async_pages = async_page.page_count
 ```
 
-`Student.get.all()` returns all rows synchronously; its async counterpart is `await Student.aget.all()`. For filtered async lists, use `await Student.afilter(...).all()`. `Student.get(...)` builds a single-row lookup; call `.get()` for the model instance or `.exists()` for a boolean. The async single-row counterpart is `await Student.aget(...)`, and its existence check is `await Student.aget(...).exists()`. Multiple matches are an error rather than an arbitrary row selection. `Student.get("field", ...).get(...)` selects one or more columns; one selected column returns a scalar and multiple columns return a mapping. This is a query projection, not a uniqueness constraint. To make the database reject duplicates, declare `unique=True` on the field.
+`Student.get.all()` returns all rows synchronously; its async counterpart is `await Student.aget.all()`. For filtered lists, use `Student.filter(...).all()` or `await Student.afilter(...).all()`. Both sync and async filtered querysets support existence checks:
+
+```python
+has_python_students = Student.filter(course="Python").exists()
+has_python_students_async = await Student.afilter(course="Python").exists()
+```
+
+`Student.get(...)` builds a single-row lookup; call `.get()` for the model instance or `.exists()` for a boolean. The async single-row counterpart is `await Student.aget(...)`, and its existence check is `await Student.aget(...).exists()`. Multiple matches are an error rather than an arbitrary row selection. `Student.get("field", ...).get(...)` selects one or more columns; one selected column returns a scalar and multiple columns return a mapping. This is a query projection, not a uniqueness constraint. To make the database reject duplicates, declare `unique=True` on the field.
 
 ### Fetch related records
 

{lenapi-0.1.3 → lenapi-0.1.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lenapi"
-version = "0.1.3"
+version = "0.1.4.1"
 description = "A modern ASGI framework with Pydantic validation, sync and async database access, WebSockets, authentication, and integrated API documentation."
 authors = [
     {name = "Ifeanyi M. Onovo", email = "ifeanyi@maekandex.com.ng"},

{lenapi-0.1.3 → lenapi-0.1.4.1}/tests/test_framework_features.py

@@ -143,6 +143,38 @@ def test_lenapi_is_the_only_public_application_class():
     app.database.close()
 
 
+def test_malformed_json_returns_400_instead_of_server_error():
+    app = make_app()
+
+    class Payload(BaseModel):
+        phone_number: str
+
+    @app.post("/payload")
+    def payload(data: Payload):
+        return {"phone_number": data.phone_number}
+
+    valid_status, _, valid_body = asgi_request(
+        app,
+        "/payload",
+        method="POST",
+        body=b'{"phone_number": "08099448550"}',
+        headers=[(b"content-type", b"application/json")],
+    )
+    assert valid_status == 200
+    assert json.loads(valid_body) == {"phone_number": "08099448550"}
+
+    status, _, body = asgi_request(
+        app,
+        "/payload",
+        method="POST",
+        body=b'{"phone_number": 08099448550}',
+        headers=[(b"content-type", b"application/json")],
+    )
+    assert status == 400
+    assert json.loads(body) == {"detail": "Malformed JSON request body"}
+    app.database.close()
+
+
 def test_multiple_routers_validation_response_models_and_openapi_visibility():
     class Input(BaseModel):
         name: str
@@ -690,6 +722,8 @@ def test_model_fields_defaults_uuid_unique_indexes_and_all_crud_helpers(tmp_path
         assert FeatureRecord.get(name="Ada").get().info == {"active": True}
         assert FeatureRecord.get_or_404(name="Grace").amount == Decimal("25.00")
         assert FeatureRecord.get(name="missing").exists() is False
+        assert FeatureRecord.filter(group="math").exists() is True
+        assert FeatureRecord.filter(group="missing").exists() is False
         assert FeatureRecord.get_or_create(name="Ada")[1] is False
         assert FeatureRecord.get_or_create({"group": "logic"}, name="Turing")[0].group == "logic"
         assert FeatureRecord.create_update({"amount": Decimal("13")}, name="Ada").amount == Decimal("13")
@@ -836,7 +870,7 @@ def test_new_fields_validate_values_and_default_temporal_fields(tmp_path):
     db = Database(f"sqlite:///{tmp_path / 'new-model-fields.db'}")
     tables = [
         PositiveFieldRecord.__table__, TimestampDurationRecord.__table__,
-        UniqueMessageRecord.__table__,
+        UniqueMessageRecord.__table__, ValidatedFieldRecord.__table__,
     ]
     Model.metadata.create_all(db.engine, tables=tables)
     session = db.session()
@@ -854,6 +888,12 @@ def test_new_fields_validate_values_and_default_temporal_fields(tmp_path):
         assert isinstance(record.created_at, datetime)
         assert record.trial_period == timedelta(days=7)
 
+        local_phone = ValidatedFieldRecord.create(
+            email="local@example.com", phone="08099448550", address="127.0.0.1",
+            website="https://example.com", public_id=uuid.uuid4(),
+        )
+        assert local_phone.phone == "08099448550"
+
         UniqueMessageRecord.create(email="ada@example.com")
         with pytest.raises(HTTPException) as duplicate:
             UniqueMessageRecord.create(email="ada@example.com")
@@ -1016,6 +1056,46 @@ def test_authentication_factory_modes_and_database_user_password_helpers():
     assert callable(register_user)
 
 
+def test_jwt_custom_identifier_uses_email_for_lookup_and_token_request(monkeypatch):
+    class EmailAuthCustomer(Model):
+        email = StringField(max_length=254, unique=True)
+        password = StringField(max_length=255)
+
+    from lenapi import authentication
+
+    settings = SimpleNamespace(
+        AUTHENTICATION="jwt",
+        TOKEN={"SECRET_KEY": "e" * 32},
+    )
+    auth = authentication(
+        "jwt",
+        settings=settings,
+        user_model=EmailAuthCustomer,
+        identifier_field="email",
+    )
+    lookups = []
+
+    class QueryResult:
+        def get(self):
+            return SimpleNamespace(id=17, password="encoded-password")
+
+    def fake_get(cls, **filters):
+        lookups.append(filters)
+        return QueryResult()
+
+    auth_module = importlib.import_module("lenapi.authentication")
+    monkeypatch.setattr(EmailAuthCustomer, "get", classmethod(fake_get))
+    monkeypatch.setattr(auth_module, "check_password", lambda raw, encoded: encoded == "encoded-password")
+
+    assert auth.authenticate("ada@example.com", "secret") == "17"
+    assert lookups == [{"email": "ada@example.com"}]
+
+    token_router = auth.router()
+    token_route = next(route for route in token_router.routes if route.path == "/auth/token")
+    credentials_model = token_route.endpoint.__annotations__["credentials"]
+    assert set(credentials_model.model_fields) == {"email", "password"}
+
+
 def test_custom_model_api_key_field_is_required_validated_and_used(monkeypatch):
     class CustomerForAPIKey(Model):
         username = StringField(max_length=64, unique=True)