pyfect-dev 0.1.0__py3-none-any.whl

pyfect/errors.py

@@ -0,0 +1,321 @@
+"""Typed errors.
+
+Subclass ``TaggedError`` for domain errors. One with fields must be a
+``@dataclass(eq=False)`` (plain ``@dataclass`` works too, but pyright then
+thinks it unhashable); constructing one whose fields nothing sets raises
+``TypeError``. An
+instance is yieldable: ``yield from NotFound(key)`` fails the surrounding
+generator and adds ``NotFound`` to its error channel. Write
+``return (yield from NotFound(key))`` so the type checker knows the code
+after it is unreachable.
+
+The class is the tag: ``catch_tag(NotFound, ...)`` matches by
+``isinstance``, so catching a base class catches its subclasses, and the
+types agree.
+
+Like Effect's ``Data.TaggedError``, errors compare and hash structurally
+(same class, equal fields or ``args``), a ``message`` field is the string
+form, a ``cause`` field holding an exception becomes ``__cause__``, and
+``exit_code`` is the process status ``run_main`` exits with when the error
+ends the program. ``error_reported`` and the ``report_*`` attributes tune
+how ``run_main`` and the error reporters (``pyfect.error_reporter``) treat
+it.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import builtins
+import re
+import sys
+from collections.abc import Callable, Generator, Mapping
+from dataclasses import dataclass, fields, is_dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, ClassVar, Final, Never, Self, TypeIs, get_origin, overload
+
+from pyfect._core import Effect, _FailCause
+from pyfect.cause import Cause, Fail, Interrupt, Reason, fail, from_reasons
+from pyfect.duration import Seconds, format_duration
+from pyfect.result import Err, Ok, Result
+
+if TYPE_CHECKING:
+    from pyfect.logger import Severity
+
+
+def with_cause(message: str, cause: object) -> str:
+    """``message`` and why, for ``str()``: what a log line shows, while ``.message`` stays
+    Effect's text (docs/PARITY.md). A cause whose own message this one repeats replaces it,
+    so a wrapper around its reason says it once."""
+    if cause is None:
+        return message
+    if not isinstance(cause, BaseException):
+        return f"{message}: {cause!r}"
+    detail = str(cause)
+    if detail.startswith(message):
+        return detail
+    said = getattr(cause, "message", None)
+    if isinstance(said, str) and said and said in message:
+        return message.replace(said, detail, 1)
+    if detail and detail in message:
+        return message
+    return f"{message}: {type(cause).__name__}{f': {detail}' if detail else ''}"
+
+
+def _why(error: BaseException) -> object:
+    """What caused ``error``: a ``reason`` that is an error (it tells its own cause), or else
+    its ``__cause__`` or ``cause``."""
+    reason = getattr(error, "reason", None)
+    if isinstance(reason, BaseException):
+        return reason
+    return error.__cause__ if error.__cause__ is not None else getattr(error, "cause", None)
+
+
+class TaggedError(Exception):
+    exit_code: ClassVar[int] = 1
+    error_reported: bool = True
+    """``False``: ``run_main`` does not log this error when it ends the
+    program (Effect's ``Runtime.errorReported``)."""
+    report_ignored: bool = False
+    """``True``: error reporters skip this error."""
+    report_severity: Severity | None = None
+    """The severity error reporters give it (``None``: ``INFO``)."""
+    report_attributes: Mapping[str, object] = MappingProxyType({})
+    """Extra metadata for error reporters."""
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # Put the structural methods in the subclass's own namespace: then
+        # ``@dataclass`` treats them as explicit and neither replaces
+        # ``__eq__`` nor sets ``__hash__ = None``. A class that defines (or
+        # inherits) its own ``__eq__`` or ``__hash__`` keeps it.
+        if cls.__eq__ is TaggedError.__eq__ and cls.__hash__ is TaggedError.__hash__:
+            type.__setattr__(cls, "__eq__", TaggedError.__eq__)
+            type.__setattr__(cls, "__hash__", TaggedError.__hash__)
+        # The bases are finished, so fields no constructor sets fail here; the
+        # class itself may still get ``@dataclass``, so it is checked when
+        # first constructed (``_check_fields_then_new``).
+        _require_dataclass_fields(cls, below=cls)
+        if "__init__" not in cls.__dict__ and _own_fields(cls):
+            type.__setattr__(cls, "__new__", staticmethod(_check_fields_then_new))
+
+    def _structure(self) -> tuple[object, ...]:
+        if is_dataclass(self):
+            return tuple(getattr(self, f.name) for f in fields(self) if f.compare)
+        return self.args
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, TaggedError) or type(other) is not type(self):
+            return NotImplemented
+        return self._structure() == other._structure()
+
+    def __hash__(self) -> int:
+        return hash((type(self), self._structure()))
+
+    def __setattr__(self, name: str, value: object) -> None:
+        super().__setattr__(name, value)
+        if name != "cause":
+            return
+        if isinstance(value, BaseException):
+            self.__cause__ = value
+        elif value is None and self.__cause__ is not None:
+            # Assigning ``__cause__`` also sets ``__suppress_context__``; an
+            # absent cause must not hide the implicit ``__context__``.
+            self.__cause__ = None
+            self.__suppress_context__ = False
+
+    def __iter__(self) -> Generator[Effect[Never, Self, Never], Any, Never]:
+        yield _FailCause(fail(self))
+        raise AssertionError("unreachable: a failed effect never resumes")
+
+    def __str__(self) -> str:
+        message = getattr(self, "message", None)
+        if isinstance(message, str):
+            return with_cause(message, _why(self))
+        if is_dataclass(self):
+            return ", ".join(f"{f.name}={getattr(self, f.name)!r}" for f in fields(self))
+        return super().__str__()
+
+    def __reduce__(self) -> str | tuple[Any, ...]:
+        # A dataclass error's ``args`` need not match its fields, so copy and
+        # pickle rebuild it from the fields instead. The state is the rest
+        # (notes, ...): the constructor sets the fields, which may be frozen.
+        if is_dataclass(self):
+            init = {f.name: getattr(self, f.name) for f in fields(self) if f.init}
+            state = {k: v for k, v in self.__dict__.items() if k not in init}
+            return (_rebuild, (type(self), init), state)
+        return super().__reduce__()
+
+
+def _own_fields(cls: type) -> list[str]:
+    """The instance fields ``cls`` itself annotates: not ``ClassVar`` /
+    ``Final``, dunders or ``TaggedError``'s own attributes."""
+    if sys.version_info >= (3, 14):
+        import annotationlib
+
+        annotations = annotationlib.get_annotations(cls, format=annotationlib.Format.FORWARDREF)
+    else:
+        import inspect
+
+        annotations = inspect.get_annotations(cls)
+    return [
+        name
+        for name, annotation in annotations.items()
+        if not name.startswith("__")
+        and name not in TaggedError.__annotations__
+        and not _CLASS_LEVEL.match(annotation if isinstance(annotation, str) else repr(annotation))
+        and get_origin(annotation) not in (ClassVar, Final)
+        and annotation not in (ClassVar, Final)
+    ]
+
+
+_CLASS_LEVEL = re.compile(r"^(?:typing\.|t\.)?(?:ClassVar|Final)\b")
+
+
+def _require_dataclass_fields(cls: type, *, below: type | None = None) -> None:
+    """Raise ``TypeError`` if a class between ``cls`` and ``TaggedError``
+    (above ``below``, when given) annotates fields that no constructor sets:
+    it is not a dataclass and neither it nor a subclass on the way to ``cls``
+    writes ``__init__``."""
+    handwritten_init = False
+    for klass in cls.__mro__:
+        if klass is TaggedError:
+            return
+        own_dataclass = "__dataclass_fields__" in klass.__dict__
+        if "__init__" in klass.__dict__ and not own_dataclass:
+            handwritten_init = True
+        if own_dataclass or handwritten_init or klass is below:
+            continue
+        names = _own_fields(klass)
+        if names:
+            raise TypeError(
+                f"{klass.__qualname__} declares fields ({', '.join(names)}) but is not a "
+                "dataclass, so nothing sets them; decorate it with @dataclass (or "
+                "@dataclass(eq=False)), or subclass S.TaggedError, which needs no decorator"
+            )
+
+
+def _check_fields_then_new(cls: type[TaggedError], *args: Any, **_kwargs: Any) -> Any:
+    """The ``__new__`` of a class with fields and no ``__init__`` of its own:
+    the first time a class is built, check that ``@dataclass`` set them up.
+    The inherited ``__new__`` gets the positional arguments only, as
+    ``BaseException.__new__`` keeps them (``OSError``'s refuses keywords
+    once a class overrides ``__new__``); ``__init__`` takes them all."""
+    new = cls.__dict__.get("_TaggedError__new")
+    if new is None:
+        _require_dataclass_fields(cls)
+        new = next(
+            own
+            for klass in cls.__mro__
+            if (own := klass.__dict__.get("__new__")) is not None and not _is_hook(own)
+        )
+        type.__setattr__(cls, "_TaggedError__new", new)
+    return new(cls, *args)
+
+
+def _is_hook(value: object) -> bool:
+    return isinstance(value, staticmethod) and value.__func__ is _check_fields_then_new
+
+
+def _rebuild[T](cls: Callable[..., T], init: dict[str, Any]) -> T:
+    return cls(**init)
+
+
+@dataclass
+class TimeoutException(TaggedError, builtins.TimeoutError):
+    """An effect ran longer than its ``timeout`` of ``duration``."""
+
+    duration: Seconds
+
+    def __str__(self) -> str:
+        return f"Operation timed out after '{format_duration(self.duration)}'"
+
+
+class NoSuchElementException(TaggedError, LookupError):
+    """An expected value was missing."""
+
+
+class IllegalArgumentError(TaggedError, ValueError):
+    """An argument outside what an operation accepts, such as an unknown
+    time zone name."""
+
+
+class Done[L = None](TaggedError):
+    """A producer finished normally: no more items will come. ``value`` is
+    what it leaves over (Effect's ``Cause.Done(value)``); a bare ``Done``
+    means ``Done[None]``.
+
+    A queue that can be ended says so in its error type,
+    ``Queue[int, Done]``; its takers fail with ``Done()`` once it drains."""
+
+    __match_args__ = ("value",)
+
+    @overload
+    def __init__(self: Done[None]) -> None: ...
+    @overload
+    def __init__(self, value: L) -> None: ...
+    def __init__(self, value: object = None) -> None:
+        super().__init__(value)
+
+    @property
+    def value(self) -> L:
+        return self.args[0]
+
+    def __repr__(self) -> str:
+        return "Done()" if self.value is None else f"Done({self.value!r})"
+
+    __str__ = __repr__
+
+
+def filter_done[E](cause: Cause[E]) -> Result[Done[Any], Cause[E]]:
+    """``Ok(done)`` if ``cause`` holds a ``Done`` failure and nothing else but
+    interruptions; otherwise ``Err`` of the cause without its ``Done``
+    failures (Effect's ``Pull.filterDone``)."""
+    dones = [r.error for r in cause.reasons if _is_done(r)]
+    if not dones:
+        return Err(cause)
+    if all(_is_done(r) or isinstance(r, Interrupt) for r in cause.reasons):
+        return Ok(dones[0])
+    return Err(from_reasons(r for r in cause.reasons if not _is_done(r)))
+
+
+def _is_done(reason: Reason[object]) -> TypeIs[Fail[Done[Any]]]:
+    return isinstance(reason, Fail) and isinstance(reason.error, Done)
+
+
+@dataclass(eq=False)
+class AsyncFiberError(TaggedError):
+    """``run_sync`` ran an effect that did not finish synchronously. The
+    fiber is left where it stopped."""
+
+    fiber: object
+    message: str = "An asynchronous Effect was executed with Effect.runSync"
+
+
+class ExceededCapacityError(TaggedError):
+    """A bounded structure was asked to hold more than its capacity."""
+
+
+@dataclass(eq=False)
+class UnknownError(TaggedError):
+    """An exception raised by code given to ``try_`` without a ``catch``.
+    ``cause`` is that exception, and also the error's ``__cause__``."""
+
+    cause: Exception
+    message: str | None = None
+
+    def __str__(self) -> str:
+        return str(self.cause) if self.message is None else with_cause(self.message, self.cause)
+
+
+__all__ = [
+    "AsyncFiberError",
+    "Done",
+    "ExceededCapacityError",
+    "IllegalArgumentError",
+    "NoSuchElementException",
+    "TaggedError",
+    "TimeoutException",
+    "UnknownError",
+    "filter_done",
+    "with_cause",
+]

pyfect/eventlog/__init__.py

@@ -0,0 +1,77 @@
+"""Event sourcing with sync (Effect's ``effect/eventlog``).
+
+``event`` and ``event_group`` declare events; ``event_log`` writes them to
+an ``event_journal`` and replays them through handlers; ``event_row``
+makes events that keep table rows. ``event_log_remote`` syncs a log with
+a server (``event_log_server_encrypted`` stores batches it cannot read,
+``event_log_server_unencrypted`` runs the handlers itself), over the RPCs
+of ``event_log_message``, encrypted by ``event_log_encryption`` (the
+``eventlog`` extra, ``cryptography``) and authenticated by
+``event_log_session_auth``. ``sql_event_journal``,
+``sql_event_log_server_encrypted`` and ``sql_event_log_server_unencrypted``
+keep the journal and the server storages in a SQLite or PostgreSQL
+database.
+
+Import it as a submodule (``from pyfect import eventlog``): ``import pyfect``
+does not load it, since its servers load ``pyfect.rpc``.
+
+Payloads, entries and write and change frames are ``encoding.schema_binary``
+frames with Effect's bytes.
+"""
+
+from pyfect.eventlog import (
+    event,
+    event_group,
+    event_journal,
+    event_log,
+    event_log_encryption,
+    event_log_message,
+    event_log_remote,
+    event_log_server,
+    event_log_server_encrypted,
+    event_log_server_unencrypted,
+    event_log_session_auth,
+    event_row,
+    sql_event_journal,
+    sql_event_log_server_encrypted,
+    sql_event_log_server_unencrypted,
+)
+from pyfect.eventlog.event import Event, Write
+from pyfect.eventlog.event_group import EventGroup
+from pyfect.eventlog.event_journal import Entry, EventJournal, EventJournalError, RemoteEntry
+from pyfect.eventlog.event_log import EventLog, Identity, Registry
+from pyfect.eventlog.event_log_encryption import EventLogEncryption
+from pyfect.eventlog.event_log_remote import EventLogRemote, EventLogRemoteError
+from pyfect.eventlog.event_row import EventRow
+
+__all__ = [
+    "Entry",
+    "Event",
+    "EventGroup",
+    "EventJournal",
+    "EventJournalError",
+    "EventLog",
+    "EventLogEncryption",
+    "EventLogRemote",
+    "EventLogRemoteError",
+    "EventRow",
+    "Identity",
+    "Registry",
+    "RemoteEntry",
+    "Write",
+    "event",
+    "event_group",
+    "event_journal",
+    "event_log",
+    "event_log_encryption",
+    "event_log_message",
+    "event_log_remote",
+    "event_log_server",
+    "event_log_server_encrypted",
+    "event_log_server_unencrypted",
+    "event_log_session_auth",
+    "event_row",
+    "sql_event_journal",
+    "sql_event_log_server_encrypted",
+    "sql_event_log_server_unencrypted",
+]

pyfect/eventlog/_conflicts.py

@@ -0,0 +1,94 @@
+"""Which stored entries conflict with a batch of incoming ones (Effect's
+``eventlog/internal/conflicts.ts``): those of the same event and primary
+key with a greater id."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyfect.eventlog.event_journal import Entry, EntryWithConflicts
+
+# Set during client replay only, so it never leaves the process: an
+# attribute outside the entry's fields, so equality and encoding ignore it.
+_ANCHOR = "_eventlog_anchor"
+
+
+@dataclass(frozen=True, slots=True)
+class _Anchor:
+    entry: Entry
+    index: int
+
+
+def set_anchor(entry: Entry, source: Entry, index: int) -> None:
+    """Order and conflict-check ``entry`` as ``source``, after the
+    ``index`` outputs written for it before."""
+    object.__setattr__(entry, _ANCHOR, _Anchor(source, index))
+
+
+def anchor_entry(entry: Entry) -> Entry:
+    anchor: _Anchor | None = getattr(entry, _ANCHOR, None)
+    return entry if anchor is None else anchor.entry
+
+
+def _anchor_key(entry: Entry) -> tuple[bytes, int]:
+    # By anchor id, then by write order among one anchor's outputs.
+    anchor: _Anchor | None = getattr(entry, _ANCHOR, None)
+    return (entry.id, 0) if anchor is None else (anchor.entry.id, anchor.index)
+
+
+@dataclass(slots=True)
+class ConflictGroup:
+    event: str
+    primary_key: str
+    oldest: Entry
+    entries: list[Entry] = field(default_factory=list["Entry"])
+
+
+class ConflictIndex:
+    """A batch, ordered by anchor, and the stored entries of its keys."""
+
+    __slots__ = ("_stored", "batch", "oldest", "oldest_millis")
+
+    def __init__(self, batch: Sequence[Entry]) -> None:
+        self.batch = sorted(batch, key=_anchor_key)
+        self.oldest = anchor_entry(self.batch[0])
+        self.oldest_millis = self.oldest.created_at_millis
+        self._stored: dict[str, dict[str, ConflictGroup]] = {}
+        for entry in self.batch:
+            by_key = self._stored.setdefault(entry.event, {})
+            if entry.primary_key not in by_key:
+                by_key[entry.primary_key] = ConflictGroup(
+                    entry.event, entry.primary_key, anchor_entry(entry)
+                )
+
+    @property
+    def events(self) -> list[str]:
+        return list(self._stored)
+
+    def groups(self) -> Iterator[ConflictGroup]:
+        for by_key in self._stored.values():
+            yield from by_key.values()
+
+    def add(self, entry: Entry) -> None:
+        """Record a stored entry (ignored unless the batch has its key)."""
+        group = self._stored.get(entry.event, {}).get(entry.primary_key)
+        if group is not None:
+            group.entries.append(entry)
+
+    def to_batch(self) -> list[EntryWithConflicts]:
+        from pyfect.eventlog.event_journal import EntryWithConflicts
+
+        for group in self.groups():
+            group.entries.sort(key=lambda entry: entry.id)
+        result: list[EntryWithConflicts] = []
+        for entry in self.batch:
+            anchor = anchor_entry(entry).id
+            stored = self._stored[entry.event][entry.primary_key].entries
+            result.append(EntryWithConflicts(entry, tuple(s for s in stored if s.id > anchor)))
+        return result
+
+
+__all__ = ["ConflictGroup", "ConflictIndex", "anchor_entry", "set_anchor"]

pyfect/eventlog/_crypto.py

@@ -0,0 +1,64 @@
+"""AES-GCM and Ed25519 on the ``cryptography`` package (the extra
+``pyfect-dev[eventlog]``), where Effect uses WebCrypto. Imported by the
+functions that need it, so the rest of ``pyfect.eventlog`` works without
+the extra."""
+
+from __future__ import annotations
+
+from pyfect._extras import missing_extra
+
+try:
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+        Ed25519PrivateKey,
+        Ed25519PublicKey,
+    )
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+except ImportError as error:  # pragma: no cover - depends on the environment
+    raise missing_extra("pyfect.eventlog encryption and session auth", "eventlog") from error
+
+
+def ed25519_public_key(seed: bytes) -> bytes:
+    """The raw public key of the private key ``seed``."""
+    public = Ed25519PrivateKey.from_private_bytes(seed).public_key()
+    return public.public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+
+
+def ed25519_sign(pkcs8: bytes, payload: bytes) -> bytes:
+    """``payload`` signed with a PKCS#8 private key; ``ValueError`` when
+    the key is not an Ed25519 key."""
+    key = serialization.load_der_private_key(pkcs8, None)
+    if not isinstance(key, Ed25519PrivateKey):
+        raise ValueError("not an Ed25519 private key")
+    return key.sign(payload)
+
+
+def ed25519_verify(public_key: bytes, signature: bytes, payload: bytes) -> bool:
+    """Whether ``signature`` signs ``payload`` for the raw ``public_key``."""
+    key = Ed25519PublicKey.from_public_bytes(public_key)
+    try:
+        key.verify(signature, payload)
+    except InvalidSignature:
+        return False
+    return True
+
+
+def aes_gcm_encrypt(key: bytes, iv: bytes, data: bytes, additional_data: bytes) -> bytes:
+    """The ciphertext followed by its 128-bit tag, as WebCrypto's."""
+    return AESGCM(key).encrypt(iv, data, additional_data)
+
+
+def aes_gcm_decrypt(key: bytes, iv: bytes, data: bytes, additional_data: bytes) -> bytes:
+    """The plaintext; ``cryptography.exceptions.InvalidTag`` when ``data``
+    was altered or the key, iv or additional data differ."""
+    return AESGCM(key).decrypt(iv, data, additional_data)
+
+
+__all__ = [
+    "aes_gcm_decrypt",
+    "aes_gcm_encrypt",
+    "ed25519_public_key",
+    "ed25519_sign",
+    "ed25519_verify",
+]

pyfect/eventlog/_identity.py

@@ -0,0 +1,26 @@
+"""The identity an event log writes as (Effect's ``EventLog.Identity``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pyfect.context import Tag
+from pyfect.redacted import Redacted
+
+
+@dataclass(frozen=True, eq=False)
+class IdentityService:
+    """A public key naming the identity and the private root secret its
+    encryption and signing keys are derived from. Compared by identity,
+    so derived keys are memoized per instance."""
+
+    public_key: str
+    private_key: Redacted[bytes]
+
+
+class Identity(Tag[IdentityService], key="effect/eventlog/EventLog/Identity"):
+    """The identity of the event log, or of the client a server handler
+    serves."""
+
+
+__all__ = ["Identity", "IdentityService"]

pyfect/eventlog/_identity_derivation.py

@@ -0,0 +1,79 @@
+"""Keys derived from an identity's root secret (Effect's
+``eventlog/internal/identityRootSecretDerivation.ts``): SHA-256 of a
+versioned, domain-separated label, a zero byte and the secret gives the
+AES-GCM key and the Ed25519 seed."""
+
+from __future__ import annotations
+
+import hashlib
+import weakref
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from pyfect._core import Effect
+from pyfect._js import text_encode
+from pyfect.effect import sync
+from pyfect.eventlog._identity import IdentityService
+from pyfect.redacted import Redacted
+from pyfect.redacted import make as redacted
+from pyfect.redacted import value as reveal
+
+ED25519_PUBLIC_KEY_LENGTH = 32
+ED25519_PKCS8_SEED_PREFIX = bytes.fromhex("302e020100300506032b657004220420")
+ENCRYPTION_DERIVATION_LABEL_V1 = "effect/eventlog/identity/v1/encryption"
+SIGNING_DERIVATION_LABEL_V1 = "effect/eventlog/identity/v1/signing"
+
+
+@dataclass(frozen=True, slots=True)
+class IdentityRootSecretMaterial:
+    """The AES-GCM key bytes and the Ed25519 key pair (the private key as PKCS#8
+    bytes) of an identity."""
+
+    encryption_key_material: bytes
+    signing_public_key: bytes
+    signing_private_key: Redacted[bytes]
+
+
+def derive_secret_bytes(root_secret: bytes, label: str) -> bytes:
+    return hashlib.sha256(text_encode(label) + b"\x00" + root_secret).digest()
+
+
+def derive_identity_root_secret_material(root_secret: bytes) -> IdentityRootSecretMaterial:
+    from pyfect.eventlog import _crypto
+
+    encryption_key = derive_secret_bytes(root_secret, ENCRYPTION_DERIVATION_LABEL_V1)
+    seed = derive_secret_bytes(root_secret, SIGNING_DERIVATION_LABEL_V1)
+    public_key = _crypto.ed25519_public_key(seed)
+    return IdentityRootSecretMaterial(
+        encryption_key, public_key, redacted(ED25519_PKCS8_SEED_PREFIX + seed)
+    )
+
+
+type GetMaterial = Callable[[IdentityService], Effect[IdentityRootSecretMaterial]]
+
+
+def make_get_identity_root_secret_material() -> GetMaterial:
+    """The material of an identity, derived once per identity instance."""
+    cache: weakref.WeakKeyDictionary[IdentityService, IdentityRootSecretMaterial] = (
+        weakref.WeakKeyDictionary()
+    )
+
+    def get(identity: IdentityService) -> IdentityRootSecretMaterial:
+        found = cache.get(identity)
+        if found is None:
+            found = cache[identity] = derive_identity_root_secret_material(
+                reveal(identity.private_key)
+            )
+        return found
+
+    return lambda identity: sync(lambda: get(identity))
+
+
+__all__ = [
+    "ENCRYPTION_DERIVATION_LABEL_V1",
+    "SIGNING_DERIVATION_LABEL_V1",
+    "IdentityRootSecretMaterial",
+    "derive_identity_root_secret_material",
+    "derive_secret_bytes",
+    "make_get_identity_root_secret_material",
+]