ithuriel 0.5.2__py3-none-any.whl

ithuriel/__init__.py

@@ -0,0 +1,93 @@
+"""Vendor-neutral reference implementation of ITHURIEL/1."""
+
+from .acceptance import AcceptanceStore, AcceptedRecord, AdmissionReservation
+from .api import create_signal, send_signal, verify_signal
+from .crypto import generate_keypair, key_id, load_private, public_record
+from .enrollment import EnrollmentInvite, EnrollmentRequest, EnrollmentStore, create_enrollment_request, create_enrollment_server
+from .federation import RelayDiscovery, discover_relay, discovery_url, recipient_domain
+from .envelope import CanonicalRef, IthurielEnvelope, digest_file
+from .errors import ResolveError, TransportError, ValidationError, VerificationError, IthurielError
+from .replay import ReplayGuard
+from .relay import RelayConfig, RelayStore, create_relay_server, relay_send, token_digest
+from .resolver import (
+    DEFAULT_MAX_CANONICAL_BYTES,
+    ResolverRegistry,
+    command_resolver,
+    default_resolvers,
+    http_resolver,
+    local_resolvers,
+    restricted_file_resolver,
+    restricted_http_resolver,
+    unsafe_file_resolver,
+)
+from .snapshot import VerifiedSnapshot
+from .transport import TransportRegistry, default_transports
+from .trust import JsonTrustStore, MappingTrustStore, SqliteTrustStore, TrustStore, TrustedKey, load_trust
+from .verify import (
+    SignatureInspectionResult,
+    VerificationPolicy,
+    VerificationResult,
+    inspect_envelope_signature,
+    verify_envelope,
+)
+
+from ._version import __version__
+
+__all__ = [
+    "AcceptanceStore",
+    "AcceptedRecord",
+    "AdmissionReservation",
+    "CanonicalRef",
+    "DEFAULT_MAX_CANONICAL_BYTES",
+    "EnrollmentInvite",
+    "EnrollmentRequest",
+    "EnrollmentStore",
+    "JsonTrustStore",
+    "MappingTrustStore",
+    "ReplayGuard",
+    "RelayConfig",
+    "RelayDiscovery",
+    "RelayStore",
+    "ResolveError",
+    "ResolverRegistry",
+    "SignatureInspectionResult",
+    "SqliteTrustStore",
+    "TransportError",
+    "TransportRegistry",
+    "TrustStore",
+    "TrustedKey",
+    "ValidationError",
+    "VerificationError",
+    "VerificationPolicy",
+    "VerificationResult",
+    "VerifiedSnapshot",
+    "IthurielEnvelope",
+    "IthurielError",
+    "command_resolver",
+    "create_enrollment_request",
+    "create_enrollment_server",
+    "create_relay_server",
+    "create_signal",
+    "default_resolvers",
+    "default_transports",
+    "digest_file",
+    "discover_relay",
+    "discovery_url",
+    "generate_keypair",
+    "http_resolver",
+    "inspect_envelope_signature",
+    "key_id",
+    "load_private",
+    "load_trust",
+    "local_resolvers",
+    "public_record",
+    "recipient_domain",
+    "relay_send",
+    "send_signal",
+    "token_digest",
+    "verify_envelope",
+    "verify_signal",
+    "restricted_file_resolver",
+    "restricted_http_resolver",
+    "unsafe_file_resolver",
+]

ithuriel/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the distribution and wire user-agent version."""
+
+__version__ = "0.5.2"

ithuriel/acceptance.py

@@ -0,0 +1,436 @@
+from __future__ import annotations
+
+import sqlite3
+import threading
+from dataclasses import dataclass
+from datetime import timedelta
+from pathlib import Path
+from typing import Any
+
+from .envelope import IthurielEnvelope
+from .errors import VerificationError
+from .snapshot import VerifiedSnapshot
+from .util import epoch_microseconds, rfc3339, sha256_digest, utc_now
+
+
+@dataclass(frozen=True)
+class AcceptedRecord:
+    status: str
+    envelope_id: str
+    nonce: str
+    packet_fingerprint: str
+    canonical_digest: str
+    canonical_uri: str
+    accepted_at: str
+    envelope_json: bytes
+    canonical_bytes: bytes
+    expires_at: str | None = None
+    consumed_at: str | None = None
+
+
+class AdmissionReservation:
+    """In-memory logical-payload and record reservation held during resolution."""
+
+    def __init__(self, store: "AcceptanceStore", bytes_reserved: int, records_reserved: int = 1):
+        self._store = store
+        self.bytes_reserved = bytes_reserved
+        self.records_reserved = records_reserved
+        self._active = True
+
+    def release(self) -> None:
+        self._store._release_reservation(self)
+
+    def __enter__(self) -> "AdmissionReservation":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.release()
+
+
+class AcceptanceStore:
+    """Durable receipt identity plus separately purged payload bytes.
+
+    ``max_total_bytes`` is logical payload accounting for retained envelope and
+    canonical bytes. It is not a physical disk quota: SQLite WAL files, indexes,
+    logs, temporary files, and SQLite maintenance require separate deployment
+    limits.
+    """
+
+    SCHEMA_VERSION = 2
+
+    def __init__(self, path: Path, *, max_records: int = 10_000, max_tombstones: int = 100_000):
+        if max_records <= 0 or max_tombstones <= 0:
+            raise ValueError("record and tombstone limits must be positive")
+        self.path = path
+        self.max_records = max_records
+        self.max_tombstones = max_tombstones
+        self.lock = threading.RLock()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.conn = sqlite3.connect(path, check_same_thread=False, isolation_level=None)
+        self.conn.execute("PRAGMA journal_mode=WAL")
+        self.conn.execute("PRAGMA synchronous=FULL")
+        self._reserved_bytes = 0
+        self._reserved_records = 0
+        self._migrate_or_initialize()
+
+    @staticmethod
+    def _table_exists(conn: sqlite3.Connection, name: str) -> bool:
+        return conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", (name,)
+        ).fetchone() is not None
+
+    @classmethod
+    def _create_schema_locked(cls, conn: sqlite3.Connection) -> None:
+        conn.execute(
+            "CREATE TABLE receipt_identity ("
+            "nonce TEXT PRIMARY KEY, envelope_id TEXT UNIQUE NOT NULL, packet_fingerprint TEXT NOT NULL, "
+            "expires_at TEXT NOT NULL, expires_at_us INTEGER NOT NULL, "
+            "accepted_at TEXT NOT NULL, accepted_at_us INTEGER NOT NULL, "
+            "status TEXT NOT NULL CHECK(status IN ('pending','consumed','purged')), "
+            "consumed_at TEXT, consumed_at_us INTEGER, canonical_digest TEXT NOT NULL, canonical_uri TEXT NOT NULL)"
+        )
+        conn.execute(
+            "CREATE TABLE receipt_payload ("
+            "nonce TEXT PRIMARY KEY, envelope_json BLOB NOT NULL, canonical_bytes BLOB NOT NULL, "
+            "FOREIGN KEY(nonce) REFERENCES receipt_identity(nonce) ON DELETE CASCADE)"
+        )
+        conn.execute("CREATE INDEX receipt_identity_expires_idx ON receipt_identity(expires_at_us)")
+        conn.execute("CREATE INDEX receipt_identity_consumed_idx ON receipt_identity(consumed_at_us)")
+
+    @staticmethod
+    def _timestamp(value: str | None, *, field: str) -> tuple[str | None, int | None]:
+        if value is None:
+            return None, None
+        try:
+            return value, epoch_microseconds(value)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"invalid {field} timestamp during acceptance migration") from exc
+
+    def _migrate_or_initialize(self) -> None:
+        with self.lock:
+            self.conn.execute("BEGIN IMMEDIATE")
+            try:
+                has_new = self._table_exists(self.conn, "receipt_identity")
+                has_payload = self._table_exists(self.conn, "receipt_payload")
+                if has_new != has_payload:
+                    raise ValueError("incomplete acceptance schema")
+                if has_new:
+                    required = {
+                        "nonce", "envelope_id", "packet_fingerprint", "expires_at", "expires_at_us",
+                        "accepted_at", "accepted_at_us", "status", "consumed_at", "consumed_at_us",
+                        "canonical_digest", "canonical_uri",
+                    }
+                    actual = {row[1] for row in self.conn.execute("PRAGMA table_info(receipt_identity)")}
+                    payload_actual = {row[1] for row in self.conn.execute("PRAGMA table_info(receipt_payload)")}
+                    if required - actual or {"nonce", "envelope_json", "canonical_bytes"} - payload_actual:
+                        raise ValueError("unsupported acceptance schema")
+                else:
+                    self._migrate_legacy_locked()
+                self.conn.execute(f"PRAGMA user_version = {self.SCHEMA_VERSION}")
+                self.conn.execute("COMMIT")
+            except Exception:
+                if self.conn.in_transaction:
+                    self.conn.execute("ROLLBACK")
+                raise
+
+    def _migrate_legacy_locked(self) -> None:
+        legacy_rows: list[tuple[str, tuple[Any, ...], bool]] = []
+        if self._table_exists(self.conn, "accepted"):
+            columns = {row[1] for row in self.conn.execute("PRAGMA table_info(accepted)")}
+            required = {
+                "nonce", "envelope_id", "packet_fingerprint", "expires_at", "accepted_at",
+                "canonical_digest", "canonical_uri", "envelope_json", "canonical_bytes",
+            }
+            if required - columns:
+                raise ValueError("accepted table is missing migration columns")
+            query = (
+                "SELECT nonce, envelope_id, packet_fingerprint, expires_at, accepted_at, "
+                + ("status, " if "status" in columns else "'pending', ")
+                + ("consumed_at, " if "consumed_at" in columns else "NULL, ")
+                + "canonical_digest, canonical_uri, envelope_json, canonical_bytes FROM accepted"
+            )
+            for row in self.conn.execute(query):
+                legacy_rows.append(("accepted", row, True))
+        if self._table_exists(self.conn, "accepted_tombstones"):
+            columns = {row[1] for row in self.conn.execute("PRAGMA table_info(accepted_tombstones)")}
+            required = {
+                "nonce", "envelope_id", "packet_fingerprint", "expires_at", "accepted_at",
+                "canonical_digest", "canonical_uri",
+            }
+            if required - columns:
+                raise ValueError("accepted_tombstones table is missing migration columns")
+            query = (
+                "SELECT nonce, envelope_id, packet_fingerprint, expires_at, accepted_at, "
+                + ("consumed_at, " if "consumed_at" in columns else "NULL, ")
+                + "canonical_digest, canonical_uri FROM accepted_tombstones"
+            )
+            for row in self.conn.execute(query):
+                legacy_rows.append(("tombstone", row, False))
+
+        self._create_schema_locked(self.conn)
+        seen_nonces: set[str] = set()
+        seen_ids: set[str] = set()
+        for _source, row, has_payload in legacy_rows:
+            if has_payload:
+                (
+                    nonce, envelope_id, fingerprint, expires_at, accepted_at, status,
+                    consumed_at, digest, uri, envelope_json, canonical_bytes,
+                ) = row
+            else:
+                nonce, envelope_id, fingerprint, expires_at, accepted_at, consumed_at, digest, uri = row
+                status = "purged"
+                envelope_json = None
+                canonical_bytes = None
+            if nonce in seen_nonces or envelope_id in seen_ids:
+                raise ValueError("conflicting duplicate acceptance identity during migration")
+            if not all(isinstance(value, str) and value for value in (nonce, envelope_id, fingerprint, expires_at, accepted_at, digest, uri)):
+                raise ValueError("invalid acceptance identity during migration")
+            if status not in {"pending", "consumed", "purged"}:
+                raise ValueError("invalid acceptance lifecycle state during migration")
+            expires_text, expires_us = self._timestamp(expires_at, field="expires_at")
+            accepted_text, accepted_us = self._timestamp(accepted_at, field="accepted_at")
+            consumed_text, consumed_us = self._timestamp(consumed_at, field="consumed_at")
+            self.conn.execute(
+                "INSERT INTO receipt_identity(nonce, envelope_id, packet_fingerprint, expires_at, expires_at_us, "
+                "accepted_at, accepted_at_us, status, consumed_at, consumed_at_us, canonical_digest, canonical_uri) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    nonce, envelope_id, fingerprint, expires_text, expires_us,
+                    accepted_text, accepted_us, status, consumed_text, consumed_us, digest, uri,
+                ),
+            )
+            if has_payload:
+                if envelope_json is None or canonical_bytes is None:
+                    raise ValueError("accepted payload is null during migration")
+                self.conn.execute(
+                    "INSERT INTO receipt_payload(nonce, envelope_json, canonical_bytes) VALUES (?, ?, ?)",
+                    (nonce, bytes(envelope_json), bytes(canonical_bytes)),
+                )
+            seen_nonces.add(nonce)
+            seen_ids.add(envelope_id)
+        if self._table_exists(self.conn, "accepted"):
+            self.conn.execute("DROP TABLE accepted")
+        if self._table_exists(self.conn, "accepted_tombstones"):
+            self.conn.execute("DROP TABLE accepted_tombstones")
+
+    @staticmethod
+    def _record(row: tuple[Any, ...]) -> AcceptedRecord:
+        return AcceptedRecord(
+            status=row[0], envelope_id=row[1], nonce=row[2], packet_fingerprint=row[3],
+            canonical_digest=row[4], canonical_uri=row[5], accepted_at=row[6],
+            envelope_json=b"" if row[7] is None else bytes(row[7]),
+            canonical_bytes=b"" if row[8] is None else bytes(row[8]),
+            expires_at=row[9], consumed_at=row[10],
+        )
+
+    def _select_base(self, suffix: str, value: str) -> tuple[Any, ...] | None:
+        if suffix not in {"nonce", "envelope_id"}:
+            raise ValueError("invalid acceptance lookup column")
+        return self.conn.execute(
+            "SELECT i.status, i.envelope_id, i.nonce, i.packet_fingerprint, i.canonical_digest, i.canonical_uri, "
+            "i.accepted_at, p.envelope_json, p.canonical_bytes, i.expires_at, i.consumed_at "
+            "FROM receipt_identity i LEFT JOIN receipt_payload p ON p.nonce = i.nonce "
+            f"WHERE i.{suffix} = ?",
+            (value,),
+        ).fetchone()
+
+    def _lookup_locked(self, nonce: str) -> AcceptedRecord | None:
+        row = self._select_base("nonce", nonce)
+        return None if row is None else self._record(row)
+
+    def lookup(self, nonce: str) -> AcceptedRecord | None:
+        with self.lock:
+            return self._lookup_locked(nonce)
+
+    def reserve(self, *, max_total_bytes: int, bytes_reserved: int) -> AdmissionReservation:
+        if max_total_bytes <= 0 or bytes_reserved <= 0:
+            raise ValueError("capacity and reservation must be positive")
+        with self.lock:
+            current = self.conn.execute(
+                "SELECT coalesce(sum(length(p.envelope_json) + length(p.canonical_bytes)), 0) "
+                "FROM receipt_payload p JOIN receipt_identity i ON i.nonce = p.nonce WHERE i.status != 'purged'"
+            ).fetchone()[0]
+            retained = self.conn.execute(
+                "SELECT count(*) FROM receipt_identity WHERE status != 'purged'"
+            ).fetchone()[0]
+            if current + self._reserved_bytes + bytes_reserved > max_total_bytes:
+                raise VerificationError("accepted inbox capacity exceeded", code="inbox-capacity-exceeded")
+            if retained + self._reserved_records + 1 > self.max_records:
+                raise VerificationError("accepted inbox record limit exceeded", code="inbox-record-limit-exceeded")
+            self._reserved_bytes += bytes_reserved
+            self._reserved_records += 1
+            return AdmissionReservation(self, bytes_reserved)
+
+    def _release_reservation(self, reservation: AdmissionReservation) -> None:
+        with self.lock:
+            if reservation._store is not self:
+                raise ValueError("reservation belongs to another acceptance store")
+            if not reservation._active:
+                return
+            if reservation.bytes_reserved > self._reserved_bytes or reservation.records_reserved > self._reserved_records:
+                raise RuntimeError("acceptance reservation accounting invariant violated")
+            self._reserved_bytes -= reservation.bytes_reserved
+            self._reserved_records -= reservation.records_reserved
+            reservation._active = False
+
+    def accept(
+        self,
+        env: IthurielEnvelope,
+        snapshot: VerifiedSnapshot,
+        *,
+        max_total_bytes: int | None = None,
+        reservation: AdmissionReservation | None = None,
+        max_records: int | None = None,
+    ) -> AcceptedRecord:
+        env.validate()
+        if snapshot.uri != env.canonical.uri or snapshot.digest != env.canonical.digest:
+            raise VerificationError("snapshot does not match envelope canonical reference", code="snapshot-envelope-mismatch")
+        if sha256_digest(snapshot.content) != env.canonical.digest:
+            raise VerificationError("snapshot bytes do not match envelope digest", code="snapshot-envelope-mismatch")
+        fingerprint = env.packet_fingerprint()
+        envelope_json = env.dumps().encode("utf-8")
+        accepted_at = rfc3339(utc_now())
+        accepted_at_us = epoch_microseconds(accepted_at)
+        record_limit = self.max_records if max_records is None else max_records
+        if record_limit <= 0:
+            raise ValueError("max_records must be positive")
+        with self.lock:
+            self.conn.execute("BEGIN IMMEDIATE")
+            try:
+                prior = self._lookup_locked(env.nonce)
+                if prior is None:
+                    existing_id = self._select_base("envelope_id", env.id)
+                    if existing_id is not None:
+                        raise VerificationError("envelope id was previously used by a different packet", code="envelope-id-conflict")
+                if prior is not None:
+                    if prior.envelope_id != env.id or prior.packet_fingerprint != fingerprint:
+                        raise VerificationError("nonce was previously used by a different packet", code="nonce-conflict")
+                    self.conn.execute("COMMIT")
+                    return AcceptedRecord(
+                        status="purged" if prior.status == "purged" else "already_accepted",
+                        envelope_id=prior.envelope_id,
+                        nonce=prior.nonce,
+                        packet_fingerprint=prior.packet_fingerprint,
+                        canonical_digest=prior.canonical_digest,
+                        canonical_uri=prior.canonical_uri,
+                        accepted_at=prior.accepted_at,
+                        envelope_json=prior.envelope_json,
+                        canonical_bytes=prior.canonical_bytes,
+                        expires_at=prior.expires_at,
+                        consumed_at=prior.consumed_at,
+                    )
+                if max_total_bytes is not None:
+                    if max_total_bytes <= 0:
+                        raise ValueError("max_total_bytes must be positive")
+                    current = self.conn.execute(
+                        "SELECT coalesce(sum(length(p.envelope_json) + length(p.canonical_bytes)), 0) "
+                        "FROM receipt_payload p JOIN receipt_identity i ON i.nonce = p.nonce WHERE i.status != 'purged'"
+                    ).fetchone()[0]
+                    reserved_other = self._reserved_bytes
+                    reserved_records_other = self._reserved_records
+                    if reservation is not None and reservation._store is self and reservation._active:
+                        reserved_other -= reservation.bytes_reserved
+                        reserved_records_other -= reservation.records_reserved
+                    if current + reserved_other + len(envelope_json) + len(snapshot.content) > max_total_bytes:
+                        raise VerificationError("accepted inbox capacity exceeded", code="inbox-capacity-exceeded")
+                retained = self.conn.execute(
+                    "SELECT count(*) FROM receipt_identity WHERE status != 'purged'"
+                ).fetchone()[0]
+                reserved_records_other = self._reserved_records
+                if reservation is not None and reservation._store is self and reservation._active:
+                    reserved_records_other -= reservation.records_reserved
+                if retained + reserved_records_other + 1 > record_limit:
+                    raise VerificationError("accepted inbox record limit exceeded", code="inbox-record-limit-exceeded")
+
+                self.conn.execute(
+                    "INSERT INTO receipt_identity(nonce, envelope_id, packet_fingerprint, expires_at, expires_at_us, "
+                    "accepted_at, accepted_at_us, status, canonical_digest, canonical_uri) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)",
+                    (
+                        env.nonce, env.id, fingerprint, env.expires_at, epoch_microseconds(env.expires_at),
+                        accepted_at, accepted_at_us, snapshot.digest, snapshot.uri,
+                    ),
+                )
+                self.conn.execute(
+                    "INSERT INTO receipt_payload(nonce, envelope_json, canonical_bytes) VALUES (?, ?, ?)",
+                    (env.nonce, envelope_json, snapshot.content),
+                )
+                self.conn.execute("COMMIT")
+                return AcceptedRecord(
+                    status="accepted", envelope_id=env.id, nonce=env.nonce, packet_fingerprint=fingerprint,
+                    canonical_digest=snapshot.digest, canonical_uri=snapshot.uri, accepted_at=accepted_at,
+                    envelope_json=envelope_json, canonical_bytes=snapshot.content, expires_at=env.expires_at,
+                )
+            except Exception:
+                if self.conn.in_transaction:
+                    self.conn.execute("ROLLBACK")
+                raise
+
+    def get_by_id(self, envelope_id: str) -> AcceptedRecord | None:
+        with self.lock:
+            row = self._select_base("envelope_id", envelope_id)
+            return None if row is None else self._record(row)
+
+    def list_metadata(self, limit: int = 100) -> list[dict[str, Any]]:
+        if limit <= 0:
+            raise ValueError("limit must be positive")
+        with self.lock:
+            rows = self.conn.execute(
+                "SELECT i.envelope_id, i.nonce, i.status, i.canonical_digest, i.canonical_uri, i.accepted_at, "
+                "i.expires_at, i.consumed_at, length(p.canonical_bytes) "
+                "FROM receipt_identity i LEFT JOIN receipt_payload p ON p.nonce = i.nonce "
+                "WHERE i.status != 'purged' ORDER BY i.accepted_at_us DESC LIMIT ?", (limit,)
+            ).fetchall()
+        return [
+            {
+                "envelope_id": row[0], "nonce": row[1], "status": row[2], "canonical_digest": row[3],
+                "canonical_uri": row[4], "accepted_at": row[5], "expires_at": row[6],
+                "consumed_at": row[7], "canonical_bytes": row[8] or 0,
+            }
+            for row in rows
+        ]
+
+    def mark_consumed(self, envelope_id: str) -> bool:
+        consumed_at = rfc3339(utc_now())
+        with self.lock:
+            cur = self.conn.execute(
+                "UPDATE receipt_identity SET status = 'consumed', consumed_at = ?, consumed_at_us = ? "
+                "WHERE envelope_id = ? AND status = 'pending'",
+                (consumed_at, epoch_microseconds(consumed_at), envelope_id),
+            )
+            return cur.rowcount > 0
+
+    def gc(self, *, retain_seconds: int = 86_400, limit: int = 1000) -> int:
+        """Purge payloads while retaining every receipt identity for replay/conflict checks."""
+        if retain_seconds < 0 or limit <= 0:
+            raise ValueError("retain_seconds must be non-negative and limit must be positive")
+        now = utc_now()
+        now_us = epoch_microseconds(now)
+        cutoff_us = epoch_microseconds(now - timedelta(seconds=retain_seconds))
+        with self.lock:
+            self.conn.execute("BEGIN IMMEDIATE")
+            try:
+                tombstones = self.conn.execute(
+                    "SELECT count(*) FROM receipt_identity WHERE status = 'purged'"
+                ).fetchone()[0]
+                if tombstones >= self.max_tombstones:
+                    raise VerificationError("acceptance tombstone limit exceeded", code="tombstone-limit-exceeded")
+                rows = self.conn.execute(
+                    "SELECT nonce FROM receipt_identity WHERE status != 'purged' AND "
+                    "(expires_at_us <= ? OR (status = 'consumed' AND consumed_at_us <= ?)) "
+                    "ORDER BY accepted_at_us ASC LIMIT ?",
+                    (now_us, cutoff_us, min(limit, self.max_tombstones - tombstones)),
+                ).fetchall()
+                for (nonce,) in rows:
+                    self.conn.execute("DELETE FROM receipt_payload WHERE nonce = ?", (nonce,))
+                    self.conn.execute("UPDATE receipt_identity SET status = 'purged' WHERE nonce = ?", (nonce,))
+                self.conn.execute("COMMIT")
+                return len(rows)
+            except Exception:
+                if self.conn.in_transaction:
+                    self.conn.execute("ROLLBACK")
+                raise
+
+    def close(self) -> None:
+        with self.lock:
+            self.conn.close()

ithuriel/api.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Mapping
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from .envelope import IthurielEnvelope
+from .replay import ReplayGuard
+from .resolver import ResolverRegistry, default_resolvers
+from .transport import TransportRegistry, default_transports
+from .trust import TrustStore
+from .util import sha256_digest
+from .verify import VerificationPolicy, VerificationResult, verify_envelope
+
+
+def create_signal(
+    *,
+    sender: str,
+    recipient: str,
+    kind: str,
+    object_id: str,
+    canonical_uri: str,
+    private_key: Ed25519PrivateKey,
+    canonical_digest: str | None = None,
+    ttl_seconds: int = 600,
+    resolvers: ResolverRegistry | None = None,
+    max_canonical_bytes: int = 8 * 1024 * 1024,
+) -> IthurielEnvelope:
+    """Create a signed ITHURIEL signal.
+
+    If canonical_digest is omitted, callers must explicitly supply a resolver
+    registry. The core never implicitly grants file/network/plugin access.
+    """
+    if canonical_digest is None:
+        if resolvers is None:
+            raise ValueError("canonical_digest or an explicit resolver registry is required")
+        content = resolvers.resolve(canonical_uri, max_bytes=max_canonical_bytes)
+        canonical_digest = sha256_digest(content)
+    return IthurielEnvelope.create(
+        sender=sender,
+        recipient=recipient,
+        kind=kind,
+        object_id=object_id,
+        uri=canonical_uri,
+        digest=canonical_digest,
+        private_key=private_key,
+        ttl_seconds=ttl_seconds,
+    )
+
+
+def verify_signal(
+    envelope: IthurielEnvelope,
+    *,
+    trust: TrustStore | Mapping[str, object],
+    policy: VerificationPolicy,
+    replay_guard: ReplayGuard | None = None,
+    resolvers: ResolverRegistry | None = None,
+) -> VerificationResult:
+    return verify_envelope(
+        envelope,
+        trust=trust,
+        policy=policy,
+        replay_guard=replay_guard,
+        resolvers=resolvers,
+    )
+
+
+def send_signal(
+    envelope: IthurielEnvelope,
+    endpoint: str,
+    *,
+    transports: TransportRegistry | None = None,
+    timeout: float = 15.0,
+) -> bytes:
+    payload = envelope.dumps().encode("utf-8")
+    return (transports or default_transports()).send(endpoint, payload, timeout)