Move audit logging demo out of test.py into example/audit_logging.py

The previous commit accidentally bundled the audit-logging configuration
walkthrough — and a local RBAC email change — into the test.py
playground script. test.py is meant to be a personal sandbox kept out
of releases. Pull the audit demo back into a dedicated example module
(example/audit_logging.py) so users still get a copy-pasteable
StreamHandler + formatter + redact-filter block, and restore test.py
to the version that was already tracked in the tree before d2ef0e7.

Author: hidekuma

example/audit_logging.py

@@ -0,0 +1,105 @@
+"""Stand-alone audit logging example for flask-s3-viewer.
+
+Copy the ``configure_audit_logger`` call into your own app's startup
+to start auditing. The block is intentionally self-contained — no
+other example file imports from it.
+
+The ``flask_s3_viewer.audit`` logger emits one record per S3 CRUD
+action (list / download / upload / delete / presign). Every record
+carries these LogRecord extras:
+
+    action / namespace / key / user / result / status_code /
+    client_ip / user_agent / request_id (+ error on failure)
+
+Multi-file requests emit one row per file. All rows from the same
+Flask request share one ``request_id`` (8 hex chars), so plaintext
+greps can group them, e.g. ``grep "req=a1b2c3d4" audit.log``.
+
+Drop this file's body into your app's startup (after ``logging.basicConfig``
+or whatever root logging your host already does) and adjust the
+handler / formatter to taste — ``FileHandler`` with rotation, a JSON
+formatter via ``python-json-logger``, a Loki/Fluent Bit sink, etc.
+"""
+
+from __future__ import annotations
+
+import logging
+
+
+class DemoUserRedactFilter(logging.Filter):
+    """Cheap email-tail redaction for the demo.
+
+    Production deployments should swap this out for the redaction
+    policy that matches their compliance requirements — see
+    ``docs/source/usage/configuration.rst`` for a ``RedactFilter`` /
+    ``KeyErrorRedactFilter`` reference set.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        user = getattr(record, "user", None)
+        if user and "@" in user:
+            local, domain = user.split("@", 1)
+            record.user = f"{local[:2]}***@{domain}"
+        return True
+
+
+def configure_audit_logger(
+    *,
+    level: int = logging.INFO,
+    propagate: bool = True,
+    redact_user_emails: bool = True,
+) -> logging.Logger:
+    """Attach a ``StreamHandler`` to ``flask_s3_viewer.audit`` and return it.
+
+    Parameters
+    ----------
+    level
+        Audit logger level. ``logging.INFO`` is the recommended default;
+        denied (401/403) records emit at ``WARNING`` and exceptions at
+        ``ERROR`` so they survive higher thresholds too.
+    propagate
+        When ``True`` (default) audit records also reach the host's root
+        logger. Set ``False`` if you want the audit stream completely
+        isolated from your application logs.
+    redact_user_emails
+        Install :class:`DemoUserRedactFilter` so emails appear as
+        ``jo***@example.com`` in the demo output. Turn off (or replace
+        with your own filter) for production.
+    """
+    audit_logger = logging.getLogger("flask_s3_viewer.audit")
+    audit_logger.setLevel(level)
+    audit_logger.propagate = propagate
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(
+        logging.Formatter(
+            "AUDIT %(asctime)s %(levelname)s "
+            "action=%(action)s namespace=%(namespace)s "
+            "key=%(key)s user=%(user)s result=%(result)s "
+            "status=%(status_code)s req=%(request_id)s "
+            "ip=%(client_ip)s",
+        ),
+    )
+    audit_logger.addHandler(handler)
+
+    if redact_user_emails:
+        audit_logger.addFilter(DemoUserRedactFilter())
+
+    return audit_logger
+
+
+if __name__ == "__main__":
+    # Quick smoke test — emits one anonymous record outside a Flask
+    # request context. Run with: python -m example.audit_logging
+    from flask_s3_viewer.audit import emit
+    from flask_s3_viewer.auth import ACTION_LIST
+
+    configure_audit_logger()
+    emit(
+        action=ACTION_LIST,
+        namespace="demo",
+        key="demo/key",
+        user="alice@example.com",
+        result="ok",
+        status_code=200,
+    )

test.py

@@ -8,55 +8,6 @@
 
 logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(asctime)s: %(message)s")
 
-# ---------------------------------------------------------------------------
-# Audit logger setup (flask_s3_viewer.audit)
-#
-# Independent of the host root logger above. The audit logger emits one
-# record per S3 CRUD action (list/download/upload/delete/presign) with
-# extra fields:
-#   action / namespace / key / user / result / status_code /
-#   client_ip / user_agent / request_id (+ error on failure)
-#
-# Multi-file uploads emit one row per file; every row in the same Flask
-# request shares one `request_id` (8 hex chars) so plain-text grep can
-# group them, e.g. `grep "req=a1b2c3d4" audit.log`.
-#
-# Copy this block into your own app to start auditing — adjust the
-# handler (StreamHandler / FileHandler / structured JSON via
-# python-json-logger) and the formatter to fit your log pipeline.
-# ---------------------------------------------------------------------------
-audit_logger = logging.getLogger("flask_s3_viewer.audit")
-audit_handler = logging.StreamHandler()
-audit_handler.setFormatter(logging.Formatter(
-    "AUDIT %(asctime)s %(levelname)s "
-    "action=%(action)s namespace=%(namespace)s "
-    "key=%(key)s user=%(user)s result=%(result)s "
-    "status=%(status_code)s req=%(request_id)s "
-    "ip=%(client_ip)s"
-))
-audit_logger.addHandler(audit_handler)
-audit_logger.setLevel(logging.INFO)
-# Set False if you do NOT want audit lines also reaching the root
-# handler installed by logging.basicConfig above. Left True here so
-# the demo shows both streams side by side.
-# audit_logger.propagate = False
-
-
-# Optional: demo-only PII-soft user field. Production policies should
-# replace this with the redaction filter that matches your compliance
-# requirements (see docs/source/usage/configuration.rst).
-class _DemoUserRedactFilter(logging.Filter):
-    def filter(self, record: logging.LogRecord) -> bool:
-        user = getattr(record, "user", None)
-        if user and "@" in user:
-            local, domain = user.split("@", 1)
-            record.user = f"{local[:2]}***@{domain}"
-        return True
-
-
-# Comment the next line out to see raw email addresses in the demo log.
-audit_logger.addFilter(_DemoUserRedactFilter())
-
 app = Flask(__name__)
 
 # For test, disable template caching
@@ -108,7 +59,7 @@ def filter(self, record: logging.LogRecord) -> bool:
 # ---------------------------------------------------------------------------
 RBAC_POLICY: dict[str, dict[str, dict[str, set[str]]]] = {
     # Replace these with your real Google account emails.
-    "joseph.jeong@kakaopiccoma.com": {
+    "test@test.com": {
         "flask-s3-viewer": {
             "list": {""},
             "upload": {"test/aaaa/"},