terp-cap-audit 0.1.0__tar.gz

terp_cap_audit-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_audit-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: terp-cap-audit
+Version: 0.1.0
+Summary: Terp audit capability — the durable, append-only sink for the core audit seam.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: terp-core==0.1.0

terp_cap_audit-0.1.0/escape-hatch-budget.json

@@ -0,0 +1,4 @@
+{
+  "arch-allow-mutations-emit-audit": 1,
+  "arch-allow-table-models-use-base-table": 1
+}

terp_cap_audit-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-audit"
+version = "0.1.0"
+description = "Terp audit capability — the durable, append-only sink for the core audit seam."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+]
+
+# Self-registering: the kernel discovers this ModuleSpec via the entry point,
+# mounting the admin (read-only) `audit` log router without any composition-root
+# edit. The durable sink is installed by create_app(audit_sink=persist_audit).
+[project.entry-points."terp.capabilities"]
+audit = "terp.capabilities.audit:module"
+
+# Owns the append-only `audit_event` table, so it ships an independent, linear
+# Alembic history (its own `alembic_version_audit` table). `terp migrate` discovers
+# this via the `terp.migrations` group (ADR 0027).
+[project.entry-points."terp.migrations"]
+audit = "terp.capabilities.audit"
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.audit`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/audit"]

terp_cap_audit-0.1.0/src/terp/capabilities/audit/__init__.py

@@ -0,0 +1,31 @@
+"""terp.capabilities.audit — the durable sink behind the core audit seam.
+
+``terp.core`` defines the audit *seam* (a typed :class:`~terp.core.AuditRecord`, the
+:class:`~terp.core.AuditPolicy` registry, and an emit chokepoint whose default sink
+only logs). This opt-in capability supplies the **durable** half: an append-only
+:class:`AuditEvent` table, the :func:`persist_audit` sink, and a self-registering,
+admin-only router to read the trail.
+
+Wiring is a single composition-root line — ``create_app(...,
+audit_sink=persist_audit)`` — after which **every** ``BaseService`` mutation in
+every module is recorded with zero per-module code. It depends only on
+``terp-core``: the sink consumes the public :class:`~terp.core.AuditRecord` /
+:class:`~terp.core.AuditPolicy` surface, never a sibling capability.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.audit.models import AuditEvent
+from terp.capabilities.audit.router import module, router
+from terp.capabilities.audit.schemas import AuditEventRead
+from terp.capabilities.audit.service import list_audit_events
+from terp.capabilities.audit.sink import persist_audit
+
+__all__ = [
+    "AuditEvent",
+    "AuditEventRead",
+    "list_audit_events",
+    "module",
+    "persist_audit",
+    "router",
+]

terp_cap_audit-0.1.0/src/terp/capabilities/audit/migrations/versions/3a9d71c5e40f_enforce_audit_append_only.py

@@ -0,0 +1,97 @@
+"""enforce audit append-only at the database
+
+Revision ID: 3a9d71c5e40f
+Revises: 586333320cdd
+Create Date: 2026-07-06 20:45:00.000000
+
+ADR 0076: the audit trail was append-only **by convention** (no service exposes
+an update/delete); this revision makes the database itself refuse an UPDATE or
+DELETE on ``audit_event``, so even code that bypasses the service layer (a raw
+session, a compromised dependency, an ad-hoc script on the app role) cannot
+silently rewrite history. Row-level triggers abort both statements on the two
+dialects the gate exercises (SQLite dev/test, PostgreSQL production).
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = '3a9d71c5e40f'
+down_revision: str | None = '586333320cdd'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+_POSTGRES_UPGRADE = """
+CREATE FUNCTION terp_audit_event_append_only() RETURNS trigger AS $$
+BEGIN
+    RAISE EXCEPTION 'audit_event is append-only (ADR 0076)';
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_audit_event_no_update
+    BEFORE UPDATE ON audit_event
+    FOR EACH ROW EXECUTE FUNCTION terp_audit_event_append_only();
+
+CREATE TRIGGER trg_audit_event_no_delete
+    BEFORE DELETE ON audit_event
+    FOR EACH ROW EXECUTE FUNCTION terp_audit_event_append_only();
+"""
+
+_POSTGRES_DOWNGRADE = """
+DROP TRIGGER trg_audit_event_no_delete ON audit_event;
+
+DROP TRIGGER trg_audit_event_no_update ON audit_event;
+
+DROP FUNCTION terp_audit_event_append_only();
+"""
+
+_SQLITE_UPGRADE = """
+CREATE TRIGGER trg_audit_event_no_update
+    BEFORE UPDATE ON audit_event
+BEGIN
+    SELECT RAISE(ABORT, 'audit_event is append-only (ADR 0076)');
+END;
+
+CREATE TRIGGER trg_audit_event_no_delete
+    BEFORE DELETE ON audit_event
+BEGIN
+    SELECT RAISE(ABORT, 'audit_event is append-only (ADR 0076)');
+END;
+"""
+
+_SQLITE_DOWNGRADE = """
+DROP TRIGGER trg_audit_event_no_delete;
+
+DROP TRIGGER trg_audit_event_no_update;
+"""
+
+
+def _statements(script: str) -> list[str]:
+    """Split *script* on blank lines (each block is one statement, `;`-safe for triggers)."""
+    return [block.strip() for block in script.split("\n\n") if block.strip()]
+
+
+def upgrade() -> None:
+    dialect = op.get_context().dialect.name
+    if dialect == "postgresql":
+        for statement in _statements(_POSTGRES_UPGRADE):
+            op.execute(statement)
+    elif dialect == "sqlite":
+        for statement in _statements(_SQLITE_UPGRADE):
+            op.execute(statement)
+    # Any other (unverified) dialect gets no trigger: the application-level
+    # convention still holds, and production boot already requires an explicit
+    # DB_ALLOW_UNVERIFIED_DIALECT acknowledgement for such a database.
+
+
+def downgrade() -> None:
+    dialect = op.get_context().dialect.name
+    if dialect == "postgresql":
+        for statement in _statements(_POSTGRES_DOWNGRADE):
+            op.execute(statement)
+    elif dialect == "sqlite":
+        for statement in _statements(_SQLITE_DOWNGRADE):
+            op.execute(statement)

terp_cap_audit-0.1.0/src/terp/capabilities/audit/migrations/versions/586333320cdd_create_audit_tables.py

@@ -0,0 +1,59 @@
+"""create audit tables
+
+Revision ID: 586333320cdd
+Revises: 
+Create Date: 2026-06-26 20:38:59.070766
+
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = '586333320cdd'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('audit_event',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('action', sqlmodel.sql.sqltypes.AutoString(length=16), nullable=False),
+    sa.Column('target_type', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
+    sa.Column('target_id', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
+    sa.Column('actor_id', sa.Uuid(), nullable=True),
+    sa.Column('request_id', sqlmodel.sql.sqltypes.AutoString(length=64), nullable=True),
+    sa.Column('payload', sa.JSON(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_audit_event'))
+    )
+    with op.batch_alter_table('audit_event', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_audit_event_action'), ['action'], unique=False)
+        batch_op.create_index(batch_op.f('ix_audit_event_actor_id'), ['actor_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_audit_event_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_audit_event_request_id'), ['request_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_audit_event_target_id'), ['target_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_audit_event_target_type'), ['target_type'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('audit_event', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_audit_event_target_type'))
+        batch_op.drop_index(batch_op.f('ix_audit_event_target_id'))
+        batch_op.drop_index(batch_op.f('ix_audit_event_request_id'))
+        batch_op.drop_index(batch_op.f('ix_audit_event_created_at'))
+        batch_op.drop_index(batch_op.f('ix_audit_event_actor_id'))
+        batch_op.drop_index(batch_op.f('ix_audit_event_action'))
+
+    op.drop_table('audit_event')
+    # ### end Alembic commands ###

terp_cap_audit-0.1.0/src/terp/capabilities/audit/models.py

@@ -0,0 +1,54 @@
+"""The append-only audit log table — the durable record behind the core seam.
+
+A row is one immutable fact: *actor* performed *action* on *target* during request
+*request_id*, at *created_at*. It is written **only** by
+:func:`terp.capabilities.audit.sink.persist_audit` (the sink ``create_app`` wires
+into the core audit seam) and never updated or deleted, so it can answer "who did
+what, when" long after the fact.
+
+Append-only by design, it composes :class:`~terp.core.UUIDPrimaryKeyMixin` rather
+than ``BaseTable``: there is no ``updated_at`` (rows never change) and no
+optimistic-concurrency ``version`` (there is no concurrent write to a row). The
+``action`` column is a plain string (the :class:`~terp.core.AuditAction` value) so
+this low-layer capability needs no higher-layer enum.
+
+``actor_id`` is an FK-less UUID on purpose: like the access capability's grant,
+this leaf must not import the higher-layer user table it references, so it stays
+something everything above it can depend on (never the reverse).
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import JSON, DateTime
+from sqlmodel import Column, Field, SQLModel
+
+from terp.core import UUIDPrimaryKeyMixin
+
+
+def _utc_now() -> datetime:
+    """UTC ``now`` provider for this non-``BaseTable`` append-only row."""
+    return datetime.now(UTC)
+
+
+class AuditEvent(UUIDPrimaryKeyMixin, SQLModel, table=True):  # arch-allow-table-models-use-base-table: append-only audit log has no updated_at/version by design (see module docstring)
+    __tablename__ = "audit_event"
+
+    action: str = Field(max_length=16, index=True)
+    target_type: str = Field(max_length=128, index=True)
+    target_id: str = Field(max_length=128, index=True)
+    actor_id: uuid.UUID | None = Field(default=None, index=True)
+    request_id: str | None = Field(default=None, max_length=64, index=True)
+    payload: dict[str, Any] | None = Field(default=None, sa_column=Column(JSON))
+    created_at: datetime = Field(
+        default_factory=_utc_now,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=False,
+        index=True,
+    )
+
+
+__all__ = ["AuditEvent"]

terp_cap_audit-0.1.0/src/terp/capabilities/audit/router.py

@@ -0,0 +1,37 @@
+"""Admin (read-only) audit-log router + the discoverable ``ModuleSpec``.
+
+**Admin-only** (``Policy`` requires ``ADMIN``): the audit trail is privileged —
+it records who did what across the whole app. Exposed as ``module`` so the
+kernel's entry-point discovery mounts it at ``/api/v1/audit`` with no
+composition-root edit. The log has no write surface here: rows are appended by the
+sink inside each mutation's transaction, never through the API.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from terp.core import ADMIN, ModuleSpec, Page, PaginationDep, Policy, SessionDep
+
+from terp.capabilities.audit.schemas import AuditEventRead
+from terp.capabilities.audit.service import list_audit_events
+
+router = APIRouter(tags=["audit"])
+
+
+@router.get("/", response_model=Page[AuditEventRead])
+def list_events(session: SessionDep, pagination: PaginationDep) -> Page[AuditEventRead]:
+    rows, total = list_audit_events(session, pagination=pagination)
+    return Page[AuditEventRead].of(
+        [AuditEventRead.model_validate(row) for row in rows], total, pagination
+    )
+
+
+module = ModuleSpec(
+    name="audit",
+    router=router,
+    policy=Policy(read=ADMIN, write=ADMIN),
+)
+
+
+__all__ = ["module", "router"]

terp_cap_audit-0.1.0/src/terp/capabilities/audit/schemas.py

@@ -0,0 +1,23 @@
+"""Read DTOs for the audit log. The log is append-only — there is no write surface."""
+
+from __future__ import annotations
+
+import datetime
+import uuid
+from typing import Any
+
+from terp.core import BaseSchema
+
+
+class AuditEventRead(BaseSchema):
+    id: uuid.UUID
+    action: str
+    target_type: str
+    target_id: str
+    actor_id: uuid.UUID | None
+    request_id: str | None
+    payload: dict[str, Any] | None
+    created_at: datetime.datetime
+
+
+__all__ = ["AuditEventRead"]

terp_cap_audit-0.1.0/src/terp/capabilities/audit/service.py

@@ -0,0 +1,32 @@
+"""Read access to the audit log — one paginated, newest-first query.
+
+The log is append-only (written by the sink), so this capability exposes only a
+read path: a single, bounded list used by the admin router. Mirrors the kernel's
+pagination contract so the trail is browsed like any other ``Page[T]``.
+"""
+
+from __future__ import annotations
+
+from sqlmodel import Session, col, func, select
+
+from terp.core import PaginationParams
+
+from terp.capabilities.audit.models import AuditEvent
+
+
+def list_audit_events(
+    session: Session, *, pagination: PaginationParams
+) -> tuple[list[AuditEvent], int]:
+    """Return one page of audit events, newest first, with the total count."""
+    total = session.exec(select(func.count()).select_from(AuditEvent)).one()
+    rows = session.exec(
+        select(AuditEvent)
+        .order_by(col(AuditEvent.created_at).desc(), col(AuditEvent.id).desc())
+        .offset(pagination.skip)
+        .limit(pagination.limit)
+    ).all()
+    return list(rows), int(total)
+
+
+__all__ = ["list_audit_events"]
+

terp_cap_audit-0.1.0/src/terp/capabilities/audit/sink.py

@@ -0,0 +1,51 @@
+"""The durable audit sink — turns a core :class:`AuditRecord` into a stored row.
+
+``create_app(audit_sink=persist_audit)`` installs this on the core audit seam, so
+every ``BaseService`` mutation appends an :class:`AuditEvent` **inside the caller's
+transaction** — the row commits atomically with the business write, and a failure
+here aborts the mutation rather than losing the trail (fail-closed).
+
+The record reaches this point already centrally redacted (see
+:meth:`terp.core.AuditPolicy.redact`); the sink only clips caller-influenceable
+strings to their column bounds and strips NUL bytes, so a hostile or oversized
+value can never break the INSERT — the audit trail must outlive bad input.
+"""
+
+from __future__ import annotations
+
+from sqlmodel import Session
+
+from terp.core import AuditPolicy, AuditRecord, DurableAuditSink
+
+from terp.capabilities.audit.models import AuditEvent
+
+
+def _clip(value: str | None, limit: int) -> str | None:
+    """Strip NUL bytes and clamp *value* to a bounded column's *limit*."""
+    if value is None:
+        return None
+    return value.replace("\x00", "")[:limit]
+
+
+def _persist_audit(session: Session, record: AuditRecord, policy: AuditPolicy) -> None:
+    """Append *record* to the audit log within the caller's transaction (no commit).
+
+    The chokepoint that emitted *record* owns the commit, so the audit row rides
+    the same unit of work as the business mutation. *policy* is accepted to satisfy
+    the sink contract; redaction was already applied centrally before this call.
+    """
+    event = AuditEvent(
+        action=record.action.value,
+        target_type=_clip(record.target_type, 128) or "",
+        target_id=_clip(record.target_id, 128) or "",
+        actor_id=record.actor_id,
+        request_id=_clip(record.request_id, 64),
+        payload=dict(record.payload) if record.payload else None,
+    )
+    session.add(event)  # arch-allow-mutations-emit-audit: this IS the durable audit sink, the base of the write stack — it cannot route through BaseService
+
+
+persist_audit = DurableAuditSink("terp.capabilities.audit.persist_audit", _persist_audit)
+
+
+__all__ = ["persist_audit"]