auth 2.0.0__tar.gz → 2.3.1__tar.gz

auth-2.3.1/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: auth
+Version: 2.3.1
+Summary: Authorization for humans
+Author-email: Farshid Ashouri <farsheed.ashouri@gmail.com>
+License-Expression: MIT
+Keywords: authorization,role,auth,groups,membership,ensure,ldap
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Natural Language :: English
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask<4,>=2.0.0
+Requires-Dist: flask-cors<7,>=3.0.0
+Requires-Dist: sqlalchemy<3,>=2.0.0
+Requires-Dist: waitress<4,>=2.0.0
+Requires-Dist: cryptography<48,>=3.0.0
+Requires-Dist: APScheduler<4,>=3.0.0
+Requires-Dist: psycopg[binary]<4,>=3.0.0
+Requires-Dist: pydantic<3,>=2.0.0
+Requires-Dist: pydantic-settings<3,>=2.0.0
+Requires-Dist: requests<3,>=2.25.0
+Requires-Dist: bleach<7,>=5.0.0
+Requires-Dist: python-json-logger<4,>=3.1.0
+Provides-Extra: ratelimit
+Requires-Dist: flask-limiter>=3.0.0; extra == "ratelimit"
+Provides-Extra: migrations
+Requires-Dist: alembic>=1.13.0; extra == "migrations"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: alembic>=1.13.0; extra == "dev"
+Requires-Dist: ruff>=0.0.260; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: types-waitress; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# auth — RBAC authorization service
+
+[![CI](https://github.com/ourway/auth/actions/workflows/ci.yml/badge.svg)](https://github.com/ourway/auth/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Role-based access control over HTTP. `auth` answers one question — **may user X
+do Y** — so your services don't reinvent roles and permissions.
+
+It is **authorization, not authentication**: it does not log anyone in, store
+passwords, or issue tokens. It trusts that the caller already knows *who* the
+user is, and decides *what they may do*. Model:
+`user → (member of) → role → (holds) → permission`.
+
+## Quickstart
+
+Your **client key is any UUID4** — it is also your private, isolated namespace.
+Generate one, keep it secret, and reuse it for every call. A role must exist
+before you add members or permissions to it.
+
+```bash
+KEY=$(python3 -c "import uuid; print(uuid.uuid4())")
+BASE=https://auth.rodmena.app
+
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/role/engineers
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/permission/engineers/deploy
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/membership/alice/engineers
+curl        -H "Authorization: Bearer $KEY" $BASE/api/has_permission/alice/deploy
+# -> {"success": true, "data": {"has_permission": true}, ...}
+```
+
+With the Python client (`pip install auth`):
+
+```python
+from auth import Client
+
+with Client(api_key=KEY, service_url="https://auth.rodmena.app") as c:
+    c.create_role("engineers")
+    c.add_permission("engineers", "deploy")
+    c.add_membership("alice", "engineers")
+    c.user_has_permission("alice", "deploy")   # -> {... "has_permission": true}
+```
+
+## Things to know before you write code
+
+- **Writes can return HTTP 200 with `{"result": false}`** (e.g. adding to a
+  missing role). Check the `result`/`data` field, not just the status code.
+- **Two response shapes** — bare `{"result": ...}` and wrapped
+  `{"success", "data", ...}`. The API reference says which per endpoint.
+- **Errors below 2xx are HTML**, not JSON. Branch on the status code first.
+- **Reuse one key.** A new key is a new empty namespace, not an error. Keep the
+  key out of source control, logs, and URLs — it is the only thing protecting
+  your data. Rotate it with `POST /api/keys/rotate` if it leaks.
+
+## Documentation
+
+| Doc | What's in it |
+|---|---|
+| **Live API reference** — [`/docs`](https://auth.rodmena.app/docs) · [`/llms.txt`](https://auth.rodmena.app/llms.txt) | Every endpoint and exact response shape, served by the app (agent-friendly). |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design, components, request lifecycle, data model, permission-check and key-rotation flows, diagrams. |
+| [SECURITY.md](SECURITY.md) | Security model (tenant isolation, encryption, audit, rotation), threat notes, reporting. |
+| [MIGRATIONS.md](MIGRATIONS.md) | Schema creation vs migrations, upgrade/rollback runbook. |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Local setup, tests (sqlite + postgres), lint/type-check, CI. |
+| [docs/](docs/) | Full Sphinx docs (concepts, configuration, encryption, deployment, REST & Python usage). |
+
+## When to use — and not
+
+**Use it** for RBAC: named roles, permissions, group membership, and boolean
+"can user X do Y" gates for a service, CLI, or workflow engine.
+
+**Not** for authentication (login/passwords/sessions/OAuth/JWT), fine-grained /
+attribute-based rules (owner-of-*this*-record, time-of-day, row-level tenancy —
+reach for an ABAC/policy engine), or air-gapped hot loops where a network hop per
+check is too costly (cache, or use the library in-process).
+
+## Development
+
+```bash
+python3.11 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,ratelimit,migrations]"
+make check   # ruff + mypy
+make test    # sqlite suite
+make test-postgres   # postgres integration (Docker), encryption on
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. Licensed under the
+[MIT License](LICENSE).

auth-2.3.1/README.md

@@ -0,0 +1,87 @@
+# auth — RBAC authorization service
+
+[![CI](https://github.com/ourway/auth/actions/workflows/ci.yml/badge.svg)](https://github.com/ourway/auth/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Role-based access control over HTTP. `auth` answers one question — **may user X
+do Y** — so your services don't reinvent roles and permissions.
+
+It is **authorization, not authentication**: it does not log anyone in, store
+passwords, or issue tokens. It trusts that the caller already knows *who* the
+user is, and decides *what they may do*. Model:
+`user → (member of) → role → (holds) → permission`.
+
+## Quickstart
+
+Your **client key is any UUID4** — it is also your private, isolated namespace.
+Generate one, keep it secret, and reuse it for every call. A role must exist
+before you add members or permissions to it.
+
+```bash
+KEY=$(python3 -c "import uuid; print(uuid.uuid4())")
+BASE=https://auth.rodmena.app
+
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/role/engineers
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/permission/engineers/deploy
+curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/membership/alice/engineers
+curl        -H "Authorization: Bearer $KEY" $BASE/api/has_permission/alice/deploy
+# -> {"success": true, "data": {"has_permission": true}, ...}
+```
+
+With the Python client (`pip install auth`):
+
+```python
+from auth import Client
+
+with Client(api_key=KEY, service_url="https://auth.rodmena.app") as c:
+    c.create_role("engineers")
+    c.add_permission("engineers", "deploy")
+    c.add_membership("alice", "engineers")
+    c.user_has_permission("alice", "deploy")   # -> {... "has_permission": true}
+```
+
+## Things to know before you write code
+
+- **Writes can return HTTP 200 with `{"result": false}`** (e.g. adding to a
+  missing role). Check the `result`/`data` field, not just the status code.
+- **Two response shapes** — bare `{"result": ...}` and wrapped
+  `{"success", "data", ...}`. The API reference says which per endpoint.
+- **Errors below 2xx are HTML**, not JSON. Branch on the status code first.
+- **Reuse one key.** A new key is a new empty namespace, not an error. Keep the
+  key out of source control, logs, and URLs — it is the only thing protecting
+  your data. Rotate it with `POST /api/keys/rotate` if it leaks.
+
+## Documentation
+
+| Doc | What's in it |
+|---|---|
+| **Live API reference** — [`/docs`](https://auth.rodmena.app/docs) · [`/llms.txt`](https://auth.rodmena.app/llms.txt) | Every endpoint and exact response shape, served by the app (agent-friendly). |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design, components, request lifecycle, data model, permission-check and key-rotation flows, diagrams. |
+| [SECURITY.md](SECURITY.md) | Security model (tenant isolation, encryption, audit, rotation), threat notes, reporting. |
+| [MIGRATIONS.md](MIGRATIONS.md) | Schema creation vs migrations, upgrade/rollback runbook. |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Local setup, tests (sqlite + postgres), lint/type-check, CI. |
+| [docs/](docs/) | Full Sphinx docs (concepts, configuration, encryption, deployment, REST & Python usage). |
+
+## When to use — and not
+
+**Use it** for RBAC: named roles, permissions, group membership, and boolean
+"can user X do Y" gates for a service, CLI, or workflow engine.
+
+**Not** for authentication (login/passwords/sessions/OAuth/JWT), fine-grained /
+attribute-based rules (owner-of-*this*-record, time-of-day, row-level tenancy —
+reach for an ABAC/policy engine), or air-gapped hot loops where a network hop per
+check is too costly (cache, or use the library in-process).
+
+## Development
+
+```bash
+python3.11 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,ratelimit,migrations]"
+make check   # ruff + mypy
+make test    # sqlite suite
+make test-postgres   # postgres integration (Docker), encryption on
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. Licensed under the
+[MIT License](LICENSE).

{auth-2.0.0 → auth-2.3.1}/auth/audit.py

@@ -37,6 +37,7 @@ class AuditAction(Enum):
     LIST_PERMISSIONS = "LIST_PERMISSIONS"
     LIST_MEMBERSHIPS = "LIST_MEMBERSHIPS"
     USER_PERMISSIONS = "USER_PERMISSIONS"
+    ROTATE_KEY = "ROTATE_KEY"
 
 
 class AuditLog(Base):
@@ -111,7 +112,65 @@ def client_fingerprint(token: Optional[str]) -> str:
     return "fpr_" + digest[:32]
 
 
-def log_audit_event(
+def _build_audit_entry(
+    client_id: str,
+    user: Optional[str],
+    action: AuditAction,
+    resource: Optional[str],
+    details: Optional[Dict[str, Any]],
+    ip_address: Optional[str],
+    user_agent: Optional[str],
+    success: bool,
+) -> "AuditLog":
+    # The managed user is a human identifier (often an email) — store a
+    # non-reversible fingerprint, never plaintext, matching how the client key is
+    # handled. Auditors correlate by fingerprint and can confirm a known user by
+    # computing its fingerprint. Role/permission/workflow names (the `resource`)
+    # are application identifiers, not PII, and stay readable — except the caller
+    # is responsible for fingerprinting any user embedded in `resource`.
+    user_fp = client_fingerprint(user) if user else None
+    return AuditLog(
+        client_id=_fit(client_id, "client_id"),
+        user=_fit(user_fp, "user"),
+        action=_fit(action.value, "action"),
+        resource=_fit(resource, "resource"),
+        details=json.dumps(details) if details else None,
+        ip_address=_fit(ip_address, "ip_address"),
+        user_agent=_fit(user_agent, "user_agent"),
+        success=1 if success else 0,
+    )
+
+
+def _emit_structured_log(
+    client_id: str,
+    user: Optional[str],
+    action: AuditAction,
+    resource: Optional[str],
+    details: Optional[Dict[str, Any]],
+    ip_address: Optional[str],
+    success: bool,
+) -> None:
+    # The DB row is the system of record. The log STREAM (journald / SIEM /
+    # shipping) is more widely exposed, so it carries no PII: no raw user and no
+    # resource string (which may embed a user). Only the non-reversible client
+    # fingerprint, the action, and the outcome.
+    log_msg: Dict[str, Any] = {
+        "type": "audit",
+        "client_id": client_id,
+        "action": action.value,
+        "success": success,
+        "timestamp": _utcnow().isoformat(),
+    }
+    if details:
+        log_msg["details"] = details
+    if ip_address:
+        log_msg["ip"] = ip_address
+    audit_logger.info(json.dumps(log_msg))
+
+
+def record_audit(
+    session,
+    *,
     client_id: str,
     user: Optional[str],
     action: AuditAction,
@@ -121,45 +180,52 @@ def log_audit_event(
     user_agent: Optional[str] = None,
     success: bool = True,
 ) -> None:
+    """Add an audit row to an EXISTING session so it commits atomically with the
+    caller's transaction (the mutation and its audit land together, or not at
+    all). The caller is responsible for committing.
+
+    This does NOT swallow errors: a failure to stage the audit row must fail the
+    surrounding request (fail-closed), never leave a committed mutation
+    unaudited.
     """
-    Log an audit event to the database and to structured logs
+    session.add(
+        _build_audit_entry(
+            client_id, user, action, resource, details, ip_address, user_agent, success
+        )
+    )
+    _emit_structured_log(client_id, user, action, resource, details, ip_address, success)
+
+
+def log_audit_event(
+    client_id: str,
+    user: Optional[str],
+    action: AuditAction,
+    resource: Optional[str] = None,
+    details: Optional[Dict[str, Any]] = None,
+    ip_address: Optional[str] = None,
+    user_agent: Optional[str] = None,
+    success: bool = True,
+) -> None:
+    """Write an audit event on its OWN committed session.
+
+    For contexts with no request transaction to join: in-process/library
+    callers, and the *failure* path of the request decorator (where the request
+    transaction is being rolled back and must not carry the audit row). This one
+    is best-effort — a failure is logged, not raised, so it cannot mask the
+    original error it is recording.
     """
     session = SessionLocal()
     try:
-        # Create audit log entry
-        audit_entry = AuditLog(
-            client_id=_fit(client_id, "client_id"),
-            user=_fit(user, "user"),
-            action=_fit(action.value, "action"),
-            resource=_fit(resource, "resource"),
-            details=json.dumps(details) if details else None,
-            ip_address=_fit(ip_address, "ip_address"),
-            user_agent=_fit(user_agent, "user_agent"),
-            success=1 if success else 0,
+        session.add(
+            _build_audit_entry(
+                client_id, user, action, resource, details, ip_address, user_agent, success
+            )
         )
-
-        session.add(audit_entry)
         session.commit()
-
-        # Also log to structured logger
-        log_msg: Dict[str, Any] = {
-            "type": "audit",
-            "client_id": client_id,
-            "user": user,
-            "action": action.value,
-            "resource": resource,
-            "success": success,
-            "timestamp": _utcnow().isoformat(),
-        }
-        if details:
-            log_msg["details"] = details
-        if ip_address:
-            log_msg["ip"] = ip_address
-
-        audit_logger.info(json.dumps(log_msg))
+        _emit_structured_log(
+            client_id, user, action, resource, details, ip_address, success
+        )
     except Exception:
-        # If audit logging fails, we don't want to break the main operation
-        # But log the failure for monitoring
         audit_logger.error(
             f"Failed to log audit event: client_id={client_id}, action={action.value}"
         )

{auth-2.0.0 → auth-2.3.1}/auth/client.py

@@ -131,6 +131,7 @@ class EnhancedAuthClient:
             "role": "/api/role/{role}",
             "workflow_users": "/api/workflow/users/{workflow_name}",
             "workflow_permission": "/api/workflow/user/{user}/can_run/{workflow_name}",
+            "rotate_key": "/api/keys/rotate",
         }
 
     def _make_request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
@@ -337,6 +338,28 @@ class EnhancedAuthClient:
         except Exception as e:
             return {"error": str(e), "success": False, "data": {"role": role}}
 
+    def rotate_key(self) -> Dict[str, Any]:
+        """Rotate this client's API key (atomic cutover).
+
+        The server mints a fresh key, moves the whole namespace onto it, and
+        returns it in ``data.new_key``. On success this client is updated in
+        place — ``self.api_key`` and the session ``Authorization`` header switch
+        to the new key — so subsequent calls on this instance keep working. The
+        returned key is the ONLY copy: persist ``data.new_key`` (e.g. to your
+        secret store) or you lose access to the namespace.
+        """
+        endpoint = self.endpoints["rotate_key"]
+        try:
+            response = self._make_request("POST", endpoint)
+        except Exception as e:
+            return {"error": str(e), "success": False, "data": {}}
+
+        new_key = (response or {}).get("data", {}).get("new_key")
+        if new_key:
+            self.api_key = new_key
+            self.session.headers["Authorization"] = f"Bearer {new_key}"
+        return response
+
     # Workflow-related methods
     def get_users_for_workflow(self, workflow_name: str) -> Dict[str, Any]:
         """Get all users who can run a specific workflow"""

{auth-2.0.0 → auth-2.3.1}/auth/config.py

@@ -18,6 +18,23 @@ class DatabaseType(Enum):
     POSTGRESQL = "postgresql"
 
 
+# Values that must never protect a production secret. The audit pepper keys the
+# HMAC that fingerprints client keys in the audit trail; if it is one of these
+# (or empty), the fingerprints are computable by anyone and the audit log's
+# offline-guess resistance is gone. Boot fails closed rather than run weak.
+_KNOWN_WEAK_SECRETS = frozenset(
+    {
+        "",
+        "default_secret_key_for_development",
+        "your_secure_jwt_secret_key_here",
+        "changeme",
+        "change-me",
+        "secret",
+        "password",
+    }
+)
+
+
 class Settings(BaseSettings):
     """Configuration class for the authorization system"""
 
@@ -100,12 +117,63 @@ class Settings(BaseSettings):
     @field_validator("jwt_secret_key")
     @classmethod
     def validate_secret_key(cls, v: str) -> str:
-        if v == "default_secret_key_for_development":
+        if v in _KNOWN_WEAK_SECRETS:
             import logging
             logger = logging.getLogger(__name__)
-            logger.warning("Using default JWT secret key. This should be changed for production!")
+            logger.warning(
+                "AUTH_JWT_SECRET_KEY is a weak/placeholder value. "
+                "Set a strong secret for production."
+            )
         return v
 
+    @model_validator(mode="after")
+    def warn_on_weak_audit_pepper(self) -> "Settings":
+        """Warn (never raise) when the effective audit pepper is weak.
+
+        Constructing Settings must not fail: ``auth`` is also a client library,
+        and ``pip install auth; from auth import Client`` to talk to a remote
+        service needs no pepper at all. The hard, fail-closed check belongs to
+        the *server* boot path — see :func:`verify_audit_pepper`, called by
+        ``auth.main.create_app``.
+        """
+        if self.enable_audit_logging and not self.debug_mode and audit_pepper_is_weak(
+            self
+        ):
+            import logging
+
+            logging.getLogger(__name__).warning(
+                "AUTH_AUDIT_PEPPER is unset, a placeholder, or too short; audit "
+                "key fingerprints are not offline-guess resistant. Set a strong "
+                "value before serving traffic."
+            )
+        return self
+
+
+def audit_pepper_is_weak(settings: "Settings") -> bool:
+    """Whether the effective audit pepper is unset/placeholder/too short.
+
+    The pepper is ``audit_pepper`` if set, else ``jwt_secret_key`` — the same
+    fallback ``audit.client_fingerprint`` uses.
+    """
+    pepper = (settings.audit_pepper or settings.jwt_secret_key or "").strip()
+    return pepper in _KNOWN_WEAK_SECRETS or len(pepper) < 16
+
+
+def verify_audit_pepper(settings: "Settings") -> None:
+    """Fail closed on a weak audit pepper — called when the SERVER starts.
+
+    A placeholder pepper makes the audit trail's key fingerprints computable, so
+    a server that writes audit rows must not run with one. Importing the package
+    as a library is unaffected (see :meth:`Settings.warn_on_weak_audit_pepper`).
+    """
+    if settings.enable_audit_logging and not settings.debug_mode:
+        if audit_pepper_is_weak(settings):
+            raise ValueError(
+                "Refusing to start: the audit pepper is unset, a placeholder, "
+                "or too short. Set AUTH_AUDIT_PEPPER to a strong random value "
+                "(>= 16 chars), or set AUTH_DEBUG_MODE=true for local use."
+            )
+
 
 @lru_cache()
 def get_settings() -> Settings:

auth-2.3.1/auth/decorators.py

@@ -0,0 +1,123 @@
+from functools import wraps
+from typing import Any, Optional
+
+from flask import Response, g, request
+
+from auth.audit import (
+    AuditAction,
+    client_fingerprint,
+    log_audit_event,
+    record_audit,
+)
+from auth.config import get_settings
+
+
+def _status_code(response) -> int:
+    """Best-effort HTTP status of a Flask view return value."""
+    if isinstance(response, Response):
+        return response.status_code
+    if isinstance(response, tuple) and len(response) >= 2 and isinstance(
+        response[1], int
+    ):
+        return response[1]
+    return 200
+
+
+def _response_body(response) -> Any:
+    """Best-effort decoded JSON body of a Flask view return value."""
+    obj = response
+    if isinstance(response, tuple) and response:
+        obj = response[0]
+    if isinstance(obj, Response):
+        return obj.get_json(silent=True)
+    return None
+
+
+def _derive_success(response) -> bool:
+    """Whether the operation actually took effect — not merely whether HTTP was
+    2xx.
+
+    Write endpoints return HTTP 200 with ``{"result": false}`` (bare) or
+    ``{"data": {"result": false}}`` (wrapped) when the write did nothing (e.g. a
+    missing role). Recording those as ``success`` would let the audit trail claim
+    a grant happened when it did not, so pull the real boolean out. Read
+    endpoints (e.g. a permission check answering ``has_permission: false``) have
+    no ``result`` field and are treated as successful — the query succeeded.
+    """
+    status_code = _status_code(response)
+    if not (200 <= status_code < 400):
+        return False
+    body = _response_body(response)
+    if isinstance(body, dict):
+        result = body.get("result")
+        if isinstance(result, bool):
+            return result
+        data = body.get("data")
+        if isinstance(data, dict):
+            inner = data.get("result")
+            if isinstance(inner, bool):
+                return inner
+    return True
+
+
+def _request_db(args) -> Optional[Any]:
+    """The request session injected by ``with_db_session`` as the first arg."""
+    return args[0] if args else None
+
+
+def audit_log(action: AuditAction, resource_extractor=None):
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            if not get_settings().enable_audit_logging:
+                return func(*args, **kwargs)
+
+            # ``before_request`` has already authenticated every /api/* request
+            # and stored the validated client key on ``g``. We record only a
+            # non-reversible fingerprint of it — never the raw key, which is the
+            # caller's credential.
+            client_ref = client_fingerprint(getattr(g, "client_key", None))
+            user = kwargs.get("user")
+            resource = resource_extractor(kwargs) if resource_extractor else None
+            db = _request_db(args)
+
+            try:
+                response = func(*args, **kwargs)
+            except Exception as e:
+                # The request transaction is being rolled back, so the audit row
+                # must NOT ride on it — write it on its own session so the failed
+                # attempt is still recorded.
+                log_audit_event(
+                    client_id=client_ref,
+                    user=user,
+                    action=action,
+                    resource=resource,
+                    details={"error": str(e)},
+                    ip_address=request.remote_addr,
+                    user_agent=request.headers.get("User-Agent", ""),
+                    success=False,
+                )
+                raise
+
+            status_code = _status_code(response)
+            success = _derive_success(response)
+            # Stage the audit row on the SAME session as the mutation; the
+            # ``with_db_session`` wrapper commits both together. If this raises,
+            # the whole request fails closed rather than committing an unaudited
+            # mutation.
+            record_audit(
+                db,
+                client_id=client_ref,
+                user=user,
+                action=action,
+                resource=resource,
+                details={"status_code": status_code},
+                ip_address=request.remote_addr,
+                user_agent=request.headers.get("User-Agent", ""),
+                success=success,
+            )
+            return response
+
+        return wrapper
+
+    return decorator