mcp-gatehouse 0.1.0__tar.gz

mcp_gatehouse-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

mcp_gatehouse-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+audit.jsonl

mcp_gatehouse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick George
+
+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_gatehouse-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: mcp-gatehouse
+Version: 0.1.0
+Summary: Permission tiers, approval gates, and audit logging for MCP servers — the server is the gatekeeper.
+Project-URL: Homepage, https://nickgeorgeai.com/mcp
+Project-URL: Repository, https://github.com/nickgeorgeseo/mcp-gatehouse
+Author-email: Nick George <nick@nickgeorgeai.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,audit-log,mcp,model-context-protocol,permissions,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.27
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-gatehouse
+
+<!-- mcp-name: io.github.nickgeorgeseo/gatehouse -->
+
+[![CI](https://github.com/nickgeorgeseo/mcp-gatehouse/actions/workflows/ci.yml/badge.svg)](https://github.com/nickgeorgeseo/mcp-gatehouse/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mcp-gatehouse)](https://pypi.org/project/mcp-gatehouse/)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-gatehouse)](https://pypi.org/project/mcp-gatehouse/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Permission tiers, approval gates, and audit logging for MCP servers.**
+The server is the gatekeeper: you decide what an AI can read, what it can
+write, and what's off-limits — and every action gets logged.
+
+Most MCP servers hand the model every tool at full strength and keep no
+record of what it did. That's fine for a demo. It's not fine the day an
+agent has write access to your CRM, your books, or your order system.
+`mcp-gatehouse` is the missing gate, enforced **inside** the server — no
+proxy, no external policy service, no dependencies beyond the official
+[`mcp` SDK](https://github.com/modelcontextprotocol/python-sdk).
+
+```
+pip install mcp-gatehouse
+```
+
+## What you get
+
+| | |
+|---|---|
+| **Permission tiers** | Every tool is declared `READ`, `WRITE`, or `DESTRUCTIVE` — and the tier also emits honest spec `ToolAnnotations` (`readOnlyHint` / `destructiveHint`), which the wrapper won't let you override to lie. |
+| **Approval gates** | Tiers you choose require a sign-off before the tool runs. Your approver is any callable — a terminal prompt, a Slack ping, a ticket. **Fails closed:** a gated tool with no approver configured is denied, not waved through. |
+| **Audit log** | Append-only JSONL, one line per call — allowed, denied, or failed — with UTC timestamps and durations. The answer to "what did the AI actually do?" six months later. |
+| **Redaction** | Argument keys you name (`api_key`, `password`, `token`, … by default) are masked before they reach the log *or* the approver. |
+| **Denylist** | Block a tool outright, whatever its tier. |
+
+## Quickstart
+
+```python
+from mcp.server.fastmcp import FastMCP
+from mcp_gatehouse import AccessTier, AuditLog, Gatehouse, Policy
+
+mcp = FastMCP("order-desk")
+gatehouse = Gatehouse(
+    mcp,
+    policy=Policy(approver=lambda req: input(f"allow {req.tool}? [y/N] ") == "y"),
+    audit=AuditLog(path="audit.jsonl"),
+)
+
+@gatehouse.tool(tier=AccessTier.READ)
+def lookup_order(order_id: str) -> str:
+    """Look up an order's status."""
+    ...
+
+@gatehouse.tool(tier=AccessTier.DESTRUCTIVE)
+def cancel_order(order_id: str) -> str:
+    """Cancel an order. Runs only if the approver says yes."""
+    ...
+
+mcp.run()
+```
+
+That's the whole integration: build your `FastMCP` server exactly as the
+SDK docs show, but register tools through the gatehouse. Schema generation,
+transports, and everything else work unchanged — the guard preserves the
+function's signature.
+
+Under the default policy, `DESTRUCTIVE` requires approval and everything
+is audited. Gate writes too with one line:
+
+```python
+Policy(require_approval=frozenset({AccessTier.WRITE, AccessTier.DESTRUCTIVE}), ...)
+```
+
+What the audit trail looks like:
+
+```json
+{"ts": "2026-07-16T14:02:11+00:00", "tool": "lookup_order", "tier": "read", "outcome": "ok", "arguments": {"order_id": "4417"}, "duration_ms": 0.42}
+{"ts": "2026-07-16T14:02:38+00:00", "tool": "add_note", "tier": "write", "outcome": "ok", "arguments": {"order_id": "4417", "note": "call back", "api_key": "«redacted»"}, "duration_ms": 1.08}
+{"ts": "2026-07-16T14:03:05+00:00", "tool": "cancel_order", "tier": "destructive", "outcome": "denied", "reason": "approver refused", "arguments": {"order_id": "4417"}}
+```
+
+## Try the demo
+
+The package ships a runnable order-desk server with all three tiers wired
+up and a terminal-prompt approver:
+
+```
+mcp-gatehouse-demo
+```
+
+Point any MCP client at it over stdio (Claude Desktop, etc.), ask the model
+to cancel an order, and watch the approval land in your terminal — and the
+verdict land in `audit.jsonl` either way. `examples/orders_server.py` is
+the same server as a copyable template.
+
+## Design notes
+
+- **Enforcement lives inside the server**, at the tool boundary. A proxy
+  can't see your tools' semantics, and a policy service is one more thing
+  to deploy. A 40-person plant doesn't have a platform team; this is a few
+  small classes and a JSONL file.
+- **Fail closed.** Security defaults that quietly allow are worse than none.
+  That includes redaction: argument values the scrubber can't take apart
+  (arbitrary objects, bytes) are replaced with an opaque placeholder rather
+  than passed through, and exception *messages* stay out of the log —
+  only the exception type is recorded, because error text loves to embed
+  the very values you just redacted.
+- **The audit log records denials and errors**, not just successes — the
+  calls that *didn't* happen are half the story.
+- **A blocking terminal approver and the stdio transport don't mix** —
+  stdout/stdin are the protocol pipe. The demo's approver prompts on
+  `/dev/tty` for exactly that reason (and denies when no terminal exists).
+  Real deployments should approve out-of-band: Slack, a ticket, a queue.
+- **What this is not:** authentication, transport encryption, or a sandbox.
+  It's a gate inside your server, not a perimeter around it. See
+  [SECURITY.md](SECURITY.md).
+
+## Compatibility
+
+Targets the official [`mcp` Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+v1.x (`mcp>=1.27,<2`) and Python 3.10+. When SDK v2 ships for the
+2026-07-28 spec revision, a v2-compatible release will follow — the
+public API here (`Gatehouse`, `Policy`, `AuditLog`, `AccessTier`) will
+not change.
+
+## Who built this
+
+[Nick George](https://nickgeorgeai.com) — I design and run MCP servers in
+production for a mid-market reverse logistics-tech company, and build them
+for businesses at [nickgeorgeai.com](https://nickgeorgeai.com). This
+library is the permission-and-audit discipline from those builds, extracted.
+
+If you're an owner or operator wondering what MCP even is, start with the
+plain-English guide: [What is an MCP server?](https://nickgeorgeai.com/mcp)
+
+## License
+
+[MIT](LICENSE)

mcp_gatehouse-0.1.0/README.md

@@ -0,0 +1,137 @@
+# mcp-gatehouse
+
+<!-- mcp-name: io.github.nickgeorgeseo/gatehouse -->
+
+[![CI](https://github.com/nickgeorgeseo/mcp-gatehouse/actions/workflows/ci.yml/badge.svg)](https://github.com/nickgeorgeseo/mcp-gatehouse/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mcp-gatehouse)](https://pypi.org/project/mcp-gatehouse/)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-gatehouse)](https://pypi.org/project/mcp-gatehouse/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Permission tiers, approval gates, and audit logging for MCP servers.**
+The server is the gatekeeper: you decide what an AI can read, what it can
+write, and what's off-limits — and every action gets logged.
+
+Most MCP servers hand the model every tool at full strength and keep no
+record of what it did. That's fine for a demo. It's not fine the day an
+agent has write access to your CRM, your books, or your order system.
+`mcp-gatehouse` is the missing gate, enforced **inside** the server — no
+proxy, no external policy service, no dependencies beyond the official
+[`mcp` SDK](https://github.com/modelcontextprotocol/python-sdk).
+
+```
+pip install mcp-gatehouse
+```
+
+## What you get
+
+| | |
+|---|---|
+| **Permission tiers** | Every tool is declared `READ`, `WRITE`, or `DESTRUCTIVE` — and the tier also emits honest spec `ToolAnnotations` (`readOnlyHint` / `destructiveHint`), which the wrapper won't let you override to lie. |
+| **Approval gates** | Tiers you choose require a sign-off before the tool runs. Your approver is any callable — a terminal prompt, a Slack ping, a ticket. **Fails closed:** a gated tool with no approver configured is denied, not waved through. |
+| **Audit log** | Append-only JSONL, one line per call — allowed, denied, or failed — with UTC timestamps and durations. The answer to "what did the AI actually do?" six months later. |
+| **Redaction** | Argument keys you name (`api_key`, `password`, `token`, … by default) are masked before they reach the log *or* the approver. |
+| **Denylist** | Block a tool outright, whatever its tier. |
+
+## Quickstart
+
+```python
+from mcp.server.fastmcp import FastMCP
+from mcp_gatehouse import AccessTier, AuditLog, Gatehouse, Policy
+
+mcp = FastMCP("order-desk")
+gatehouse = Gatehouse(
+    mcp,
+    policy=Policy(approver=lambda req: input(f"allow {req.tool}? [y/N] ") == "y"),
+    audit=AuditLog(path="audit.jsonl"),
+)
+
+@gatehouse.tool(tier=AccessTier.READ)
+def lookup_order(order_id: str) -> str:
+    """Look up an order's status."""
+    ...
+
+@gatehouse.tool(tier=AccessTier.DESTRUCTIVE)
+def cancel_order(order_id: str) -> str:
+    """Cancel an order. Runs only if the approver says yes."""
+    ...
+
+mcp.run()
+```
+
+That's the whole integration: build your `FastMCP` server exactly as the
+SDK docs show, but register tools through the gatehouse. Schema generation,
+transports, and everything else work unchanged — the guard preserves the
+function's signature.
+
+Under the default policy, `DESTRUCTIVE` requires approval and everything
+is audited. Gate writes too with one line:
+
+```python
+Policy(require_approval=frozenset({AccessTier.WRITE, AccessTier.DESTRUCTIVE}), ...)
+```
+
+What the audit trail looks like:
+
+```json
+{"ts": "2026-07-16T14:02:11+00:00", "tool": "lookup_order", "tier": "read", "outcome": "ok", "arguments": {"order_id": "4417"}, "duration_ms": 0.42}
+{"ts": "2026-07-16T14:02:38+00:00", "tool": "add_note", "tier": "write", "outcome": "ok", "arguments": {"order_id": "4417", "note": "call back", "api_key": "«redacted»"}, "duration_ms": 1.08}
+{"ts": "2026-07-16T14:03:05+00:00", "tool": "cancel_order", "tier": "destructive", "outcome": "denied", "reason": "approver refused", "arguments": {"order_id": "4417"}}
+```
+
+## Try the demo
+
+The package ships a runnable order-desk server with all three tiers wired
+up and a terminal-prompt approver:
+
+```
+mcp-gatehouse-demo
+```
+
+Point any MCP client at it over stdio (Claude Desktop, etc.), ask the model
+to cancel an order, and watch the approval land in your terminal — and the
+verdict land in `audit.jsonl` either way. `examples/orders_server.py` is
+the same server as a copyable template.
+
+## Design notes
+
+- **Enforcement lives inside the server**, at the tool boundary. A proxy
+  can't see your tools' semantics, and a policy service is one more thing
+  to deploy. A 40-person plant doesn't have a platform team; this is a few
+  small classes and a JSONL file.
+- **Fail closed.** Security defaults that quietly allow are worse than none.
+  That includes redaction: argument values the scrubber can't take apart
+  (arbitrary objects, bytes) are replaced with an opaque placeholder rather
+  than passed through, and exception *messages* stay out of the log —
+  only the exception type is recorded, because error text loves to embed
+  the very values you just redacted.
+- **The audit log records denials and errors**, not just successes — the
+  calls that *didn't* happen are half the story.
+- **A blocking terminal approver and the stdio transport don't mix** —
+  stdout/stdin are the protocol pipe. The demo's approver prompts on
+  `/dev/tty` for exactly that reason (and denies when no terminal exists).
+  Real deployments should approve out-of-band: Slack, a ticket, a queue.
+- **What this is not:** authentication, transport encryption, or a sandbox.
+  It's a gate inside your server, not a perimeter around it. See
+  [SECURITY.md](SECURITY.md).
+
+## Compatibility
+
+Targets the official [`mcp` Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+v1.x (`mcp>=1.27,<2`) and Python 3.10+. When SDK v2 ships for the
+2026-07-28 spec revision, a v2-compatible release will follow — the
+public API here (`Gatehouse`, `Policy`, `AuditLog`, `AccessTier`) will
+not change.
+
+## Who built this
+
+[Nick George](https://nickgeorgeai.com) — I design and run MCP servers in
+production for a mid-market reverse logistics-tech company, and build them
+for businesses at [nickgeorgeai.com](https://nickgeorgeai.com). This
+library is the permission-and-audit discipline from those builds, extracted.
+
+If you're an owner or operator wondering what MCP even is, start with the
+plain-English guide: [What is an MCP server?](https://nickgeorgeai.com/mcp)
+
+## License
+
+[MIT](LICENSE)

mcp_gatehouse-0.1.0/SECURITY.md

@@ -0,0 +1,20 @@
+# Security
+
+`mcp-gatehouse` is security *tooling*, so it gets held to its own standard.
+
+## Reporting a vulnerability
+
+Email **nick@nickgeorgeai.com** with the details. You'll get a reply
+within 72 hours. Please don't open a public issue for anything exploitable —
+give me a chance to ship the fix first.
+
+## What this library does and doesn't do
+
+**Does:** enforce per-tool permission tiers, gate calls behind an approver
+you control, keep an append-only audit trail, and mask configured argument
+keys before they reach logs or approvers.
+
+**Doesn't:** authenticate clients, encrypt transports, sandbox tool code,
+or protect against a malicious *server author*. It's a gate inside your
+server, not a perimeter around it. Treat third-party MCP servers with the
+same scrutiny you'd give any software you install.

mcp_gatehouse-0.1.0/examples/orders_server.py

@@ -0,0 +1,59 @@
+"""A copyable template: the demo order-desk server, spelled out.
+
+This is the same server `mcp-gatehouse-demo` runs — copy it and swap the
+ORDERS dict for your real system. The approver comes from the package
+because prompting a human is trickier than it looks: over the stdio
+transport, stdout/stdin are the protocol pipe, so the prompt must go to
+the controlling terminal (and fail closed when there isn't one).
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from mcp_gatehouse import AccessTier, AuditLog, Gatehouse, Policy
+from mcp_gatehouse.demo import terminal_approver
+
+# A stand-in for your real system of record.
+ORDERS = {
+    "4417": {"customer": "Blue Ridge Cabinets", "status": "packed", "notes": []},
+    "4418": {"customer": "Piedmont Supply", "status": "picking", "notes": []},
+}
+
+mcp = FastMCP("order-desk")
+gatehouse = Gatehouse(
+    mcp,
+    policy=Policy(approver=terminal_approver),
+    audit=AuditLog(path="audit.jsonl"),
+)
+
+
+@gatehouse.tool(tier=AccessTier.READ)
+def lookup_order(order_id: str) -> str:
+    """Look up an order's status."""
+    order = ORDERS.get(order_id)
+    if order is None:
+        return f"no order {order_id}"
+    return f"{order_id} · {order['customer']} · {order['status']}"
+
+
+@gatehouse.tool(tier=AccessTier.WRITE)
+def add_note(order_id: str, note: str, api_key: str = "") -> str:
+    """Attach a note to an order. (The api_key never reaches the log.)"""
+    if order_id not in ORDERS:
+        return f"no order {order_id}"
+    ORDERS[order_id]["notes"].append(note)
+    return f"note added to {order_id}"
+
+
+@gatehouse.tool(tier=AccessTier.DESTRUCTIVE)
+def cancel_order(order_id: str) -> str:
+    """Cancel an order. Requires approval — the gate fails closed."""
+    if order_id not in ORDERS:
+        return f"no order {order_id}"
+    ORDERS[order_id]["status"] = "cancelled"
+    return f"{order_id} cancelled"
+
+
+if __name__ == "__main__":
+    mcp.run()

mcp_gatehouse-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-gatehouse"
+version = "0.1.0"
+description = "Permission tiers, approval gates, and audit logging for MCP servers — the server is the gatekeeper."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Nick George", email = "nick@nickgeorgeai.com" }]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "security",
+    "audit-log",
+    "permissions",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Security",
+]
+dependencies = ["mcp>=1.27,<2"]
+
+[project.scripts]
+mcp-gatehouse-demo = "mcp_gatehouse.demo:main"
+# Alias so `uvx mcp-gatehouse` / `pipx run mcp-gatehouse` resolve without --from.
+mcp-gatehouse = "mcp_gatehouse.demo:main"
+
+[project.urls]
+Homepage = "https://nickgeorgeai.com/mcp"
+Repository = "https://github.com/nickgeorgeseo/mcp-gatehouse"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "anyio>=4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_gatehouse"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mcp_gatehouse-0.1.0/server.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.nickgeorgeseo/gatehouse",
+  "title": "mcp-gatehouse",
+  "description": "Permission tiers, approval gates, and audit logging for MCP servers, enforced inside the server at the tool boundary. Ships a runnable order-desk demo: READ tools run freely, WRITE tools are audited with secret redaction, DESTRUCTIVE tools require human approval and fail closed.",
+  "version": "0.1.0",
+  "websiteUrl": "https://nickgeorgeai.com/mcp",
+  "repository": {
+    "url": "https://github.com/nickgeorgeseo/mcp-gatehouse",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "mcp-gatehouse",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

mcp_gatehouse-0.1.0/src/mcp_gatehouse/__init__.py

@@ -0,0 +1,30 @@
+"""mcp-gatehouse — permission tiers, approval gates, and audit logging
+for MCP servers built with the official Python SDK.
+
+The server is the gatekeeper: you decide what an AI can read, what it can
+write, and what's off-limits — and every action gets logged.
+"""
+
+from .audit import AuditLog, NullAuditLog
+from .gatehouse import GateDenied, Gatehouse
+from .policy import (
+    AccessTier,
+    ApprovalRequest,
+    Approver,
+    Policy,
+    redact_arguments,
+)
+
+__all__ = [
+    "AccessTier",
+    "ApprovalRequest",
+    "Approver",
+    "AuditLog",
+    "GateDenied",
+    "Gatehouse",
+    "NullAuditLog",
+    "Policy",
+    "redact_arguments",
+]
+
+__version__ = "0.1.0"

mcp_gatehouse-0.1.0/src/mcp_gatehouse/audit.py

@@ -0,0 +1,76 @@
+"""Append-only JSONL audit log.
+
+One line per tool call — allowed, denied, or failed — with UTC timestamps
+and redacted arguments. The point is a trail you can grep six months later
+when someone asks "what did the AI actually do?"
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import io
+import json
+import os
+import threading
+from pathlib import Path
+from typing import Any, TextIO
+
+
+class AuditLog:
+    """Writes one JSON object per line to a file or stream.
+
+    Thread-safe for concurrent tool calls within one process. Events are
+    flushed on every write — an audit log that loses its tail in a crash
+    is not an audit log.
+    """
+
+    def __init__(
+        self,
+        path: str | os.PathLike[str] | None = None,
+        stream: TextIO | None = None,
+    ) -> None:
+        if (path is None) == (stream is None):
+            raise ValueError("provide exactly one of `path` or `stream`")
+        self._lock = threading.Lock()
+        if path is not None:
+            p = Path(path)
+            p.parent.mkdir(parents=True, exist_ok=True)
+            self._stream: TextIO = p.open("a", encoding="utf-8")
+            self._owns_stream = True
+        else:
+            assert stream is not None
+            self._stream = stream
+            self._owns_stream = False
+
+    def record(self, **event: Any) -> None:
+        """Append one event. A ``ts`` field (UTC, ISO-8601) is added.
+
+        ``ensure_ascii=True`` on purpose: it escapes U+2028/U+2029/NEL and
+        friends, so a crafted argument value can never split one record
+        into two for line-aware readers. One ``\\n`` per record, always.
+        """
+        event = {"ts": _dt.datetime.now(_dt.timezone.utc).isoformat(), **event}
+        line = json.dumps(event, ensure_ascii=True, default=str)
+        with self._lock:
+            self._stream.write(line + "\n")
+            self._stream.flush()
+
+    def close(self) -> None:
+        if self._owns_stream:
+            self._stream.close()
+
+    def __enter__(self) -> "AuditLog":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class NullAuditLog(AuditLog):
+    """An audit log that swallows everything. For tests and dry runs."""
+
+    def __init__(self) -> None:
+        super().__init__(stream=io.StringIO())
+
+    def record(self, **event: Any) -> None:  # noqa: D102 — intentionally inert
+        pass