easyapi-django 1.3.1__tar.gz → 1.3.2__tar.gz

{easyapi_django-1.3.1/easyapi_django.egg-info → easyapi_django-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easyapi-django
-Version: 1.3.1
+Version: 1.3.2
 Summary: Zero-effort MCP server (and REST API) generator from Django models.
 Author-email: Stamatios Stamou Jr <bushier.outsets.0c@icloud.com>
 License-Expression: MIT
@@ -174,7 +174,7 @@ REST is mostly a solved problem now. The new pain is MCP — most teams are rebu
 - Multi-tenant DB routing. One call switches the connection for the request.
 - Sliding session TTLs via Redis `GETEX`. Configure with `SESSION_TTL` (default 1800s) and `API_SESSION_TTL` (default 300s).
 - Sensitive-field scrubbing (`password`, `api_key`, `token` baseline plus your additions) — applied on both REST and MCP responses.
-- Global read-only switch (`MCP = {'READ_ONLY': True}`) rejects every non-`GET` request with `405`.
+- Global read-only switch (`EASYAPI = {'READ_ONLY': True}`) rejects every non-`GET` request with `405`.
 - Async end-to-end. Async ORM, async Redis, async dispatch.
 
 Full docs and reference: https://github.com/ssjunior/easyapi-django
@@ -233,11 +233,12 @@ Defaults are demo-friendly. Production deployments should:
 - **Per-resource ownership.** Set `owner_field = 'owner_id'` on resources where rows belong to a single user — restricts every CRUD operation to the row's owner. `POST` always forces `owner_id` to the caller (override with `allow_owner_override = True` for admin paths).
 - **Authenticated cache.** If you turn on `cache = True` for an authenticated resource, set `session_cache = True` or `cache_scope_fields = (...)` — otherwise responses can leak across users. The framework warns at runtime when it detects this combination.
 - **Tune session TTLs.** `SESSION_TTL` (cookies, default 1800s) and `API_SESSION_TTL` (api-key cache, default 300s) both slide on use. Pick numbers that match your security/UX trade-off.
-- **Never ship `DEBUG = True`.** Under `DEBUG`, edge security (scanner blocking, 4xx flood detection), rate limiting, credential-path defense and abuse blocking are all bypassed for dev ergonomics. The framework logs a loud startup warning when the bypass is active. To decouple from `DEBUG` — e.g. a staging box mirroring production — set `MCP = {'SECURITY_BYPASS': False}` to force protections on (or `True` to bypass without `DEBUG`).
+- **Never ship `DEBUG = True`.** Under `DEBUG`, edge security (scanner blocking, 4xx flood detection), rate limiting, credential-path defense and abuse blocking are all bypassed for dev ergonomics. The framework logs a loud startup warning when the bypass is active. To decouple from `DEBUG` — e.g. a staging box mirroring production — set `EASYAPI = {'SECURITY_BYPASS': False}` to force protections on (or `True` to bypass without `DEBUG`).
 - **Trust your proxies explicitly.** IP-based rate limits and abuse blocking key on the client IP. `X-Forwarded-For` / `X-Real-IP` are only honored when `REMOTE_ADDR` is in `TRUSTED_PROXIES = ['10.0.0.0/8', ...]`; otherwise `REMOTE_ADDR` wins. Leave it unset behind a proxy and every request looks like it comes from the proxy.
-- **Bound the metrics surface.** The `/metrics` endpoint queries any model in the registry by default. Set `METRICS_MODELS = ['app_Model', ...]` to allowlist which models are queryable. References to credential-named columns (in filters, groups, order or calc) are always rejected — the per-resource escape hatch does not reach `/metrics`.
+- **`/metrics` is opt-in.** `get_routes` doesn't mount it unless you pass `metrics_view=Metrics` (the generic, unscoped resource — `from easyapi import Metrics`) or a custom row-scoped subclass. Once mounted, bound which models it can query: set `METRICS_MODELS = ['app_Model', ...]` to allowlist them. References to credential-named columns (in filters, groups, order or calc) are always rejected regardless — the per-resource escape hatch does not reach `/metrics`.
+- **Bound the metrics fields, per model.** `METRICS_MODELS` only gates *which models* — every non-credential field on an allowed model is still fair game for `/metrics` (filter, group, order, calc), including arbitrary FK traversal. Set `METRICS_FIELDS = {'app_Model': ['status', 'owner__name', ...]}` to also allowlist *which field paths*, per model. Unlike REST's `filter_fields` (root-segment match), this checks the **full** `__`-joined path — `'owner'` in the list does not imply `'owner__anything'` is allowed. `filter_by` references tolerate one trailing Django lookup (`owner__name__icontains` matches an allowed `owner__name`) since those reach `Q(**kwargs)` directly; `calc`/`group_by`/`order`/`additional_fields`/`conditions` don't take lookups and are matched literally. A model absent from the dict, or the setting left unset, stays unrestricted — opt-in, same as `METRICS_MODELS`. If you already maintain a `bi_fields`/`related_fields` map for a frontend field picker, `easyapi.util.flatten_include_fields(model, bag)` turns that same data into the flat path list this setting expects, so there's one source of truth instead of two.
 - **Keep the escape hatch narrow.** Columns whose names look like credentials (`password`, `api_key`, `token`, `otp`, `secret`, …) are masked as `'*********'` on every response, on top of whatever `sensitive_fields` lists. When the heuristic catches a false positive, opt it out per surface: `edit_allow_sensitive_fields = ['token_count']` returns it verbatim on `GET /resource/<id>/` while LIST still masks it. `list_allow_sensitive_fields` does the same for LIST, where every row carries the value — reach for the detail-only form first.
-- **OAuth clients are public by default.** MCP clients (Claude.ai, ChatGPT, ...) authenticate with PKCE — list them under `MCP['OAUTH_CLIENTS']` with no `client_secret`. A client becomes confidential only with an explicit secret; `/register` never hands out a confidential secret (provision those out of band).
+- **OAuth clients are public by default.** MCP clients (Claude.ai, ChatGPT, ...) authenticate with PKCE — list them under `EASYAPI['OAUTH_CLIENTS']` with no `client_secret`. A client becomes confidential only with an explicit secret; `/register` never hands out a confidential secret (provision those out of band).
 
 ---
 

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/README.md

@@ -130,7 +130,7 @@ REST is mostly a solved problem now. The new pain is MCP — most teams are rebu
 - Multi-tenant DB routing. One call switches the connection for the request.
 - Sliding session TTLs via Redis `GETEX`. Configure with `SESSION_TTL` (default 1800s) and `API_SESSION_TTL` (default 300s).
 - Sensitive-field scrubbing (`password`, `api_key`, `token` baseline plus your additions) — applied on both REST and MCP responses.
-- Global read-only switch (`MCP = {'READ_ONLY': True}`) rejects every non-`GET` request with `405`.
+- Global read-only switch (`EASYAPI = {'READ_ONLY': True}`) rejects every non-`GET` request with `405`.
 - Async end-to-end. Async ORM, async Redis, async dispatch.
 
 Full docs and reference: https://github.com/ssjunior/easyapi-django
@@ -189,11 +189,12 @@ Defaults are demo-friendly. Production deployments should:
 - **Per-resource ownership.** Set `owner_field = 'owner_id'` on resources where rows belong to a single user — restricts every CRUD operation to the row's owner. `POST` always forces `owner_id` to the caller (override with `allow_owner_override = True` for admin paths).
 - **Authenticated cache.** If you turn on `cache = True` for an authenticated resource, set `session_cache = True` or `cache_scope_fields = (...)` — otherwise responses can leak across users. The framework warns at runtime when it detects this combination.
 - **Tune session TTLs.** `SESSION_TTL` (cookies, default 1800s) and `API_SESSION_TTL` (api-key cache, default 300s) both slide on use. Pick numbers that match your security/UX trade-off.
-- **Never ship `DEBUG = True`.** Under `DEBUG`, edge security (scanner blocking, 4xx flood detection), rate limiting, credential-path defense and abuse blocking are all bypassed for dev ergonomics. The framework logs a loud startup warning when the bypass is active. To decouple from `DEBUG` — e.g. a staging box mirroring production — set `MCP = {'SECURITY_BYPASS': False}` to force protections on (or `True` to bypass without `DEBUG`).
+- **Never ship `DEBUG = True`.** Under `DEBUG`, edge security (scanner blocking, 4xx flood detection), rate limiting, credential-path defense and abuse blocking are all bypassed for dev ergonomics. The framework logs a loud startup warning when the bypass is active. To decouple from `DEBUG` — e.g. a staging box mirroring production — set `EASYAPI = {'SECURITY_BYPASS': False}` to force protections on (or `True` to bypass without `DEBUG`).
 - **Trust your proxies explicitly.** IP-based rate limits and abuse blocking key on the client IP. `X-Forwarded-For` / `X-Real-IP` are only honored when `REMOTE_ADDR` is in `TRUSTED_PROXIES = ['10.0.0.0/8', ...]`; otherwise `REMOTE_ADDR` wins. Leave it unset behind a proxy and every request looks like it comes from the proxy.
-- **Bound the metrics surface.** The `/metrics` endpoint queries any model in the registry by default. Set `METRICS_MODELS = ['app_Model', ...]` to allowlist which models are queryable. References to credential-named columns (in filters, groups, order or calc) are always rejected — the per-resource escape hatch does not reach `/metrics`.
+- **`/metrics` is opt-in.** `get_routes` doesn't mount it unless you pass `metrics_view=Metrics` (the generic, unscoped resource — `from easyapi import Metrics`) or a custom row-scoped subclass. Once mounted, bound which models it can query: set `METRICS_MODELS = ['app_Model', ...]` to allowlist them. References to credential-named columns (in filters, groups, order or calc) are always rejected regardless — the per-resource escape hatch does not reach `/metrics`.
+- **Bound the metrics fields, per model.** `METRICS_MODELS` only gates *which models* — every non-credential field on an allowed model is still fair game for `/metrics` (filter, group, order, calc), including arbitrary FK traversal. Set `METRICS_FIELDS = {'app_Model': ['status', 'owner__name', ...]}` to also allowlist *which field paths*, per model. Unlike REST's `filter_fields` (root-segment match), this checks the **full** `__`-joined path — `'owner'` in the list does not imply `'owner__anything'` is allowed. `filter_by` references tolerate one trailing Django lookup (`owner__name__icontains` matches an allowed `owner__name`) since those reach `Q(**kwargs)` directly; `calc`/`group_by`/`order`/`additional_fields`/`conditions` don't take lookups and are matched literally. A model absent from the dict, or the setting left unset, stays unrestricted — opt-in, same as `METRICS_MODELS`. If you already maintain a `bi_fields`/`related_fields` map for a frontend field picker, `easyapi.util.flatten_include_fields(model, bag)` turns that same data into the flat path list this setting expects, so there's one source of truth instead of two.
 - **Keep the escape hatch narrow.** Columns whose names look like credentials (`password`, `api_key`, `token`, `otp`, `secret`, …) are masked as `'*********'` on every response, on top of whatever `sensitive_fields` lists. When the heuristic catches a false positive, opt it out per surface: `edit_allow_sensitive_fields = ['token_count']` returns it verbatim on `GET /resource/<id>/` while LIST still masks it. `list_allow_sensitive_fields` does the same for LIST, where every row carries the value — reach for the detail-only form first.
-- **OAuth clients are public by default.** MCP clients (Claude.ai, ChatGPT, ...) authenticate with PKCE — list them under `MCP['OAUTH_CLIENTS']` with no `client_secret`. A client becomes confidential only with an explicit secret; `/register` never hands out a confidential secret (provision those out of band).
+- **OAuth clients are public by default.** MCP clients (Claude.ai, ChatGPT, ...) authenticate with PKCE — list them under `EASYAPI['OAUTH_CLIENTS']` with no `client_secret`. A client becomes confidential only with an explicit secret; `/register` never hands out a confidential secret (provision those out of band).
 
 ---
 

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/__init__.py

@@ -16,6 +16,7 @@ except PackageNotFoundError:        # editable/dev checkout without metadata
 try:
     from easyapi.auth import make_token, validate_token, validate_token_async  # noqa: F401
     from easyapi.base import BaseResource  # noqa
+    from easyapi.calc_resource import Metrics  # noqa
     from easyapi.core import CoreResource, endpoint  # noqa: F401
     from easyapi.exception import HTTPException  # noqa
     from easyapi.middleware import AuthMiddleware, ExceptionMiddleware  # noqa

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/base.py

@@ -116,7 +116,7 @@ def _warn_csrf_unprotected_at_startup():
     logger.warning(
         'authenticated mode is on but neither ENFORCE_TOKEN nor '
         'ALLOWED_ORIGINS is configured — no anti-CSRF defense at the '
-        'framework level. Set at least one in the MCP settings dict, '
+        'framework level. Set at least one in the EASYAPI settings dict, '
         'or harden cookies at the deployment layer.',
     )
 
@@ -138,7 +138,7 @@ def _warn_if_security_bypassed_at_startup():
             'limiting, credential-path defense and abuse blocking are '
             'DISABLED (SECURITY_BYPASS set, or DEBUG=True with '
             'SECURITY_BYPASS unset). Never run this in production; set '
-            "MCP['SECURITY_BYPASS'] = False to force protections on.",
+            "EASYAPI['SECURITY_BYPASS'] = False to force protections on.",
         )
 
 
@@ -147,7 +147,7 @@ _warn_if_security_bypassed_at_startup()
 
 class BaseResource(CoreResource):
     # ``True`` historically. Override globally via
-    # ``MCP = {'DEFAULT_AUTHENTICATED': False}`` (the generator emits
+    # ``EASYAPI = {'DEFAULT_AUTHENTICATED': False}`` (the generator emits
     # this for demo-friendly first-run experience), or per-resource
     # by setting ``authenticated = False`` on a subclass.
     authenticated = DEFAULT_AUTHENTICATED

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/calc.py

@@ -19,7 +19,9 @@ from .dates import Dates
 from .exception import HTTPException
 from .filters import Filter as OrmFilter
 from .sensitive import looks_sensitive
-from .settings_helper import get_metrics_max_execution_ms, get_metrics_models
+from .settings_helper import (
+    get_metrics_fields, get_metrics_max_execution_ms, get_metrics_models,
+)
 from .util import normalize_field
 
 SAFE_OPS = {
@@ -584,52 +586,99 @@ def _collect_condition_fields(node, refs):
             _collect_condition_fields(item, refs)
 
 
-def _reject_sensitive_fields(data):
-    """Block any field reference in the metrics body that touches a
-    credential-named column.
+_DJANGO_LOOKUPS = frozenset({
+    'exact', 'iexact', 'contains', 'icontains', 'in',
+    'gt', 'gte', 'lt', 'lte', 'startswith', 'istartswith',
+    'endswith', 'iendswith', 'range', 'date', 'year', 'iso_year',
+    'month', 'day', 'week', 'week_day', 'iso_week_day', 'quarter',
+    'time', 'hour', 'minute', 'second', 'isnull', 'regex', 'iregex',
+})
 
-    The metrics endpoint references models/fields straight from the
-    request body — filters, groups, order and calc targets. Without this
-    guard, an authenticated caller can turn counts into a boolean oracle
-    (``owner__password__startswith=a`` → read the count) or read values
-    directly (``group_by.fields=['owner__api_key']`` → the api_key comes
-    back as a group label; the LIST/detail sensitive-field scrub does not
-    cover metrics output). We reject any reference whose ``__``-split
-    segments include a sensitive name.
+
+def _strip_known_lookup(ref):
+    """Strip one trailing Django lookup segment (``__icontains``, ``__gte``,
+    ...) if present. Returns ``None`` when there's nothing recognized to
+    strip, so callers can distinguish "no lookup suffix" from "stripped to
+    an empty path"."""
+    if '__' not in ref:
+        return None
+    head, _, tail = ref.rpartition('__')
+    return head if tail in _DJANGO_LOOKUPS else None
+
+
+def _collect_metrics_field_refs(data):
+    """Walk the metrics request body and collect every field reference —
+    filters, groups, order and calc targets — as they appear verbatim
+    (``__``-joined paths). Shared by ``_reject_sensitive_fields`` and
+    ``_check_field_allowlist`` so both see the exact same surface; collecting
+    twice risks one guard covering a body key the other misses.
+
+    Returns ``(strict_refs, filter_refs, order_refs)``. ``filter_refs`` are
+    ``filter_by.fields`` keys (including ``or_conditions`` entries) — these
+    reach ``queryset.filter(**kwargs)``/``Q(**kwargs)`` directly, so they may
+    carry a trailing Django lookup (``owner__name__icontains``) that isn't
+    part of the field path itself. ``order_refs`` are ``order`` entries
+    (``-`` stripped) — these may reference either a real field/path or a
+    ``calc.formula`` name (``count``, ``sum``, ...), since ``group_by``
+    annotates the queryset with the formula name as the aggregation's alias
+    and ``order_by`` can target that alias directly (see ``group_by()``).
+    Every other reference (``calc``, ``group_by``, ``additional_fields``,
+    ``period.field``, Layer-2 ``conditions``) is a bare field/path — Layer-2
+    conditions carry the lookup in a separate ``operator`` key, not appended
+    to ``field``.
     """
-    refs = []
+    strict_refs = []
+    filter_refs = []
+    order_refs = []
 
     calc_cfg = data.get('calc') or {}
     on_field = calc_cfg.get('field')
     if isinstance(on_field, str):
-        refs.append(on_field)
+        strict_refs.append(on_field)
     elif isinstance(on_field, list):
-        refs += [f for f in on_field if isinstance(f, str)]
+        strict_refs += [f for f in on_field if isinstance(f, str)]
 
     gb = data.get('group_by') or {}
-    refs += [f for f in (gb.get('fields') or []) if isinstance(f, str)]
+    strict_refs += [f for f in (gb.get('fields') or []) if isinstance(f, str)]
     date_group = gb.get('date') or {}
     if isinstance(date_group.get('field'), str):
-        refs.append(date_group['field'])
+        strict_refs.append(date_group['field'])
 
-    refs += [f for f in (data.get('additional_fields') or []) if isinstance(f, str)]
-    refs += [o.lstrip('-') for o in (data.get('order') or []) if isinstance(o, str)]
+    strict_refs += [f for f in (data.get('additional_fields') or []) if isinstance(f, str)]
+    order_refs += [o.lstrip('-') for o in (data.get('order') or []) if isinstance(o, str)]
 
     filter_by = data.get('filter_by') or {}
     for key, value in (filter_by.get('fields') or {}).items():
         if key == 'or_conditions':
             for cond in value or []:
                 if isinstance(cond, dict):
-                    refs += list(cond.keys())
+                    filter_refs += list(cond.keys())
         else:
-            refs.append(key)
+            filter_refs.append(key)
     period = filter_by.get('period') or {}
     if isinstance(period.get('field'), str):
-        refs.append(period['field'])
+        strict_refs.append(period['field'])
+
+    _collect_condition_fields(data.get('conditions'), strict_refs)
 
-    _collect_condition_fields(data.get('conditions'), refs)
+    return strict_refs, filter_refs, order_refs
 
-    for ref in refs:
+
+def _reject_sensitive_fields(data):
+    """Block any field reference in the metrics body that touches a
+    credential-named column.
+
+    The metrics endpoint references models/fields straight from the
+    request body — filters, groups, order and calc targets. Without this
+    guard, an authenticated caller can turn counts into a boolean oracle
+    (``owner__password__startswith=a`` → read the count) or read values
+    directly (``group_by.fields=['owner__api_key']`` → the api_key comes
+    back as a group label; the LIST/detail sensitive-field scrub does not
+    cover metrics output). We reject any reference whose ``__``-split
+    segments include a sensitive name.
+    """
+    strict_refs, filter_refs, order_refs = _collect_metrics_field_refs(data)
+    for ref in strict_refs + filter_refs + order_refs:
         for segment in str(ref).split('__'):
             if looks_sensitive(segment):
                 raise HTTPException(
@@ -639,6 +688,62 @@ def _reject_sensitive_fields(data):
                 )
 
 
+def _check_field_allowlist(data, model_label):
+    """Enforce ``EASYAPI['METRICS_FIELDS']`` (see ``get_metrics_fields``) when the
+    project has configured an allowlist for ``model_label``. Each reference
+    must match a listed path exactly — full ``__``-joined path, not just the
+    root segment. A model absent from the configured dict, or the setting
+    left unset entirely, is unrestricted (opt-in, preserves current
+    behavior).
+
+    ``filter_by`` references try the literal path first; only when that
+    fails and the trailing segment is a recognized Django lookup
+    (``__icontains``, ``__gte``, ...) do we retry without it — a filter
+    allowed on a field shouldn't require enumerating every lookup variant.
+    ``order`` references try the literal path first too, then fall back to
+    matching a ``calc.formula`` name (``count``, ``sum``, ...) — ``group_by``
+    annotates the queryset with the formula name as the aggregation's alias,
+    so ``order: ['-count']`` targets that alias, not a model field, and
+    would otherwise 403 on every grouped/aggregated request. Every other
+    reference must match literally: neither a lookup suffix nor a formula
+    alias is valid there, so allowing either would loosen the check for no
+    reason.
+    """
+    allowed_by_model = get_metrics_fields()
+    if not allowed_by_model or model_label not in allowed_by_model:
+        return
+
+    allowed = allowed_by_model[model_label]
+    strict_refs, filter_refs, order_refs = _collect_metrics_field_refs(data)
+
+    for ref in strict_refs:
+        if ref not in allowed:
+            raise HTTPException(
+                403,
+                f'Field not allowed for metrics on "{model_label}": {ref}',
+            )
+
+    for ref in filter_refs:
+        if ref in allowed:
+            continue
+        stripped = _strip_known_lookup(ref)
+        if stripped is not None and stripped in allowed:
+            continue
+        raise HTTPException(
+            403,
+            f'Field not allowed for metrics on "{model_label}": {ref}',
+        )
+
+    calc_formulas = (data.get('calc') or {}).get('formula') or []
+    for ref in order_refs:
+        if ref in allowed or ref in calc_formulas:
+            continue
+        raise HTTPException(
+            403,
+            f'Field not allowed for metrics on "{model_label}": {ref}',
+        )
+
+
 async def get_results(timezone, data, base_queryset=None):
     """Entry point for the metrics endpoint.
 
@@ -659,6 +764,7 @@ async def get_results(timezone, data, base_queryset=None):
         raise HTTPException(403, f'Metrics not allowed for model "{model_label}"')
 
     _reject_sensitive_fields(data)
+    _check_field_allowlist(data, model_label)
 
     model = get_model(model_label)
 

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/gen/cli.py

@@ -297,7 +297,7 @@ def _print_next_steps(out: Path, sample: dict | None, *, read_only: bool = False
         print(
             '\n⚠  this project was generated read-only — once you register\n'
             '   MCP toolsets, `POST /mcp` will return 405. Re-run with\n'
-            '   `--writable` (or drop `MCP[\'READ_ONLY\']` in settings.py)\n'
+            '   `--writable` (or drop `EASYAPI[\'READ_ONLY\']` in settings.py)\n'
             '   if you plan to expose an MCP server.',
             file=sys.stderr,
         )

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/gen/config.py

@@ -47,7 +47,7 @@ class Project:
     backend: str
     database: str
     # When True (default), the generated ``settings.py`` carries
-    # ``MCP = {'READ_ONLY': True}`` — a global gate that rejects every
+    # ``EASYAPI = {'READ_ONLY': True}`` — a global gate that rejects every
     # non-GET request with 405 across all resources (REST + MCP).
     # Safer first-run default for projects pointed at an existing
     # database; flip with ``--writable`` to drop the gate.

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/oauth/clients.py

@@ -1,8 +1,8 @@
 """Lazy accessor for the configured OAuth clients.
 
-The project defines its clients under ``MCP['OAUTH_CLIENTS']``::
+The project defines its clients under ``EASYAPI['OAUTH_CLIENTS']``::
 
-    MCP = {
+    EASYAPI = {
         'OAUTH_CLIENTS': {
             'claude': {
                 # Public client — MCP clients (Claude.ai, other LLMs)
@@ -31,7 +31,7 @@ from .settings_helper import get_oauth_clients
 
 class _ClientsView:
     """Dict-like proxy that re-reads settings on every access so tests
-    overriding ``MCP['OAUTH_CLIENTS']`` see fresh data without an
+    overriding ``EASYAPI['OAUTH_CLIENTS']`` see fresh data without an
     import-time freeze."""
 
     def __contains__(self, key):

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/oauth/constants.py

@@ -1,6 +1,6 @@
 """Static constants for the OAuth sub-package.
 
-``SCOPE.ALL`` is built lazily from ``MCP['OAUTH_SCOPES']`` so the set
+``SCOPE.ALL`` is built lazily from ``EASYAPI['OAUTH_SCOPES']`` so the set
 of advertised scopes stays project-defined.
 """
 from .settings_helper import get_oauth_scopes

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/oauth/migrations/0001_initial.py

@@ -6,7 +6,7 @@ from easyapi.oauth.settings_helper import get_oauth_user_model
 
 # Resolve the FK target at import time, mirroring Django's own
 # ``settings.AUTH_USER_MODEL`` pattern. Projects must set
-# ``MCP['OAUTH_USER_MODEL']`` BEFORE running the first migrate;
+# ``EASYAPI['OAUTH_USER_MODEL']`` BEFORE running the first migrate;
 # changing it later requires a new migration in the project.
 _USER_MODEL = get_oauth_user_model()
 

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/oauth/resolver.py

@@ -19,7 +19,7 @@ Contract for ``OAUTH_USER_RESOLVER`` (dotted path in ``MCP``)::
         '''
 
 When no resolver is configured, a minimal fallback resolves the user
-via ``MCP['OAUTH_USER_MODEL']`` and returns ``{'user': {'id': ...},
+via ``EASYAPI['OAUTH_USER_MODEL']`` and returns ``{'user': {'id': ...},
 'account': {'id': account_id}}``.
 """
 from django.apps import apps

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/oauth/routes.py

@@ -2,7 +2,7 @@
 
 Returns the full RFC 6749 + RFC 8628 surface so the project can plug
 it into its ``urls.py`` with a single call. Returns ``[]`` when
-``MCP['OAUTH_URL']`` is not configured — keeps the surface invisible
+``EASYAPI['OAUTH_URL']`` is not configured — keeps the surface invisible
 for projects that don't use OAuth.
 """
 from django.urls import path
@@ -13,7 +13,7 @@ from easyapi.settings_helper import get_oauth_url
 def get_oauth_routes():
     """Return Django URL patterns for the OAuth endpoints.
 
-    Returns empty list if ``MCP['OAUTH_URL']`` is not configured.
+    Returns empty list if ``EASYAPI['OAUTH_URL']`` is not configured.
     """
     if not get_oauth_url():
         return []

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/oauth/settings_helper.py

@@ -1,7 +1,8 @@
 """Module-local helpers around ``easyapi.settings_helper.get_setting``.
 
 All project-specific knobs for the OAuth sub-package live under the
-shared ``MCP`` settings dict. Each helper here returns a safe default
+shared ``EASYAPI`` settings dict (``MCP`` as a legacy alias — see
+``easyapi.settings_helper``). Each helper here returns a safe default
 so the package can be imported (and migrated) before the project has
 configured anything OAuth-specific.
 """
@@ -46,7 +47,7 @@ def get_oauth_clients():
     A client becomes **confidential** only by opting in explicitly:
 
       * ``'client_secret': '<value>'`` — that literal secret, or
-      * ``'client_secret': ''``        — share ``MCP['OAUTH_SECRET']``
+      * ``'client_secret': ''``        — share ``EASYAPI['OAUTH_SECRET']``
         across confidential clients without repeating it (``None`` when
         ``OAUTH_SECRET`` is unset).
 

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/routes.py

@@ -5,7 +5,6 @@ from django.urls import path, re_path
 from django.http import HttpResponse, JsonResponse
 
 from . import bearer as _bearer
-from .calc_resource import Metrics
 from .openapi import SCALAR_HTML, build_spec
 from .redis_config import KEY_PREFIX, get_redis, getex as redis_getex
 from .settings_helper import (
@@ -66,12 +65,12 @@ def get_routes(endpoints, **kwargs):
     to make them anonymous; default is ``False`` (requires the same auth as
     the rest of the API — session cookie or X-Api-Key).
 
-    ``metrics_view`` controls the built-in ``/metrics`` route. Default mounts
-    the generic :class:`Metrics` (no row scoping). Pass a custom resource to
-    replace it (e.g. a role-scoped subclass that injects a ``base_queryset``),
-    or ``None`` to not mount it at all — so a project that owns row scoping
-    can guarantee the unscoped route does not exist, instead of relying on
-    URL-order shadowing.
+    ``metrics_view`` controls the built-in ``/metrics`` route. Default is
+    ``None`` — not mounted. Pass :class:`Metrics` to opt into the generic
+    (no row scoping) resource, or a custom resource (e.g. a role-scoped
+    subclass that injects a ``base_queryset``) to replace it. Metrics is a
+    real attack surface if left on by accident, so a project has to ask for
+    it explicitly rather than lose it silently to a missed override.
     """
     from . import __version__ as _easyapi_version
 
@@ -79,7 +78,7 @@ def get_routes(endpoints, **kwargs):
     spec_version = kwargs.get('version', _easyapi_version)
     spec_description = kwargs.get('description')
     docs_public = kwargs.get('docs_public', False)
-    metrics_view = kwargs.get('metrics_view', Metrics)
+    metrics_view = kwargs.get('metrics_view', None)
 
     async def openapi_json(request, *args, **kwargs):
         if not docs_public and not await _has_valid_session(request):

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/security.py

@@ -22,6 +22,12 @@ from .redis_config import KEY_PREFIX, get_redis
 
 from .settings_helper import get_setting, security_bypassed
 
+# EASYAPI['BLOCK_PATTERNS']/EASYAPI['BLOCK_USER_AGENTS'] *replace* the framework
+# defaults below — they do not merge. A project that already sets either key
+# gets none of the patterns/signatures added here in later versions; copy the
+# current DEFAULT_BLOCK_PATTERNS/DEFAULT_BLOCK_USER_AGENTS into the override
+# and extend it instead of starting from an empty list, or new protections
+# added upstream won't reach that project until the override is refreshed.
 BLOCK_PATTERNS = get_setting('BLOCK_PATTERNS')
 BLOCK_USER_AGENTS = get_setting('BLOCK_USER_AGENTS')
 MAX_4XX_PER_MINUTE = get_setting('MAX_4XX_PER_MINUTE', default=10)
@@ -36,10 +42,14 @@ DEFAULT_BLOCK_PATTERNS = [
     r'/(cgi-bin|fcgi-bin|server-status|server-info)',
     r'/(actuator|jmx-console|config\.json|appsettings\.json)',
     r'\.\./|%2e%2e|\.\.\\',
-    r'\bunion\s+select\b|\bor\s+1\s*=\s*1\b|\bsleep\s*\(',
+    r'\bunion\s+select\b|\bor\s+1\s*=\s*1\b|\band\s+1\s*=\s*1\b|\bsleep\s*\(',
+    r"'\s*or\s*'1'\s*=\s*'1|;--|\bwaitfor\s+delay\b|\bbenchmark\s*\(",
+    r'\bxp_cmdshell\b|\bpg_sleep\s*\(|information_schema|\bextractvalue\s*\(|\bupdatexml\s*\(',
     r'<script\b|javascript:|onerror\s*=',
     r'/etc/passwd|/etc/shadow|/proc/self',
     r'\bphp://|\bdata:.*base64',
+    r';\s*(cat|rm|wget|curl|nc|bash|sh)\b|\$\(.*\)|`[^`]*`',
+    r'%0d%0a|\r\n',
 ]
 
 DEFAULT_BLOCK_USER_AGENTS = [

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/easyapi/settings_helper.py

@@ -1,14 +1,20 @@
-"""Read easyapi configuration from the project's ``MCP`` dict.
+"""Read easyapi configuration from the project's ``EASYAPI`` dict.
 
-A single dict named ``MCP`` in ``settings.py`` collects every
+A single dict named ``EASYAPI`` in ``settings.py`` collects every
 easyapi-owned setting (DRF/Celery-style namespace)::
 
-    MCP = {
+    EASYAPI = {
         'CACHE_TTL': 300,
         'ENFORCE_TOKEN': True,
         'RATE_LIMITS': {...},
     }
 
+``MCP`` is kept as a legacy alias for projects that haven't migrated
+yet — ``get_setting`` reads ``EASYAPI`` first and falls back to
+``MCP`` when the project only defines the old name. Both point at the
+same project; ``EASYAPI`` reflects that the framework serves REST
+first, MCP is one surface among several.
+
 Inside the bag the historical ``MCP_`` prefix is redundant:
 ``MCP_API_KEY_RESOLVER`` and ``API_KEY_RESOLVER`` resolve to the
 same setting.
@@ -16,17 +22,20 @@ same setting.
 
 
 def get_setting(name, default=None):
-    """Look up a setting by name in ``settings.MCP``.
+    """Look up a setting by name in ``settings.EASYAPI`` (or ``settings.MCP``
+    as a legacy alias — see module docstring).
 
     Returns ``default`` (which itself defaults to ``None``) when the
-    project hasn't defined the bag or the key is missing.
+    project hasn't defined either bag or the key is missing.
     """
     try:
         from settings import settings as _project_settings
     except ImportError:
         return default
 
-    bag = getattr(_project_settings, 'MCP', None)
+    bag = getattr(_project_settings, 'EASYAPI', None)
+    if not isinstance(bag, dict):
+        bag = getattr(_project_settings, 'MCP', None)
     if not isinstance(bag, dict):
         return default
 
@@ -115,6 +124,29 @@ def get_metrics_models():
     return get_setting('METRICS_MODELS', default=None)
 
 
+def get_metrics_fields():
+    """Per-model allowlist of field references (``"applabel_ClassName": [...]``)
+    the metrics endpoint may filter, group, order or aggregate by. Each entry
+    is a full ``__``-joined path (e.g. ``"agency__country__name"``), not just
+    the root segment — stricter than ``filters.validate_conditions``, which
+    only checks the root.
+
+    ``calc``/``group_by``/``order``/``additional_fields``/``conditions``
+    references must match a listed path exactly. ``filter_by.fields`` (and
+    ``or_conditions``) reach ``Q(**kwargs)`` directly and may carry a
+    trailing Django lookup not present in the list — a reference like
+    ``"owner__name__icontains"`` matches a listed ``"owner__name"`` by
+    stripping one recognized lookup segment before comparing.
+
+    ``None`` (default) disables the check entirely. A model label absent from
+    the dict is also unrestricted — set ``METRICS_MODELS`` alongside this to
+    close that gap for every model not explicitly listed here.
+
+    Orthogonal to ``METRICS_MODELS`` (bounds *which models*) and
+    ``base_queryset`` (bounds *which rows*): this bounds *which fields*."""
+    return get_setting('METRICS_FIELDS', default=None)
+
+
 def get_credential_paths():
     """Path-segment list that triggers the credential-path rate-limit
     auto-defense. Anything matching one of these segments — at the
@@ -129,13 +161,13 @@ def get_credential_paths():
       * ``/forgotten``            → NOT matched (different segment)
 
     Configure with leading slash for readability — it's stripped at
-    match time. Set to ``[]`` in ``MCP`` to disable.
+    match time. Set to ``[]`` in ``EASYAPI`` to disable.
 
-    **Override semantics:** ``MCP['CREDENTIAL_PATHS']`` *replaces* the
+    **Override semantics:** ``EASYAPI['CREDENTIAL_PATHS']`` *replaces* the
     framework default — does not merge. To add project-specific paths
     while keeping the defaults, copy the default list and extend::
 
-        MCP = {
+        EASYAPI = {
             'CREDENTIAL_PATHS': [
                 '/forgot', '/change_password', '/signup',
                 '/reset', '/recover', '/register',  # default

easyapi_django-1.3.2/easyapi/util.py

@@ -0,0 +1,105 @@
+import re
+
+SESSION_KEY_PATTERN = re.compile(r'^[a-zA-Z0-9_\-:]{5,100}$')
+
+
+def validate_session_key(session_key):
+    if not session_key or not SESSION_KEY_PATTERN.match(session_key):
+        return None
+    return session_key
+
+
+def make_list(data):
+    if not data:
+        data = []
+    elif not isinstance(data, list):
+        data = [data]
+
+    return data
+
+
+def make_unique_list(data):
+    return list(set(make_list(data)))
+
+
+def normalize_field(name):
+    # Used by Filter.distinct to render unique column values as filter
+    # options in the UI. Falsy non-int values collapse to 'Blank' so the
+    # user sees a single "empty" option for fields where null=True,
+    # blank=True both occur (e.g. segment filters).
+    #
+    # `bool` is a subclass of `int` in Python, so `isinstance(False, int)`
+    # would be True. We use `type(name) is int` instead to keep False in
+    # the 'Blank' bucket alongside '' and [].
+    #
+    # Behaviour table:
+    #
+    # | Input  | Output    | Notes                                   |
+    # |--------|-----------|-----------------------------------------|
+    # | None   | 'Null'    |                                         |
+    # | 0      | 0         | int passes through                      |
+    # | 0.0    | 'Blank'   | float, falsy, not int                   |
+    # | ''     | 'Blank'   |                                         |
+    # | 'x'    | 'x'       |                                         |
+    # | []     | 'Blank'   | empty collection, falsy                 |
+    # | True   | True      | int(True) == 1, truthy                  |
+    # | False  | 'Blank'   | bool not in int bucket here, falsy      |
+    #
+    # If the segment UI ever needs False to be a real value (not "empty"),
+    # swap `type(name) is not int` for `not isinstance(name, int)`.
+    if name is None:
+        return 'Null'
+    if type(name) is not int and not name:
+        return 'Blank'
+    return name
+
+
+def flatten_include_fields(model, bag):
+    """Flatten a project's ``INCLUDE_FIELDS[label]`` bag (as used by the
+    hand-maintained ``modules/segment/constants.py`` convention) into a flat
+    list of full ``__``-joined field paths, suitable for
+    ``EASYAPI['METRICS_FIELDS'][label]``.
+
+    ``model`` is the Django model class the label refers to. ``bag`` is a
+    dict shaped like::
+
+        {
+            'bi_fields': ['id', 'active', ...],
+            'related_fields': {
+                1: {'agency': ['name', 'country', ...]},
+                2: {'country': ['name', 'code', ...]},
+            },
+        }
+
+    ``bi_fields`` are copied verbatim (top-level columns on ``model``
+    itself). ``related_fields`` is walked level by level, using the model's
+    own ``_meta`` to resolve each relation's ``related_model`` and recurse —
+    mirroring the traversal ``modules/segment/util.py``'s ``get_related``
+    already performs to build the frontend's field picker, so the allowlist
+    matches exactly what the frontend is told exists. ``related_models`` is
+    not consulted: it's redundant with (and, in practice, sometimes
+    inconsistent with) the ``related_fields`` keys, which are the actual
+    gate ``get_related`` walks by.
+
+    Only fields explicitly enumerated in ``bi_fields``/``related_fields``
+    are returned — a relation absent from ``related_fields`` is never
+    recursed into, so its own columns never appear in the output.
+    """
+    paths = list(bag.get('bi_fields') or [])
+
+    def walk(current_model, level, prefix):
+        level_map = (bag.get('related_fields') or {}).get(level) or {}
+        for relation_name, leaf_fields in level_map.items():
+            try:
+                field = current_model._meta.get_field(relation_name)
+            except Exception:
+                continue
+            full_prefix = f'{prefix}__{relation_name}' if prefix else relation_name
+            for leaf in leaf_fields:
+                paths.append(f'{full_prefix}__{leaf}')
+            related_model = getattr(field, 'related_model', None)
+            if related_model:
+                walk(related_model, level + 1, full_prefix)
+
+    walk(model, 1, '')
+    return paths

{easyapi_django-1.3.1 → easyapi_django-1.3.2/easyapi_django.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easyapi-django
-Version: 1.3.1
+Version: 1.3.2
 Summary: Zero-effort MCP server (and REST API) generator from Django models.
 Author-email: Stamatios Stamou Jr <bushier.outsets.0c@icloud.com>
 License-Expression: MIT
@@ -174,7 +174,7 @@ REST is mostly a solved problem now. The new pain is MCP — most teams are rebu
 - Multi-tenant DB routing. One call switches the connection for the request.
 - Sliding session TTLs via Redis `GETEX`. Configure with `SESSION_TTL` (default 1800s) and `API_SESSION_TTL` (default 300s).
 - Sensitive-field scrubbing (`password`, `api_key`, `token` baseline plus your additions) — applied on both REST and MCP responses.
-- Global read-only switch (`MCP = {'READ_ONLY': True}`) rejects every non-`GET` request with `405`.
+- Global read-only switch (`EASYAPI = {'READ_ONLY': True}`) rejects every non-`GET` request with `405`.
 - Async end-to-end. Async ORM, async Redis, async dispatch.
 
 Full docs and reference: https://github.com/ssjunior/easyapi-django
@@ -233,11 +233,12 @@ Defaults are demo-friendly. Production deployments should:
 - **Per-resource ownership.** Set `owner_field = 'owner_id'` on resources where rows belong to a single user — restricts every CRUD operation to the row's owner. `POST` always forces `owner_id` to the caller (override with `allow_owner_override = True` for admin paths).
 - **Authenticated cache.** If you turn on `cache = True` for an authenticated resource, set `session_cache = True` or `cache_scope_fields = (...)` — otherwise responses can leak across users. The framework warns at runtime when it detects this combination.
 - **Tune session TTLs.** `SESSION_TTL` (cookies, default 1800s) and `API_SESSION_TTL` (api-key cache, default 300s) both slide on use. Pick numbers that match your security/UX trade-off.
-- **Never ship `DEBUG = True`.** Under `DEBUG`, edge security (scanner blocking, 4xx flood detection), rate limiting, credential-path defense and abuse blocking are all bypassed for dev ergonomics. The framework logs a loud startup warning when the bypass is active. To decouple from `DEBUG` — e.g. a staging box mirroring production — set `MCP = {'SECURITY_BYPASS': False}` to force protections on (or `True` to bypass without `DEBUG`).
+- **Never ship `DEBUG = True`.** Under `DEBUG`, edge security (scanner blocking, 4xx flood detection), rate limiting, credential-path defense and abuse blocking are all bypassed for dev ergonomics. The framework logs a loud startup warning when the bypass is active. To decouple from `DEBUG` — e.g. a staging box mirroring production — set `EASYAPI = {'SECURITY_BYPASS': False}` to force protections on (or `True` to bypass without `DEBUG`).
 - **Trust your proxies explicitly.** IP-based rate limits and abuse blocking key on the client IP. `X-Forwarded-For` / `X-Real-IP` are only honored when `REMOTE_ADDR` is in `TRUSTED_PROXIES = ['10.0.0.0/8', ...]`; otherwise `REMOTE_ADDR` wins. Leave it unset behind a proxy and every request looks like it comes from the proxy.
-- **Bound the metrics surface.** The `/metrics` endpoint queries any model in the registry by default. Set `METRICS_MODELS = ['app_Model', ...]` to allowlist which models are queryable. References to credential-named columns (in filters, groups, order or calc) are always rejected — the per-resource escape hatch does not reach `/metrics`.
+- **`/metrics` is opt-in.** `get_routes` doesn't mount it unless you pass `metrics_view=Metrics` (the generic, unscoped resource — `from easyapi import Metrics`) or a custom row-scoped subclass. Once mounted, bound which models it can query: set `METRICS_MODELS = ['app_Model', ...]` to allowlist them. References to credential-named columns (in filters, groups, order or calc) are always rejected regardless — the per-resource escape hatch does not reach `/metrics`.
+- **Bound the metrics fields, per model.** `METRICS_MODELS` only gates *which models* — every non-credential field on an allowed model is still fair game for `/metrics` (filter, group, order, calc), including arbitrary FK traversal. Set `METRICS_FIELDS = {'app_Model': ['status', 'owner__name', ...]}` to also allowlist *which field paths*, per model. Unlike REST's `filter_fields` (root-segment match), this checks the **full** `__`-joined path — `'owner'` in the list does not imply `'owner__anything'` is allowed. `filter_by` references tolerate one trailing Django lookup (`owner__name__icontains` matches an allowed `owner__name`) since those reach `Q(**kwargs)` directly; `calc`/`group_by`/`order`/`additional_fields`/`conditions` don't take lookups and are matched literally. A model absent from the dict, or the setting left unset, stays unrestricted — opt-in, same as `METRICS_MODELS`. If you already maintain a `bi_fields`/`related_fields` map for a frontend field picker, `easyapi.util.flatten_include_fields(model, bag)` turns that same data into the flat path list this setting expects, so there's one source of truth instead of two.
 - **Keep the escape hatch narrow.** Columns whose names look like credentials (`password`, `api_key`, `token`, `otp`, `secret`, …) are masked as `'*********'` on every response, on top of whatever `sensitive_fields` lists. When the heuristic catches a false positive, opt it out per surface: `edit_allow_sensitive_fields = ['token_count']` returns it verbatim on `GET /resource/<id>/` while LIST still masks it. `list_allow_sensitive_fields` does the same for LIST, where every row carries the value — reach for the detail-only form first.
-- **OAuth clients are public by default.** MCP clients (Claude.ai, ChatGPT, ...) authenticate with PKCE — list them under `MCP['OAUTH_CLIENTS']` with no `client_secret`. A client becomes confidential only with an explicit secret; `/register` never hands out a confidential secret (provision those out of band).
+- **OAuth clients are public by default.** MCP clients (Claude.ai, ChatGPT, ...) authenticate with PKCE — list them under `EASYAPI['OAUTH_CLIENTS']` with no `client_secret`. A client becomes confidential only with an explicit secret; `/register` never hands out a confidential secret (provision those out of band).
 
 ---
 

{easyapi_django-1.3.1 → easyapi_django-1.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "easyapi-django"
-version = "1.3.1"
+version = "1.3.2"
 authors = [
   { name="Stamatios Stamou Jr", email="bushier.outsets.0c@icloud.com" },
 ]

easyapi_django-1.3.1/easyapi/util.py

@@ -1,54 +0,0 @@
-import re
-
-SESSION_KEY_PATTERN = re.compile(r'^[a-zA-Z0-9_\-:]{5,100}$')
-
-
-def validate_session_key(session_key):
-    if not session_key or not SESSION_KEY_PATTERN.match(session_key):
-        return None
-    return session_key
-
-
-def make_list(data):
-    if not data:
-        data = []
-    elif not isinstance(data, list):
-        data = [data]
-
-    return data
-
-
-def make_unique_list(data):
-    return list(set(make_list(data)))
-
-
-def normalize_field(name):
-    # Used by Filter.distinct to render unique column values as filter
-    # options in the UI. Falsy non-int values collapse to 'Blank' so the
-    # user sees a single "empty" option for fields where null=True,
-    # blank=True both occur (e.g. segment filters).
-    #
-    # `bool` is a subclass of `int` in Python, so `isinstance(False, int)`
-    # would be True. We use `type(name) is int` instead to keep False in
-    # the 'Blank' bucket alongside '' and [].
-    #
-    # Behaviour table:
-    #
-    # | Input  | Output    | Notes                                   |
-    # |--------|-----------|-----------------------------------------|
-    # | None   | 'Null'    |                                         |
-    # | 0      | 0         | int passes through                      |
-    # | 0.0    | 'Blank'   | float, falsy, not int                   |
-    # | ''     | 'Blank'   |                                         |
-    # | 'x'    | 'x'       |                                         |
-    # | []     | 'Blank'   | empty collection, falsy                 |
-    # | True   | True      | int(True) == 1, truthy                  |
-    # | False  | 'Blank'   | bool not in int bucket here, falsy      |
-    #
-    # If the segment UI ever needs False to be a real value (not "empty"),
-    # swap `type(name) is not int` for `not isinstance(name, int)`.
-    if name is None:
-        return 'Null'
-    if type(name) is not int and not name:
-        return 'Blank'
-    return name