lorebase-store 0.2.3__py3-none-any.whl

lorebase_store/auth/checkpoints.py

@@ -0,0 +1,185 @@
+"""Signed checkpoints of the audit chains, kept outside the database.
+
+A table owner can delete the newest entries of a chain, or recompute a whole chain, and the
+chain still verifies. A checkpoint records the head (`seq`, `entry_hash`) of every chain of a
+stream at a point in time; Scribe publishes one periodically to a sink the database cannot
+reach (`scribe.audit_checkpoints`), and `audit verify --checkpoints` compares the log with
+them: a checkpointed entry that is missing reveals a truncation, one whose hash differs a
+rewrite. Entries newer than the latest checkpoint are not covered.
+
+A checkpoint is a JSON document signed with Ed25519 over the RFC 8785 form of every member
+but `signature`, so a verifier needs only the public key and a writer to the sink cannot forge
+one::
+
+    {"format": "lorebase.audit.checkpoint/1", "stream": "actions",
+     "at": "2026-10-25T09:00:00.000000+00:00", "key_id": "main",
+     "chains": [{"domain_id": "acme", "seq": 42, "entry_hash": "<hex>"}, ...],
+     "signature": "<base64>"}
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_private_key, load_pem_public_key
+
+from lorebase_core.canonical import jcs_bytes
+from lorebase_store.auth.audit import AuditRepository, AuditStream, ChainHead
+
+FORMAT = "lorebase.audit.checkpoint/1"
+MAX_DOCUMENT_BYTES = 16 * 1024 * 1024
+
+
+class CheckpointError(ValueError):
+    """A document is not a valid checkpoint or its signature does not verify."""
+
+
+@dataclass(frozen=True)
+class Checkpoint:
+    """The heads of every chain of a stream at `at`."""
+
+    stream: AuditStream
+    at: datetime
+    key_id: str
+    chains: tuple[ChainHead, ...]
+
+    def body(self) -> dict[str, Any]:
+        """Every member but the signature."""
+        return {
+            "format": FORMAT,
+            "stream": self.stream.value,
+            "at": self.at.astimezone(UTC).isoformat(timespec="microseconds"),
+            "key_id": self.key_id,
+            "chains": [
+                {"domain_id": h.domain_id, "seq": h.seq, "entry_hash": h.entry_hash.hex()}
+                for h in self.chains
+            ],
+        }
+
+    def name(self, prefix: str = "") -> str:
+        """Object name of the checkpoint under `prefix`: by stream, then sortable time."""
+        stamp = self.at.astimezone(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+        return f"{prefix}{self.stream.value}/{stamp}.json"
+
+
+@dataclass(frozen=True)
+class CheckpointFinding:
+    """A checkpointed entry the log no longer holds as it was."""
+
+    checkpoint_at: datetime
+    domain_id: str | None
+    seq: int
+    problem: Literal["missing", "changed"]
+
+
+def load_private_key(pem: str) -> Ed25519PrivateKey:
+    """An Ed25519 private key from PEM (PKCS #8, as `openssl genpkey -algorithm ed25519`)."""
+    try:
+        key = load_pem_private_key(pem.encode(), password=None)
+    except (ValueError, TypeError):
+        # The parser's message is left out: it never needs to describe secret material.
+        raise CheckpointError("not a PEM private key (unencrypted PKCS #8)") from None
+    if not isinstance(key, Ed25519PrivateKey):
+        raise CheckpointError("the checkpoint signing key must be an Ed25519 key")
+    return key
+
+
+def load_public_key(pem: str) -> Ed25519PublicKey:
+    """An Ed25519 public key from PEM (`openssl pkey -pubout`)."""
+    try:
+        key = load_pem_public_key(pem.encode())
+    except (ValueError, TypeError) as error:
+        raise CheckpointError(f"not a PEM public key: {error}") from None
+    if not isinstance(key, Ed25519PublicKey):
+        raise CheckpointError("the checkpoint key must be an Ed25519 key")
+    return key
+
+
+def signed_document(checkpoint: Checkpoint, key: Ed25519PrivateKey) -> bytes:
+    """The checkpoint as signed JSON."""
+    body = checkpoint.body()
+    signature = key.sign(jcs_bytes(body))
+    document = {**body, "signature": base64.b64encode(signature).decode("ascii")}
+    return json.dumps(document, separators=(",", ":"), sort_keys=True).encode()
+
+
+def _head(item: Any) -> ChainHead:
+    if not isinstance(item, Mapping):
+        raise CheckpointError("a chain must be an object")
+    domain_id, seq, digest = item.get("domain_id"), item.get("seq"), item.get("entry_hash")
+    if domain_id is not None and not isinstance(domain_id, str):
+        raise CheckpointError("chain domain_id must be a string or null")
+    if not isinstance(seq, int) or isinstance(seq, bool) or seq < 1:
+        raise CheckpointError("chain seq must be a positive integer")
+    try:
+        entry_hash = bytes.fromhex(digest) if isinstance(digest, str) else b""
+    except ValueError:
+        entry_hash = b""
+    if len(entry_hash) != 32:
+        raise CheckpointError("chain entry_hash must be 64 hex digits")
+    return ChainHead(domain_id, seq, entry_hash)
+
+
+def parse_document(raw: bytes, public_key: Ed25519PublicKey) -> Checkpoint:
+    """A checkpoint from signed JSON; `CheckpointError` unless well formed and signed by
+    `public_key`."""
+    if len(raw) > MAX_DOCUMENT_BYTES:
+        raise CheckpointError("checkpoint document too large")
+    try:
+        document = json.loads(raw)
+    except (ValueError, UnicodeDecodeError) as error:
+        raise CheckpointError(f"not JSON: {error}") from None
+    if not isinstance(document, dict) or document.get("format") != FORMAT:
+        raise CheckpointError(f"not a {FORMAT} document")
+    encoded = document.pop("signature", None)
+    if not isinstance(encoded, str):
+        raise CheckpointError("signature missing")
+    try:
+        signature = base64.b64decode(encoded, validate=True)
+        public_key.verify(signature, jcs_bytes(document))
+    except (binascii.Error, InvalidSignature):
+        raise CheckpointError("signature does not verify") from None
+    try:
+        stream = AuditStream(str(document.get("stream")))
+        at = datetime.fromisoformat(str(document.get("at")))
+    except ValueError as error:
+        raise CheckpointError(str(error)) from None
+    chains = document.get("chains")
+    if not isinstance(chains, list):
+        raise CheckpointError("chains must be a list")
+    if at.tzinfo is None:
+        raise CheckpointError("at must carry a time zone")
+    return Checkpoint(stream, at, str(document.get("key_id", "")), tuple(map(_head, chains)))
+
+
+async def compare(
+    repository: AuditRepository,
+    checkpoints: Iterable[Checkpoint],
+    *,
+    domain_ids: Sequence[str | None] | None = None,
+) -> list[CheckpointFinding]:
+    """Checkpointed heads the log does not hold with the same hash, oldest checkpoint first.
+    `domain_ids` limits the comparison to some chains (None: every chain)."""
+    findings: list[CheckpointFinding] = []
+    for checkpoint in sorted(checkpoints, key=lambda c: c.at):
+        heads = [h for h in checkpoint.chains if domain_ids is None or h.domain_id in domain_ids]
+        stored = await repository.entry_hashes([(h.domain_id, h.seq) for h in heads])
+        for head in heads:
+            found = stored.get((head.domain_id, head.seq))
+            if found is None:
+                findings.append(
+                    CheckpointFinding(checkpoint.at, head.domain_id, head.seq, "missing")
+                )
+            elif found != head.entry_hash:
+                findings.append(
+                    CheckpointFinding(checkpoint.at, head.domain_id, head.seq, "changed")
+                )
+    return findings

lorebase_store/auth/grants.py

@@ -0,0 +1,161 @@
+"""Role grants of principals and groups in a Domain (design 10.2).
+
+Grants are Domain rows under row-level security: each lookup names its Domain, or the system
+scope when it spans Domains.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from dataclasses import dataclass
+from datetime import datetime
+
+from sqlalchemy import delete, select, tuple_
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from lorebase_store.auth.scope import new_id, rls_scope
+from lorebase_store.models import Domain, Grant
+from lorebase_store.models.enums import GrantScope
+
+ID_PREFIX = "grt"
+
+
+@dataclass(frozen=True)
+class GrantRecord:
+    """A role of `subject` (principal or group id) in a Domain, optionally narrowed by scope."""
+
+    id: str
+    domain_id: str
+    subject: str
+    role: str
+    scope_type: GrantScope
+    scope_ref: str | None
+    created_by: str
+    created_at: datetime
+
+
+def _record(row: Grant) -> GrantRecord:
+    return GrantRecord(
+        id=row.id,
+        domain_id=row.domain_id,
+        subject=row.subject,
+        role=row.role,
+        scope_type=row.scope_type,
+        scope_ref=row.scope_ref,
+        created_by=row.created_by,
+        created_at=row.created_at,
+    )
+
+
+class GrantRepository:
+    """Grants by Domain and subject."""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def add(
+        self,
+        *,
+        domain_id: str,
+        subject: str,
+        role: str,
+        created_by: str,
+        scope_type: GrantScope = GrantScope.DOMAIN,
+        scope_ref: str | None = None,
+    ) -> GrantRecord:
+        """Insert a grant, or return the identical one that already exists.
+
+        `scope_ref` is required for every scope but `domain`, where it must be absent.
+        """
+        if (scope_type is GrantScope.DOMAIN) != (scope_ref is None):
+            raise ValueError("scope_ref is required for kind, operation and branch scopes only")
+        async with rls_scope(self._session, domain_ids=[domain_id]):
+            existing = (
+                await self._session.execute(
+                    select(Grant).where(
+                        Grant.domain_id == domain_id,
+                        Grant.subject == subject,
+                        Grant.role == role,
+                        Grant.scope_type == scope_type,
+                        Grant.scope_ref.is_not_distinct_from(scope_ref),
+                    )
+                )
+            ).scalar_one_or_none()
+            if existing is not None:
+                return _record(existing)
+            row = Grant(
+                id=new_id(ID_PREFIX),
+                domain_id=domain_id,
+                subject=subject,
+                role=role,
+                scope_type=scope_type,
+                scope_ref=scope_ref,
+                created_by=created_by,
+            )
+            self._session.add(row)
+            await self._session.flush()
+            await self._session.refresh(row)
+            return _record(row)
+
+    async def get(self, domain_id: str, grant_id: str) -> GrantRecord | None:
+        """A grant of the Domain."""
+        async with rls_scope(self._session, domain_ids=[domain_id]):
+            row = (
+                await self._session.execute(
+                    select(Grant).where(Grant.domain_id == domain_id, Grant.id == grant_id)
+                )
+            ).scalar_one_or_none()
+        return _record(row) if row else None
+
+    async def delete(self, domain_id: str, grant_id: str) -> bool:
+        """Revoke a grant; false when the Domain has no such grant."""
+        async with rls_scope(self._session, domain_ids=[domain_id]):
+            result = await self._session.execute(
+                delete(Grant).where(Grant.domain_id == domain_id, Grant.id == grant_id)
+            )
+        return bool(result.rowcount)  # type: ignore[attr-defined]
+
+    async def for_subjects(self, domain_id: str, subjects: Collection[str]) -> list[GrantRecord]:
+        """Every grant in the Domain held by any of `subjects`."""
+        if not subjects:
+            return []
+        async with rls_scope(self._session, domain_ids=[domain_id]):
+            rows = await self._session.execute(
+                select(Grant)
+                .where(Grant.domain_id == domain_id, Grant.subject.in_(list(subjects)))
+                .order_by(Grant.created_at, Grant.id)
+            )
+            return [_record(row) for row in rows.scalars()]
+
+    async def domain_exists(self, domain_id: str) -> bool:
+        """Whether a Domain with this id exists (Domains are not under row-level security)."""
+        found = await self._session.execute(select(Domain.id).where(Domain.id == domain_id))
+        return found.scalar_one_or_none() is not None
+
+    async def for_subjects_anywhere(self, subjects: Collection[str]) -> list[GrantRecord]:
+        """Every grant held by any of `subjects`, across Domains (system scope)."""
+        if not subjects:
+            return []
+        async with rls_scope(self._session, bypass=True):
+            rows = await self._session.execute(
+                select(Grant)
+                .where(Grant.subject.in_(list(subjects)))
+                .order_by(Grant.domain_id, Grant.created_at, Grant.id)
+            )
+            return [_record(row) for row in rows.scalars()]
+
+    async def list_domain(
+        self, domain_id: str, *, limit: int, after: tuple[datetime, str] | None = None
+    ) -> list[GrantRecord]:
+        """Grants of a Domain in creation order; `after` is `(created_at, id)` of the last item."""
+        statement = (
+            select(Grant)
+            .where(Grant.domain_id == domain_id)
+            .order_by(Grant.created_at, Grant.id)
+            .limit(limit)
+        )
+        if after is not None:
+            statement = statement.where(tuple_(Grant.created_at, Grant.id) > after)
+        async with rls_scope(self._session, domain_ids=[domain_id]):
+            rows = await self._session.execute(statement)
+            return [_record(row) for row in rows.scalars()]

lorebase_store/auth/principals.py

@@ -0,0 +1,158 @@
+"""Principals and groups (design 10.2, 13.2).
+
+Users come from an identity provider and are provisioned on first sign-in; service principals
+are created by administrators and own API keys. Ids are prefixed: `usr_`, `svc_`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import CompoundSelect, Select, select, tuple_
+from sqlalchemy.dialects.postgresql import insert
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from lorebase_store.auth.scope import new_id
+from lorebase_store.models import Group, GroupMember, Principal
+from lorebase_store.models.enums import PrincipalType
+
+ID_PREFIXES = {
+    PrincipalType.USER: "usr",
+    PrincipalType.SERVICE: "svc",
+    PrincipalType.API_KEY: "key",
+}
+
+
+@dataclass(frozen=True)
+class PrincipalRecord:
+    """A stored principal."""
+
+    id: str
+    type: PrincipalType
+    display_name: str
+    external_subject: str | None
+    created_at: datetime
+
+
+def _record(row: Principal) -> PrincipalRecord:
+    return PrincipalRecord(
+        id=row.id,
+        type=row.type,
+        display_name=row.display_name,
+        external_subject=row.external_subject,
+        created_at=row.created_at,
+    )
+
+
+class PrincipalRepository:
+    """Principals of one installation (no row-level security: the table is installation-wide)."""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def get(self, principal_id: str) -> PrincipalRecord | None:
+        """The principal with this id, if any."""
+        row = await self._session.get(Principal, principal_id)
+        return _record(row) if row else None
+
+    async def get_by_subject(self, external_subject: str) -> PrincipalRecord | None:
+        """The principal linked to an identity provider subject, if any."""
+        row = (
+            await self._session.execute(
+                select(Principal).where(Principal.external_subject == external_subject)
+            )
+        ).scalar_one_or_none()
+        return _record(row) if row else None
+
+    async def add(
+        self,
+        type_: PrincipalType,
+        display_name: str,
+        *,
+        external_subject: str | None = None,
+        principal_id: str | None = None,
+    ) -> PrincipalRecord:
+        """Insert a principal. A taken `external_subject` raises `IntegrityError`."""
+        row = Principal(
+            id=principal_id or new_id(ID_PREFIXES[type_]),
+            type=type_,
+            display_name=display_name,
+            external_subject=external_subject,
+        )
+        self._session.add(row)
+        await self._session.flush()
+        await self._session.refresh(row)
+        return _record(row)
+
+    async def get_or_create_user(
+        self, external_subject: str, display_name: str
+    ) -> tuple[PrincipalRecord, bool]:
+        """The user of a provider subject, created on first use. Safe under concurrency.
+
+        Returns the principal and whether this call created it.
+        """
+        statement = (
+            insert(Principal)
+            .values(
+                id=new_id(ID_PREFIXES[PrincipalType.USER]),
+                type=PrincipalType.USER,
+                display_name=display_name,
+                external_subject=external_subject,
+            )
+            .on_conflict_do_nothing(
+                index_elements=[Principal.external_subject],
+                index_where=Principal.external_subject.is_not(None),
+            )
+            .returning(Principal.id)
+        )
+        created = (await self._session.execute(statement)).scalar_one_or_none() is not None
+        existing = await self.get_by_subject(external_subject)
+        if existing is None:  # pragma: no cover - the subject row exists after the upsert
+            raise RuntimeError("principal vanished after upsert")
+        return existing, created
+
+    async def list(
+        self,
+        *,
+        type_: PrincipalType | None = None,
+        limit: int,
+        after: tuple[datetime, str] | None = None,
+    ) -> list[PrincipalRecord]:
+        """Principals in creation order; `after` is the `(created_at, id)` of the last item."""
+        statement = select(Principal).order_by(Principal.created_at, Principal.id).limit(limit)
+        if type_ is not None:
+            statement = statement.where(Principal.type == type_)
+        if after is not None:
+            statement = statement.where(tuple_(Principal.created_at, Principal.id) > after)
+        return [_record(row) for row in (await self._session.execute(statement)).scalars()]
+
+
+class GroupRepository:
+    """Groups and memberships."""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def group_ids_for(
+        self, principal_id: str, external_groups: Collection[str] = ()
+    ) -> list[str]:
+        """Ids of the groups a principal belongs to.
+
+        Groups are found by stored membership and by the provider group names carried in the
+        principal's current token (`Group.external_group`).
+        """
+        by_membership = select(GroupMember.group_id).where(GroupMember.principal_id == principal_id)
+        statement: Select[Any] | CompoundSelect[Any] = by_membership
+        if external_groups:
+            statement = by_membership.union(
+                select(Group.id).where(Group.external_group.in_(list(external_groups)))
+            )
+        return sorted(str(item) for item in (await self._session.execute(statement)).scalars())
+
+    async def subject_exists(self, subject_id: str) -> bool:
+        """Whether `subject_id` names a principal or a group (grant subjects)."""
+        principal = await self._session.get(Principal, subject_id)
+        return principal is not None or await self._session.get(Group, subject_id) is not None

lorebase_store/auth/scope.py

@@ -0,0 +1,70 @@
+"""Row-level security scope for auth lookups (see docs/store-schema-notes.md).
+
+Postgres policies read two transaction-local settings: `lorebase.domain_ids` (comma-separated
+Domain ids) and `lorebase.bypass_rls` (`on` for system paths). `rls_scope` sets them for the
+body of the `with` block and puts the previous values back afterwards, so repositories can be
+used inside a longer transaction without widening what later statements see.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+DOMAIN_IDS_SETTING = "lorebase.domain_ids"
+BYPASS_SETTING = "lorebase.bypass_rls"
+
+_SWAP = text(
+    "WITH previous AS MATERIALIZED ("
+    "SELECT coalesce(current_setting(:domains_name, true), '') AS domains, "
+    "coalesce(current_setting(:bypass_name, true), '') AS bypass) "
+    "SELECT previous.domains, previous.bypass, "
+    "set_config(:domains_name, :domains, true), set_config(:bypass_name, :bypass, true) "
+    "FROM previous"
+)
+_RESTORE = text(
+    "SELECT set_config(:domains_name, :domains, true), set_config(:bypass_name, :bypass, true)"
+)
+
+
+def checked_domain_id(domain_id: str) -> str:
+    """`domain_id` when it fits the comma-separated `lorebase.domain_ids` setting.
+
+    Raises `ValueError` for an empty id or one holding a comma, either of which would change
+    which Domains the setting names.
+    """
+    if not domain_id:
+        raise ValueError("Domain ids cannot be empty")
+    if "," in domain_id:
+        raise ValueError("Domain ids cannot contain commas")
+    return domain_id
+
+
+@asynccontextmanager
+async def rls_scope(
+    session: AsyncSession, *, domain_ids: Sequence[str] = (), bypass: bool = False
+) -> AsyncIterator[None]:
+    """Make rows of `domain_ids` (or every row with `bypass`) visible inside the block.
+
+    The settings are transaction-local. When the block raises, they are left as they are:
+    the transaction is expected to roll back. An empty Domain id or one holding a comma raises
+    `ValueError` before anything is set.
+    """
+    domains = ",".join(checked_domain_id(domain_id) for domain_id in domain_ids)
+    names = {"domains_name": DOMAIN_IDS_SETTING, "bypass_name": BYPASS_SETTING}
+    row = (
+        await session.execute(
+            _SWAP, {**names, "domains": domains, "bypass": "on" if bypass else ""}
+        )
+    ).one()
+    yield
+    await session.execute(_RESTORE, {**names, "domains": row.domains, "bypass": row.bypass})
+
+
+def new_id(prefix: str) -> str:
+    """Application-generated id with a type prefix, e.g. `usr_3f2a...`."""
+    return f"{prefix}_{uuid.uuid4().hex}"