loom-kernel 10.2.0__tar.gz → 10.3.0__tar.gz

{loom_kernel-10.2.0 → loom_kernel-10.3.0}/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ### lambda
 
+- **lambda:** `identity` is required on `eventbridge`, `s3`, `sns` and
+  `schedule` triggers: a trigger without one fails to load, so no automatic
+  change runs without an actor. An `identity.attributes` key under the
+  reserved `loom:` prefix fails to load too.
+
 - **lambda:** the deploy manifest reuses the loader: `served_routes(source,
   select_interfaces=None)` reads and validates `app.rest.interfaces` and
   `app.rest.disable_routes` itself, the placeholders are read by OmegaConf's
@@ -49,6 +54,37 @@
 
 ## ✨ Features
 
+### audit
+
+- **audit:** a model marked `Audited` records every insert, delete and
+  value-changing update in its store's `audit_log`: the person
+  (`subject`, `mechanism`, `on_behalf_of`), the request (`trace_id`), the
+  changed columns, the row's scopes and the connection. Written by a trigger
+  of guard revision 3 in the same transaction, append-only for everyone,
+  readable only by the `<schema>_auditor` role, partitioned by month.
+  Excluded and secret columns are recorded as redacted. Configured under
+  `stores.<name>.schema.audit` (`enabled`, `retention_months`, `reader`).
+  Run `loom schema bootstrap` from this release before marking a table:
+  revision 3 is one-way, and an application with audited tables refuses to
+  start on an older guard. See "Audit" in the Postgres RLS guide and ADR 0009.
+- **audit:** every transaction on an external Postgres store sets
+  `loom.actor.subject`, `loom.actor.mechanism`, `loom.actor.on_behalf_of`
+  and `loom.trace_id`, scoped store or not. A product `SessionSettings` may
+  not set any `loom.` key.
+- **audit:** the identity of an event trigger acts on behalf of the caller
+  AWS recorded: an S3 record's `userIdentity.principalId`, or the
+  `detail.userIdentity.arn` of an EventBridge event from an `aws.` source.
+  `loom:on_behalf_of` is reserved: JWT claims under `loom:` are dropped.
+- **cli:** `loom schema bootstrap` (as the superuser, sets the migrator's and
+  each login's password from `LOOM_DB_PASSWORD_<USER>`), `loom schema verify`
+  (exit 1 on drift, lists expired audit partitions) and
+  `loom schema audit drop-expired` (one partition past the retention per run).
+- **audit:** the log's partitions are UTC months kept twelve months ahead by
+  every deploy and by `loom schema audit ensure-partitions`, meant for a
+  scheduler; `verify` fails and startup warns with fewer than three months left.
+- **check:** `loom check --deploy` warns (`loom.audit.W001`) about a store
+  whose audit is disabled.
+
 ### jobs
 
 - **jobs:** `app.job_service` (`inline`, `celery` or `module:Class` built with

{loom_kernel-10.2.0 → loom_kernel-10.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 10.2.0
+Version: 10.3.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-10.2.0 → loom_kernel-10.3.0}/src/loom/cli/check.py

@@ -100,6 +100,7 @@ def _load_check_packages() -> None:
     """Import the packages registering loom's checks; the REST ones need the rest extra."""
     importlib.import_module("loom.core.logger")
     importlib.import_module("loom.core.repository.abc")
+    importlib.import_module("loom.core.persistence.audit_checks")
     if importlib.util.find_spec("fastapi") is not None:
         importlib.import_module("loom.rest")
 

loom_kernel-10.3.0/src/loom/cli/schema.py

@@ -0,0 +1,243 @@
+"""``loom schema``: the commands that prepare a row-scoped schema."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Any, NoReturn, TypeVar
+
+import typer
+import yaml
+
+from loom.core.config.errors import ConfigError
+from loom.core.config.keys import ConfigKey
+from loom.core.environment import (
+    DB_PASSWORD_PREFIX,
+    MIGRATOR_URL_VARIABLE,
+    SUPERUSER_URL_VARIABLE,
+    VERIFY_URL_VARIABLE,
+    loom_variable,
+)
+from loom.core.locator import load_application
+from loom.core.persistence.stores import BACKEND_KEY, DEFAULT_STORE, SQLALCHEMY_BACKEND
+from loom.core.schema_names import SchemaNames
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncConnection
+
+    from loom.core.repository.sqlalchemy.rls import BootstrapConfig
+    from loom.core.repository.sqlalchemy.rls.verify import Report
+
+# The commands below import SQLAlchemy inside their bodies: the CLI loads
+# without it, and only these commands require it.
+
+_T = TypeVar("_T")
+_STORES = str(ConfigKey.STORES)  # a plain str: yaml.safe_dump refuses a StrEnum key
+_STORE_PATH = f"{_STORES}.{DEFAULT_STORE}"
+
+
+schema_app = typer.Typer(no_args_is_help=True, help="Prepare a row-scoped schema.")
+audit_app = typer.Typer(no_args_is_help=True, help="Operate the store's audit log.")
+schema_app.add_typer(audit_app, name="audit")
+
+_CONFIG_OPTION = typer.Option("--config", help="A config directory or file, as the app loads it.")
+
+
+@schema_app.command("init")
+def init(
+    name: Annotated[str, typer.Argument(help="The application schema.")],
+    config: Annotated[
+        Path | None,
+        typer.Option("--config", help="Merge the names into this configuration file."),
+    ] = None,
+) -> None:
+    """Derive the names around a schema once and write them into the configuration.
+
+    Without ``--config`` the block is printed. With it the names are merged
+    into ``stores.default.schema``, declaring the store with ``backend:
+    sqlalchemy`` when the file does not; a name the product already changed
+    is never overwritten.
+    """
+    try:
+        block = _block(name, SchemaNames.derived(name))
+        if config is None:
+            document = {
+                _STORES: {DEFAULT_STORE: {BACKEND_KEY: SQLALCHEMY_BACKEND, "schema": block}}
+            }
+            typer.echo(yaml.safe_dump(document, sort_keys=False), nl=False)
+            return
+        _write(config, block)
+    except (ValueError, yaml.YAMLError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+
+def _write(config: Path, block: dict[str, Any]) -> None:
+    document = _load(config)
+    store = _section(_section(document, _STORES, _STORES), DEFAULT_STORE, _STORE_PATH)
+    backend = store.setdefault(BACKEND_KEY, SQLALCHEMY_BACKEND)
+    if backend != SQLALCHEMY_BACKEND:
+        raise ValueError(
+            f"{_STORE_PATH}.{BACKEND_KEY} is {backend!r}; "
+            f"a row-scoped schema needs {SQLALCHEMY_BACKEND}"
+        )
+    schema = _section(store, "schema", f"{_STORE_PATH}.schema")
+    conflicts = _merge(schema, block, f"{_STORE_PATH}.schema")
+    if conflicts:
+        raise ValueError(
+            "these names differ from the derived ones and were kept: " + ", ".join(conflicts)
+        )
+    config.write_text(yaml.safe_dump(document, sort_keys=False))
+
+
+def _load(config: Path) -> dict[str, Any]:
+    if not config.exists():
+        return {}
+    loaded = yaml.safe_load(config.read_text())
+    if loaded is None:
+        return {}
+    if not isinstance(loaded, dict):
+        raise ValueError(f"{config} must hold a mapping at its top level")
+    return loaded
+
+
+def _section(parent: dict[str, Any], key: str, path: str) -> dict[str, Any]:
+    current = parent.get(key)
+    if current is None:
+        current = parent[key] = {}
+    if not isinstance(current, dict):
+        raise ValueError(f"{path} must be a mapping")
+    return current
+
+
+def _block(name: str, names: SchemaNames) -> dict[str, Any]:
+    return {
+        "name": name,
+        "guard": names.guard,
+        "groups": {"readers": names.readers, "writers": names.writers},
+        "version_tables": {"structure": names.version_table, "data": names.data_version_table},
+    }
+
+
+def _merge(target: dict[str, Any], values: dict[str, Any], path: str) -> list[str]:
+    conflicts: list[str] = []
+    for key, value in values.items():
+        current = target.get(key)
+        if current is None:
+            target[key] = value
+        elif isinstance(value, dict) and isinstance(current, dict):
+            conflicts += _merge(current, value, f"{path}.{key}")
+        elif current != value:
+            conflicts.append(f"{path}.{key}")
+    return conflicts
+
+
+@schema_app.command("bootstrap")
+def bootstrap(config: Annotated[Path, _CONFIG_OPTION]) -> None:
+    """Install or upgrade the guard and configure roles, as the superuser; idempotent.
+
+    The superuser URL comes from ``LOOM_SUPERUSER_URL`` and the password of the
+    migrator and of each database user with a login from ``LOOM_DB_PASSWORD_<USER>``.
+    """
+    from loom.core.repository.sqlalchemy.rls import apply_bootstrap
+
+    try:
+        settings = _bootstrap_config(config)
+        logins = [settings.roles.migrator] + [
+            name for name, user in settings.database_users.items() if user.login
+        ]
+        passwords = {name: _env(DB_PASSWORD_PREFIX + name.upper()) for name in logins}
+        asyncio.run(apply_bootstrap(_env(SUPERUSER_URL_VARIABLE), settings, passwords))
+    except ConfigError as exc:
+        _fail(exc)
+    typer.echo(f"guard of {config} is installed and configured")
+
+
+@schema_app.command("verify")
+def verify_schema(config: Annotated[Path, _CONFIG_OPTION]) -> None:
+    """Compare the database with the application; exit 1 on any drift.
+
+    The URL comes from ``LOOM_VERIFY_URL``, else ``LOOM_SUPERUSER_URL``: the
+    guard's configuration row needs a privileged reader. Audit partitions past
+    the retention are listed, not counted as drift.
+    """
+    from loom.core.repository.sqlalchemy.rls import verify
+
+    try:
+        application = load_application(str(config))
+        url = loom_variable(VERIFY_URL_VARIABLE) or _env(SUPERUSER_URL_VARIABLE)
+        report = asyncio.run(verify(url, application))
+    except ConfigError as exc:
+        _fail(exc)
+    _print_report(report)
+    if not report.ok:
+        raise typer.Exit(1)
+
+
+def _print_report(report: Report) -> None:
+    """One line per finding, then one per audit partition past the retention."""
+    for finding in report.findings:
+        subject = f"{finding.table} " if finding.table else ""
+        typer.echo(f"{subject}{finding.check}: expected {finding.expected}, found {finding.actual}")
+    for partition in report.expired_audit_partitions:
+        typer.echo(f"expired audit partition: {partition}")
+
+
+@audit_app.command("drop-expired")
+def drop_expired() -> None:
+    """Drop the oldest audit partition past the retention, as the migrator; one per run."""
+    from loom.core.repository.sqlalchemy.rls.audit import drop_expired_audit_partition
+
+    try:
+        dropped = asyncio.run(_as_migrator(drop_expired_audit_partition))
+    except ConfigError as exc:
+        _fail(exc)
+    typer.echo(f"dropped {dropped}" if dropped else "no audit partition is past the retention")
+
+
+@audit_app.command("ensure-partitions")
+def ensure_partitions() -> None:
+    """Create the audit partitions missing in the next twelve months, as the migrator.
+
+    Idempotent; meant for a scheduler between deploys (monthly is enough).
+    """
+    from loom.core.repository.sqlalchemy.rls.audit import ensure_audit_partitions
+
+    try:
+        created = asyncio.run(_as_migrator(ensure_audit_partitions))
+    except ConfigError as exc:
+        _fail(exc)
+    typer.echo(f"created {created} audit partition(s)")
+
+
+async def _as_migrator(action: Callable[[AsyncConnection], Awaitable[_T]]) -> _T:
+    """Run *action* in one transaction as the migrator (``LOOM_MIGRATOR_URL``)."""
+    from sqlalchemy.ext.asyncio import create_async_engine
+    from sqlalchemy.pool import NullPool
+
+    engine = create_async_engine(_env(MIGRATOR_URL_VARIABLE), poolclass=NullPool)
+    try:
+        async with engine.begin() as connection:
+            return await action(connection)
+    finally:
+        await engine.dispose()
+
+
+def _bootstrap_config(config: Path) -> BootstrapConfig:
+    settings = load_application(str(config)).bootstrap
+    if settings is None:
+        raise ConfigError(f"{config} declares no row-scoped schema to bootstrap")
+    return settings
+
+
+def _env(name: str) -> str:
+    value = loom_variable(name)
+    if not value:
+        raise ConfigError(f"set {name}")
+    return value
+
+
+def _fail(exc: Exception) -> NoReturn:
+    typer.echo(str(exc), err=True)
+    raise typer.Exit(1) from exc

{loom_kernel-10.2.0 → loom_kernel-10.3.0}/src/loom/core/backend/sqlalchemy.py

@@ -47,6 +47,7 @@ from sqlalchemy.sql.schema import DEFAULT_NAMING_CONVENTION
 from loom.core.backend.core_model import CoreModel, CoreProfilePlan, CoreRelationStep
 from loom.core.backend.scoped_ddl import SCHEMA_KEY, register_listeners
 from loom.core.config import ConfigError
+from loom.core.model.audited import AuditedTable, AuditedTables, audited_table, is_audited
 from loom.core.model.enums import Cardinality, OnDelete, ServerDefault, ServerOnUpdate
 from loom.core.model.field import ColumnType, Field
 from loom.core.model.introspection import (
@@ -127,6 +128,7 @@ class _Compilation:
     core: dict[type, CoreModel]
     pending: dict[type, dict[str, Relation]]
     scoped: dict[tuple[str | None, str], ScopedTable] = field(default_factory=dict)
+    audited: dict[tuple[str | None, str], AuditedTable] = field(default_factory=dict)
 
 
 _COMPILATION_KEY = "loom.compilation"
@@ -165,6 +167,11 @@ def scoped_tables(metadata: MetaData | None = None) -> Mapping[tuple[str | None,
     return dict(_compilation_for(metadata).scoped)
 
 
+def audited_tables(metadata: MetaData | None = None) -> AuditedTables:
+    """Audited tables compiled into ``metadata``, keyed by ``(schema, name)``."""
+    return dict(_compilation_for(metadata).audited)
+
+
 def _build_sa_column_type(col_type: ColumnType) -> Any:
     if col_type.type_name == "Postgres.ARRAY":
         if len(col_type.args) != 1:
@@ -269,7 +276,18 @@ def _compile_model(
     comp.compiled[struct_cls] = sa_cls
     comp.tables[table_name] = sa_cls
     comp.pending[struct_cls] = get_relations(struct_cls)
-    table = sa_cls.__table__
+    _register_protection(struct_cls, sa_cls.__table__, comp, scopes, partition)
+    return sa_cls
+
+
+def _register_protection(
+    struct_cls: type,
+    table: Any,
+    comp: _Compilation,
+    scopes: tuple[Any, ...],
+    partition: Any,
+) -> None:
+    """Record what the guard protects on *table*: its scopes and its audit trigger."""
     scoped = None
     if scopes:
         scoped = ScopedTable(
@@ -280,6 +298,8 @@ def _compile_model(
             partition_by=None if partition is None else partition.column,
         )
         comp.scoped[(table.schema, table.name)] = scoped
+    if is_audited(struct_cls):
+        comp.audited[(table.schema, table.name)] = _audited(struct_cls, table)
     schema = comp.metadata.info.get(SCHEMA_KEY)
     if schema is not None:
         register_listeners(
@@ -288,7 +308,25 @@ def _compile_model(
             scoped=scoped,
             privileges=declared_privileges(struct_cls),
         )
-    return sa_cls
+
+
+def _audited(struct_cls: type, table: Any) -> AuditedTable:
+    """Compile the audit declaration of *struct_cls* onto its *table*.
+
+    Raises:
+        ConfigError: When an excluded column does not exist, or an excluded or
+            secret column is part of the primary key.
+    """
+    try:
+        return audited_table(
+            struct_cls,
+            schema=table.schema,
+            name=table.name,
+            columns=(column.name for column in table.columns),
+            key_columns=(column.name for column in table.primary_key.columns),
+        )
+    except ValueError as exc:
+        raise ConfigError(str(exc)) from exc
 
 
 def _refuse_undeclared_column_types(

{loom_kernel-10.2.0 → loom_kernel-10.3.0}/src/loom/core/environment.py

@@ -55,6 +55,18 @@ SPARK_IVY_DIR_VARIABLE: Final = "LOOM_SPARK_IVY_DIR"
 SPARK_OFFLINE_VARIABLE: Final = "LOOM_SPARK_OFFLINE"
 """``1`` makes the Spark test session use only cached jars."""
 
+SUPERUSER_URL_VARIABLE: Final = "LOOM_SUPERUSER_URL"
+"""Database URL ``loom schema bootstrap`` installs the guard with."""
+
+VERIFY_URL_VARIABLE: Final = "LOOM_VERIFY_URL"
+"""Database URL ``loom schema verify`` reads the catalogue with."""
+
+MIGRATOR_URL_VARIABLE: Final = "LOOM_MIGRATOR_URL"
+"""Database URL ``loom schema audit drop-expired`` drops a partition with."""
+
+DB_PASSWORD_PREFIX: Final = "LOOM_DB_PASSWORD_"
+"""Prefix of the variables holding a database login's password, by upper-case login."""
+
 _BASE_CONFIG_FILE: Final = "base.yaml"
 
 
@@ -289,13 +301,17 @@ def select_config_paths(
 
 __all__ = [
     "CONFIG_VARIABLE",
+    "DB_PASSWORD_PREFIX",
     "ENVIRONMENT_VARIABLE",
     "ETL_CONFIG_VARIABLE",
+    "MIGRATOR_URL_VARIABLE",
     "OVERRIDE_PREFIX",
     "SPARK_IVY_DIR_VARIABLE",
     "SPARK_OFFLINE_VARIABLE",
     "SPOOL_DIR_VARIABLE",
     "STORAGE_CONFIG_VARIABLE",
+    "SUPERUSER_URL_VARIABLE",
+    "VERIFY_URL_VARIABLE",
     "Environment",
     "config_source_paths",
     "configured_variable",

{loom_kernel-10.2.0 → loom_kernel-10.3.0}/src/loom/core/identity/__init__.py

@@ -7,11 +7,18 @@ no transport and no infrastructure.
 """
 
 from loom.core.identity.context import current_identity, reset_identity, set_identity
-from loom.core.identity.identity import ANONYMOUS, Identity
+from loom.core.identity.identity import (
+    ANONYMOUS,
+    ON_BEHALF_OF_ATTRIBUTE,
+    RESERVED_ATTRIBUTE_PREFIX,
+    Identity,
+)
 from loom.core.identity.issuer import IssuedToken, TokenIssuer
 
 __all__ = [
     "ANONYMOUS",
+    "ON_BEHALF_OF_ATTRIBUTE",
+    "RESERVED_ATTRIBUTE_PREFIX",
     "Identity",
     "IssuedToken",
     "TokenIssuer",

{loom_kernel-10.2.0 → loom_kernel-10.3.0}/src/loom/core/identity/identity.py

@@ -15,6 +15,10 @@ from types import MappingProxyType
 from loom.core.errors import Forbidden, Unauthenticated
 
 _EMPTY_ATTRIBUTES: Mapping[str, str] = MappingProxyType({})
+RESERVED_ATTRIBUTE_PREFIX = "loom:"
+"""Attributes under this prefix are set only by loom itself, never by an authenticator."""
+ON_BEHALF_OF_ATTRIBUTE = f"{RESERVED_ATTRIBUTE_PREFIX}on_behalf_of"
+"""The person a system identity acts for; set by loom's event dispatchers and audited."""
 
 _NO_SUBJECT_MESSAGE = "Authentication required: the request carries no verified identity."
 

{loom_kernel-10.2.0 → loom_kernel-10.3.0}/src/loom/core/locator.py

@@ -14,8 +14,8 @@ from __future__ import annotations
 import os
 import re
 import sys
-from collections.abc import Mapping
-from dataclasses import dataclass
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Final, get_args
 
@@ -31,6 +31,7 @@ from loom.core.environment import (
     resolve_environment,
 )
 from loom.core.logger import get_logger
+from loom.core.model.audited import AuditedTables
 from loom.core.model.scoped import ScopedTables, declared_scopes
 from loom.core.persistence.database import (
     DatabaseConfig,
@@ -83,6 +84,17 @@ class Application:
     scoped: ScopedTables
     scope_sources: Mapping[str, str]
     store: StoreKey = DEFAULT_STORE
+    audited: AuditedTables = field(default_factory=dict)
+
+    @property
+    def guarded(self) -> bool:
+        """Whether the store needs the guard: it declares scoped or audited tables."""
+        return bool(self.scoped or self.audited)
+
+    @property
+    def active_audited(self) -> AuditedTables:
+        """The audited tables that record rows: the marked ones while ``schema.audit.enabled``."""
+        return self.audited if self.database.schema.audit.enabled else {}
 
     @property
     def path(self) -> str:
@@ -119,14 +131,7 @@ def load_application(
         ConfigError: When the path is missing, a required key is absent or a
             value has the wrong shape; the message names the key.
     """
-    from sqlalchemy import MetaData
-
-    from loom.core.backend.scoped_ddl import SCHEMA_KEY
-    from loom.core.backend.sqlalchemy import (
-        compile_all,
-        configured_naming_convention,
-        scoped_tables,
-    )
+    from loom.core.backend.sqlalchemy import audited_tables, scoped_tables
 
     path = _resolve_path(config_path)
     environment = resolve_environment()
@@ -143,14 +148,10 @@ def load_application(
     if skipped:
         _log.info("StoresNotLoaded", store=store, skipped=skipped)
     schema = database.schema
-    metadata = MetaData(
-        naming_convention=configured_naming_convention(schema.naming_convention, path=spec.path)
-    )
-    if schema.name is not None:
-        metadata.info[SCHEMA_KEY] = _schema_name(schema.name, spec.path)
-    compile_all(*models, metadata=metadata)
+    metadata = _compiled_metadata(models, schema, spec.path)
     scoped = scoped_tables(metadata)
-    bootstrap = _bootstrap(schema, spec.path) if scoped else None
+    audited = audited_tables(metadata)
+    bootstrap = _bootstrap(schema, spec.path) if scoped or audited else None
     scope_sources = _scope_sources(schema, scoped, spec.path) if scoped else {}
     return Application(
         models=tuple(models),
@@ -160,9 +161,26 @@ def load_application(
         scoped=scoped,
         scope_sources=scope_sources,
         store=store,
+        audited=audited,
     )
 
 
+def _compiled_metadata(models: Sequence[type], schema: SchemaConfig, path: str) -> MetaData:
+    """A metadata holding *models* compiled under the store's naming convention and schema."""
+    from sqlalchemy import MetaData
+
+    from loom.core.backend.scoped_ddl import SCHEMA_KEY
+    from loom.core.backend.sqlalchemy import compile_all, configured_naming_convention
+
+    metadata = MetaData(
+        naming_convention=configured_naming_convention(schema.naming_convention, path=path)
+    )
+    if schema.name is not None:
+        metadata.info[SCHEMA_KEY] = _schema_name(schema.name, path)
+    compile_all(*models, metadata=metadata)
+    return metadata
+
+
 def add_code_path(code_path: str | os.PathLike[str], config_dir: Path) -> Path:
     """Put an application's code directory first on ``sys.path``, once.
 
@@ -228,6 +246,8 @@ def _bootstrap(schema: SchemaConfig, path: str) -> BootstrapConfig:
             version_table=version_tables.structure,
             data_version_table=version_tables.data,
         ),
+        auditor=schema.audit.reader,
+        audit_retention_months=schema.audit.retention_months,
     )
     try:
         return config.validated()

{loom_kernel-10.2.0 → loom_kernel-10.3.0}/src/loom/core/model/__init__.py

@@ -6,6 +6,7 @@ from loom.core.model._loom_type import (
     msgspec_type,
     pydantic_type,
 )
+from loom.core.model.audited import Audited, AuditedTable
 from loom.core.model.base import BaseModel, LoomStructMeta
 from loom.core.model.enums import Cardinality, OnDelete, OnUpdate, ServerDefault, ServerOnUpdate
 from loom.core.model.field import ColumnField, ColumnType, Field, ScopedField
@@ -56,6 +57,8 @@ from loom.core.model.types import (
 from loom.core.model.types_postgres import Postgres
 
 __all__ = [
+    "Audited",
+    "AuditedTable",
     "BaseModel",
     "READ_WRITE",
     "Privilege",

loom_kernel-10.3.0/src/loom/core/model/audited.py

@@ -0,0 +1,75 @@
+"""Marker and descriptor for tables whose every row change is recorded in the audit log."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import ClassVar
+
+from loom.core.model.redaction import is_secret_name
+
+
+class Audited:
+    """Mark a model as audited; adds no column.
+
+    Every insert, delete and value-changing update of the table is recorded
+    in the store's audit log by a trigger the guard installs. Columns named
+    in ``__audit_exclude__``, and every column whose name is a credential
+    (:func:`~loom.core.model.redaction.is_secret_name`), are never written
+    to the log: a change to one is recorded as redacted. The table needs a
+    primary key, and no excluded or secret column may be part of it.
+    """
+
+    __audited__: ClassVar[bool] = True
+    __audit_exclude__: ClassVar[frozenset[str]] = frozenset()
+
+
+@dataclass(frozen=True, slots=True)
+class AuditedTable:
+    """A compiled audited table: its key columns and the columns never written to the log."""
+
+    schema: str | None
+    name: str
+    key_columns: tuple[str, ...]
+    excluded: frozenset[str]
+
+
+AuditedTables = Mapping[tuple[str | None, str], AuditedTable]  # by schema and name
+
+
+def is_audited(model: type) -> bool:
+    """Whether *model* carries the :class:`Audited` marker."""
+    return bool(getattr(model, "__audited__", False))
+
+
+def audited_table(
+    model: type,
+    *,
+    schema: str | None,
+    name: str,
+    columns: Iterable[str],
+    key_columns: Iterable[str],
+) -> AuditedTable:
+    """Compile *model*'s audit declaration.
+
+    Raises:
+        ValueError: When the table has no primary key, an excluded column does
+            not exist, or an excluded or secret column is part of the primary
+            key; the message names the table and the column.
+    """
+    names = tuple(columns)
+    keys = tuple(key_columns)
+    if not keys:
+        raise ValueError(f"audited table {name} has no primary key; the log keys each row by it")
+    declared = frozenset(getattr(model, "__audit_exclude__", frozenset()))
+    unknown = sorted(declared - set(names))
+    if unknown:
+        raise ValueError(f"audited table {name} excludes unknown columns {unknown}")
+    excluded = declared | {column for column in names if is_secret_name(column)}
+    in_key = sorted(excluded & set(keys))
+    if in_key:
+        raise ValueError(
+            f"audited table {name}: {in_key} cannot be excluded from the log "
+            "and be part of the primary key"
+        )
+    return AuditedTable(schema=schema, name=name, key_columns=keys, excluded=excluded)