mcp-baf-audit 0.2.0__tar.gz

mcp_baf_audit-0.2.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Test / lint caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Runtime artifacts (audit journals)
+audit.log
+audit-*.log
+*.log
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db

mcp_baf_audit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andriy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_baf_audit-0.2.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: mcp-baf-audit
+Version: 0.2.0
+Summary: Shared JSONL audit log for BAF MCP services (mcp-baf, baf-write-mcp, hermes)
+Project-URL: Repository, https://github.com/andriy4k07/mcp-baf-audit
+Project-URL: Issues, https://github.com/andriy4k07/mcp-baf-audit/issues
+Author: andriy4k07
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 1c,audit,baf,jsonl,logging,mcp
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-baf-audit
+
+Єдиний JSONL-журнал аудиту для сервісів BAF. Формат запису — спільний
+контракт, щоб логи не розходилися між сервісами.
+
+Пакет **повністю незалежний**: без рантайм-залежностей, тільки стандартна
+бібліотека Python (≥3.11). Він нічого не імпортує зі споживачів — навпаки,
+споживачі залежать від нього.
+
+## Споживачі
+
+- [mcp-baf](https://github.com/andriy4k07/mcp-baf) — MCP-сервер читання 1С
+  (інтеграція запланована окремим PR).
+- [baf-write-mcp](https://github.com/andriy4k07/baf-write-mcp) — MCP-сервер
+  контрольованого створення номенклатури в 1С (вже переведений на цей пакет).
+- hermes — інтеграція запланована.
+
+## Схема запису (v2)
+
+Кожен рядок журналу — один JSON-об'єкт зі спільним конвертом:
+
+```json
+{
+  "schema_version": "2",
+  "ts": "2026-06-14T10:51:23.354+00:00",
+  "service": "baf-write-mcp",
+  "session": "d6dfd09f2d7d",
+  "seq": 1043,
+  "trace_id": "abc123…",
+  "event": "product.create",
+  "level": "info",
+  "tool": "create_product_catalog_item",
+  "request_id": "req-7",
+  "object": { "type": "product", "ref": "uuid…", "code": "000001", "name": "Болт" },
+  "actor": "write-svc",
+  "source_channel": "mcp",
+  "ok": true,
+  "duration_ms": 87,
+  "status": 200,
+  "payload": { },
+  "error": null
+}
+```
+
+`service` — ім'я сервіса (`mcp-baf` | `baf-write-mcp` | `hermes`);
+`session` — hex12, один на процес; `seq` — монотонний лічильник у сеансі;
+`trace_id` — наскрізний ідентифікатор операції між сервісами, **ніколи не
+null у нових записах** (вкладені події успадковують його через contextvar).
+
+Optional-поля конверта v2 (`request_id`, `object`, `actor`, `source_channel`,
+`ok`, `duration_ms`, `status`) nullable: їхня відсутність у рядку (зокрема в
+логах v1) не ламає читання. Редакція секретів застосовується і до `payload`,
+і до `object`.
+
+> Будь-яка зміна формату рядка → bump `SCHEMA_VERSION` у `writer.py`
+> і minor/major тега пакета. v2 додав optional-поля конверта; читач
+> розуміє і v1, і v2.
+
+## Канонічні імена подій
+
+`events.py` фіксує namespaced-таксономію (`tool.call`, `product.create`,
+`counterparty.propose`, `one_c.http`, `index.search`, …). Writer нормалізує
+ім'я кожного запису через `canonical()`, тож **нові логи завжди канонічні** —
+навіть якщо доменний код передає звичне плоске ім'я. Старі логи лишаються
+читабельними: той самий `canonical()` мапить плоскі імена v1 у канонічні.
+
+```python
+from mcp_baf_audit import canonical, events
+
+canonical("create")             # -> "product.create"
+canonical("tool_call")          # -> "tool.call"
+canonical("product.create")     # -> "product.create" (ідемпотентно)
+events.PRODUCT_CREATE           # "product.create"
+```
+
+## Використання
+
+```python
+from mcp_baf_audit import AuditWriter, traced, iter_events
+
+audit = AuditWriter(service="mcp-baf", path="/path/to/audit.log")
+audit.server_start(version="1.2.3")
+
+# Канонічний метод v2 (payload і object редагуються від секретів):
+audit.event("product.create", tool="create_product_catalog_item",
+            request_id="req-7", status=200, duration_ms=12, ok=True,
+            obj={"type": "product", "ref": "uuid…", "name": "Болт"},
+            payload={"name": "Болт"})
+
+# Обгортка інструмента: пише tool.call/tool.error, міряє duration,
+# гарантує не-null trace_id (явний -> contextvar -> новий) і фіксує його
+# в contextvar, щоб вкладені події успадкували.
+result_json = await traced(audit, "query", call, args={"limit": 10})
+```
+
+### Читання журналу
+
+`iter_events()` — єдина читацька функція. Вона обходить ротовані архіви в
+хронологічному порядку, мовчки пропускає биті рядки (повідомляє про кожен
+через `on_bad_line`) і нормалізує `event` через `canonical()`. На ній
+будуються зовнішні проєкція/дашборд — сама бібліотека ні БД, ні форматів
+представлення не знає.
+
+```python
+from mcp_baf_audit import iter_events
+
+bad: list[str] = []
+for ev in iter_events("/path/to/audit.log", on_bad_line=bad.append):
+    print(ev["seq"], ev["event"], ev.get("trace_id"))
+print("пропущено битих рядків:", len(bad))
+```
+
+### HTTP-події `one_c.http`
+
+`baf-write-mcp` передає аудит у HTTP-клієнт (`OneCClient(config, audit=audit)`),
+і кожен виклик 1С лишає рівно одну подію `one_c.http` (метод, ендпоінт,
+статус, `duration_ms`, `response_bytes`, `request_id`, `trace_id`). **Тіло
+запиту/відповіді не логується**; помилки пишуться з `level:"error"`, `ok:false`.
+
+### Секрети
+
+Редакція централізована у writer'і: ключі `password|token|authorization|secret`
+(регістронезалежно, рекурсивно) замінюються на `***` у кожному записі.
+Передавати «сирий» payload безпечно — секрети у лог не потрапляють.
+
+## Постачання / версіонування
+
+Тег `v0.2.0` (minor-bump: формат запису перейшов на schema v2). Споживачі
+пінять версію:
+
+```
+pip install "git+https://github.com/andriy4k07/mcp-baf-audit.git@v0.2.0"
+```
+
+У монорепо — path-залежність від сусіднього каталогу:
+
+```
+pip install -e ../mcp-baf-audit
+```

mcp_baf_audit-0.2.0/README.md

@@ -0,0 +1,139 @@
+# mcp-baf-audit
+
+Єдиний JSONL-журнал аудиту для сервісів BAF. Формат запису — спільний
+контракт, щоб логи не розходилися між сервісами.
+
+Пакет **повністю незалежний**: без рантайм-залежностей, тільки стандартна
+бібліотека Python (≥3.11). Він нічого не імпортує зі споживачів — навпаки,
+споживачі залежать від нього.
+
+## Споживачі
+
+- [mcp-baf](https://github.com/andriy4k07/mcp-baf) — MCP-сервер читання 1С
+  (інтеграція запланована окремим PR).
+- [baf-write-mcp](https://github.com/andriy4k07/baf-write-mcp) — MCP-сервер
+  контрольованого створення номенклатури в 1С (вже переведений на цей пакет).
+- hermes — інтеграція запланована.
+
+## Схема запису (v2)
+
+Кожен рядок журналу — один JSON-об'єкт зі спільним конвертом:
+
+```json
+{
+  "schema_version": "2",
+  "ts": "2026-06-14T10:51:23.354+00:00",
+  "service": "baf-write-mcp",
+  "session": "d6dfd09f2d7d",
+  "seq": 1043,
+  "trace_id": "abc123…",
+  "event": "product.create",
+  "level": "info",
+  "tool": "create_product_catalog_item",
+  "request_id": "req-7",
+  "object": { "type": "product", "ref": "uuid…", "code": "000001", "name": "Болт" },
+  "actor": "write-svc",
+  "source_channel": "mcp",
+  "ok": true,
+  "duration_ms": 87,
+  "status": 200,
+  "payload": { },
+  "error": null
+}
+```
+
+`service` — ім'я сервіса (`mcp-baf` | `baf-write-mcp` | `hermes`);
+`session` — hex12, один на процес; `seq` — монотонний лічильник у сеансі;
+`trace_id` — наскрізний ідентифікатор операції між сервісами, **ніколи не
+null у нових записах** (вкладені події успадковують його через contextvar).
+
+Optional-поля конверта v2 (`request_id`, `object`, `actor`, `source_channel`,
+`ok`, `duration_ms`, `status`) nullable: їхня відсутність у рядку (зокрема в
+логах v1) не ламає читання. Редакція секретів застосовується і до `payload`,
+і до `object`.
+
+> Будь-яка зміна формату рядка → bump `SCHEMA_VERSION` у `writer.py`
+> і minor/major тега пакета. v2 додав optional-поля конверта; читач
+> розуміє і v1, і v2.
+
+## Канонічні імена подій
+
+`events.py` фіксує namespaced-таксономію (`tool.call`, `product.create`,
+`counterparty.propose`, `one_c.http`, `index.search`, …). Writer нормалізує
+ім'я кожного запису через `canonical()`, тож **нові логи завжди канонічні** —
+навіть якщо доменний код передає звичне плоске ім'я. Старі логи лишаються
+читабельними: той самий `canonical()` мапить плоскі імена v1 у канонічні.
+
+```python
+from mcp_baf_audit import canonical, events
+
+canonical("create")             # -> "product.create"
+canonical("tool_call")          # -> "tool.call"
+canonical("product.create")     # -> "product.create" (ідемпотентно)
+events.PRODUCT_CREATE           # "product.create"
+```
+
+## Використання
+
+```python
+from mcp_baf_audit import AuditWriter, traced, iter_events
+
+audit = AuditWriter(service="mcp-baf", path="/path/to/audit.log")
+audit.server_start(version="1.2.3")
+
+# Канонічний метод v2 (payload і object редагуються від секретів):
+audit.event("product.create", tool="create_product_catalog_item",
+            request_id="req-7", status=200, duration_ms=12, ok=True,
+            obj={"type": "product", "ref": "uuid…", "name": "Болт"},
+            payload={"name": "Болт"})
+
+# Обгортка інструмента: пише tool.call/tool.error, міряє duration,
+# гарантує не-null trace_id (явний -> contextvar -> новий) і фіксує його
+# в contextvar, щоб вкладені події успадкували.
+result_json = await traced(audit, "query", call, args={"limit": 10})
+```
+
+### Читання журналу
+
+`iter_events()` — єдина читацька функція. Вона обходить ротовані архіви в
+хронологічному порядку, мовчки пропускає биті рядки (повідомляє про кожен
+через `on_bad_line`) і нормалізує `event` через `canonical()`. На ній
+будуються зовнішні проєкція/дашборд — сама бібліотека ні БД, ні форматів
+представлення не знає.
+
+```python
+from mcp_baf_audit import iter_events
+
+bad: list[str] = []
+for ev in iter_events("/path/to/audit.log", on_bad_line=bad.append):
+    print(ev["seq"], ev["event"], ev.get("trace_id"))
+print("пропущено битих рядків:", len(bad))
+```
+
+### HTTP-події `one_c.http`
+
+`baf-write-mcp` передає аудит у HTTP-клієнт (`OneCClient(config, audit=audit)`),
+і кожен виклик 1С лишає рівно одну подію `one_c.http` (метод, ендпоінт,
+статус, `duration_ms`, `response_bytes`, `request_id`, `trace_id`). **Тіло
+запиту/відповіді не логується**; помилки пишуться з `level:"error"`, `ok:false`.
+
+### Секрети
+
+Редакція централізована у writer'і: ключі `password|token|authorization|secret`
+(регістронезалежно, рекурсивно) замінюються на `***` у кожному записі.
+Передавати «сирий» payload безпечно — секрети у лог не потрапляють.
+
+## Постачання / версіонування
+
+Тег `v0.2.0` (minor-bump: формат запису перейшов на schema v2). Споживачі
+пінять версію:
+
+```
+pip install "git+https://github.com/andriy4k07/mcp-baf-audit.git@v0.2.0"
+```
+
+У монорепо — path-залежність від сусіднього каталогу:
+
+```
+pip install -e ../mcp-baf-audit
+```

mcp_baf_audit-0.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "mcp-baf-audit"
+version = "0.2.0"
+description = "Shared JSONL audit log for BAF MCP services (mcp-baf, baf-write-mcp, hermes)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "andriy4k07" }]
+requires-python = ">=3.11"
+keywords = ["mcp", "audit", "jsonl", "logging", "1c", "baf"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: System :: Logging",
+]
+# Без рантайм-зависимостей: только стандартная библиотека.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+Repository = "https://github.com/andriy4k07/mcp-baf-audit"
+Issues = "https://github.com/andriy4k07/mcp-baf-audit/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_baf_audit"]

mcp_baf_audit-0.2.0/src/mcp_baf_audit/__init__.py

@@ -0,0 +1,54 @@
+"""mcp-baf-audit — единый JSONL-аудит для сервисов BAF (mcp-baf, baf-write-mcp, hermes).
+
+Схема записи общая (см. writer.SCHEMA_VERSION). Публичный API намеренно
+повторяет знакомые из baf-write имена, чтобы интеграция была минимальной.
+"""
+
+from __future__ import annotations
+
+from . import events
+from .events import ALIASES, canonical
+from .reader import iter_events
+from .redact import REDACTED, default_redactor
+from .trace import (
+    get_trace_id,
+    new_trace_id,
+    set_trace_id,
+    to_json,
+    traced,
+)
+from .writer import (
+    DEFAULT_AUDIT_ARCHIVES,
+    DEFAULT_AUDIT_MAX_SIZE_MIB,
+    DEFAULT_MAX_BYTES,
+    SCHEMA_VERSION,
+    AuditLog,
+    AuditWriter,
+    default_cache_dir,
+    user_cache_dir,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AuditWriter",
+    "AuditLog",
+    "traced",
+    "to_json",
+    "set_trace_id",
+    "get_trace_id",
+    "new_trace_id",
+    "default_redactor",
+    "REDACTED",
+    "events",
+    "canonical",
+    "ALIASES",
+    "iter_events",
+    "SCHEMA_VERSION",
+    "DEFAULT_AUDIT_MAX_SIZE_MIB",
+    "DEFAULT_AUDIT_ARCHIVES",
+    "DEFAULT_MAX_BYTES",
+    "default_cache_dir",
+    "user_cache_dir",
+    "__version__",
+]

mcp_baf_audit-0.2.0/src/mcp_baf_audit/events.py

@@ -0,0 +1,99 @@
+"""Каноническая таксономия событий аудита.
+
+Единый словарь namespaced-имён событий для всех сервисов BAF. Раньше каждый
+сервис писал плоские имена ("create", "tool_call", "propose_counterparty"),
+из-за чего одно и то же действие выглядело по-разному и плохо группировалось.
+Здесь зафиксированы канонические имена вида ``<домен>.<действие>``.
+
+Совместимость двусторонняя:
+
+* writer нормализует имя каждой записи через :func:`canonical`, поэтому новые
+  логи всегда несут канонические имена — даже если доменный код по-прежнему
+  передаёт привычное плоское имя ("create" -> "product.create");
+* старые логи остаются читаемыми: потребитель прогоняет прочитанное имя через
+  ту же :func:`canonical` и получает канонический вид, а имена без записи в
+  :data:`ALIASES` (или уже канонические) возвращаются как есть.
+"""
+
+from __future__ import annotations
+
+# ── Канонические имена событий ──────────────────────────────────────
+
+# Вызовы инструментов (обёртка traced()).
+TOOL_CALL = "tool.call"
+TOOL_ERROR = "tool.error"
+
+# Жизненный цикл сервера.
+SERVER_START = "server.start"
+SERVER_STOP = "server.stop"
+SERVER_VERSION_MISMATCH = "server.version_mismatch"
+
+# Номенклатура (каталожная позиция): propose -> validate -> create -> verify.
+PRODUCT_PROPOSE = "product.propose"
+PRODUCT_VALIDATE = "product.validate"
+PRODUCT_CREATE = "product.create"
+PRODUCT_VERIFY = "product.verify"
+PRODUCT_REFUSED = "product.refused"
+
+# Значения списковых свойств номенклатуры.
+PROPERTY_VALUE_PROPOSE = "property_value.propose"
+PROPERTY_VALUE_VALIDATE = "property_value.validate"
+PROPERTY_VALUE_CREATE = "property_value.create"
+
+# Контрагенты.
+COUNTERPARTY_PROPOSE = "counterparty.propose"
+COUNTERPARTY_VALIDATE = "counterparty.validate"
+COUNTERPARTY_CREATE = "counterparty.create"
+COUNTERPARTY_VERIFY = "counterparty.verify"
+
+# Обращения к HTTP-сервису 1С.
+ONE_C_HTTP = "one_c.http"
+
+# Поисковый индекс (mcp-baf): обновление, поиск, кэш.
+INDEX_REFRESH_START = "index.refresh_start"
+INDEX_REFRESH_FINISH = "index.refresh_finish"
+INDEX_REFRESH_ERROR = "index.refresh_error"
+INDEX_SEARCH = "index.search"
+INDEX_CACHE_HIT = "index.cache_hit"
+INDEX_CACHE_MISS = "index.cache_miss"
+
+
+# ── Алиасы: прежние плоские имена -> канонические ───────────────────
+#
+# Только имена, у которых есть канонический эквивалент в таксономии выше.
+# Прочие плоские имена (*_error, *_incomplete, накладные и т.п.) намеренно
+# не отображаются и проходят через canonical() без изменений.
+ALIASES: dict[str, str] = {
+    # Инструменты.
+    "tool_call": TOOL_CALL,
+    "tool_error": TOOL_ERROR,
+    # Сервер.
+    "server_start": SERVER_START,
+    "server_stop": SERVER_STOP,
+    "extension_version_mismatch": SERVER_VERSION_MISMATCH,
+    # Номенклатура (плоские имена baf-write).
+    "propose": PRODUCT_PROPOSE,
+    "validate": PRODUCT_VALIDATE,
+    "create": PRODUCT_CREATE,
+    "verify": PRODUCT_VERIFY,
+    "create_refused": PRODUCT_REFUSED,
+    # Значения свойств.
+    "propose_property_value": PROPERTY_VALUE_PROPOSE,
+    "validate_property_value": PROPERTY_VALUE_VALIDATE,
+    "create_property_value": PROPERTY_VALUE_CREATE,
+    # Контрагенты.
+    "propose_counterparty": COUNTERPARTY_PROPOSE,
+    "validate_counterparty": COUNTERPARTY_VALIDATE,
+    "create_counterparty": COUNTERPARTY_CREATE,
+    "verify_counterparty": COUNTERPARTY_VERIFY,
+}
+
+
+def canonical(name: str) -> str:
+    """Нормализует имя события в каноническое.
+
+    Прежнее плоское имя из :data:`ALIASES` отображается в каноническое;
+    уже каноническое имя (или имя без алиаса) возвращается без изменений.
+    Функция идемпотентна: ``canonical(canonical(x)) == canonical(x)``.
+    """
+    return ALIASES.get(name, name)

mcp_baf_audit-0.2.0/src/mcp_baf_audit/reader.py

@@ -0,0 +1,97 @@
+"""Чтение журнала аудита — единственная «читающая» функция библиотеки.
+
+:func:`iter_events` отдаёт события из активного журнала и (по умолчанию) из
+ротированных архивов в хронологическом порядке. Битые строки молча
+пропускаются — о каждой сообщается через callback ``on_bad_line``, чтобы
+потребитель мог их посчитать. Имя события нормализуется через
+:func:`mcp_baf_audit.events.canonical`, поэтому старые плоские имена (v1) и
+канонические (v2) приходят к читателю единообразно.
+
+На этой функции строятся внешние проекции/дашборд: сама библиотека ни БД,
+ни форматов представления не знает.
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import logging
+import os
+from collections.abc import Callable, Iterator
+from pathlib import Path
+from typing import Any
+
+from .events import canonical
+
+logger = logging.getLogger(__name__)
+
+
+def _sort_key(file_path: str) -> str:
+    """Ключ сортировки архивов: имя без расширения .log.
+
+    Имена архивов: ``<stem>-<YYYYMMDD-HHMMSS>[-<n>].log``. Сортировка по
+    строке без ".log" ставит базовый архив метки раньше его collision-версии
+    ``-<n>`` (та же секунда), потому что более короткая строка-префикс идёт
+    первой; точка ".log" не вмешивается в сравнение.
+    """
+    return file_path[:-4] if file_path.endswith(".log") else file_path
+
+
+def _files_in_order(path: str | Path, follow_rotation: bool) -> list[str]:
+    """Архивы (старые -> новые) и затем активный журнал последним."""
+    p = str(path)
+    files: list[str] = []
+    if follow_rotation:
+        directory = os.path.dirname(p) or "."
+        name = os.path.basename(p)
+        stem = name[:-4] if name.endswith(".log") else name
+        pattern = os.path.join(directory, f"{stem}-*.log")
+        files.extend(sorted(glob.glob(pattern), key=_sort_key))
+    files.append(p)  # активный журнал — самый свежий, читаем последним
+    return files
+
+
+def iter_events(
+    path: str | Path,
+    *,
+    follow_rotation: bool = True,
+    on_bad_line: Callable[[str], None] | None = None,
+) -> Iterator[dict[str, Any]]:
+    """Итерирует события журнала аудита в хронологическом порядке.
+
+    path — путь к активному журналу (например ``<cache>/audit.log``).
+    follow_rotation — включать ротированные архивы ``<stem>-*.log`` перед
+    активным журналом (по умолчанию да).
+    on_bad_line — вызывается с исходным текстом каждой пропущенной (битой)
+    строки; удобно для подсчёта. Битой считается строка, которая не парсится
+    как JSON или не является JSON-объектом. Пустые строки пропускаются молча.
+
+    Каждое отданное событие — dict с нормализованным каноническим ``event``.
+    Отсутствующие/недоступные файлы пропускаются без ошибки.
+    """
+    for file_path in _files_in_order(path, follow_rotation):
+        try:
+            handle = open(file_path, encoding="utf-8")
+        except OSError:
+            continue  # файла нет или нет доступа — не наша забота
+        with handle as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue  # пустые строки не считаем битыми
+                try:
+                    record = json.loads(line)
+                except ValueError:
+                    logger.debug("audit reader: пропущена битая строка")
+                    if on_bad_line is not None:
+                        on_bad_line(line)
+                    continue
+                if not isinstance(record, dict):
+                    logger.debug("audit reader: пропущена не-объектная строка")
+                    if on_bad_line is not None:
+                        on_bad_line(line)
+                    continue
+                event = record.get("event")
+                if isinstance(event, str):
+                    record["event"] = canonical(event)
+                yield record