utic-invocation-settings 0.1.0__py3-none-any.whl

utic_invocation_settings/__init__.py

@@ -0,0 +1,78 @@
+"""utic-invocation-settings — consume encrypted Unstructured plugin invocation settings.
+
+Public, self-contained on ``cryptography`` + ``pydantic``. Reads the v1 envelope defined in
+cellular-dataplane/docs/envelope-contract-v1.md: RSA-OAEP-256-wrapped AES-256-GCM, with
+authenticated caching, decrypting inside the plugin at invoke time.
+
+Typical use in a plugin::
+
+    from utic_invocation_settings import (
+        extract_envelope, decrypt_settings, TTLCache,
+    )
+
+    _settings_cache = TTLCache(ttl_seconds=300)
+    _key_cache = TTLCache(ttl_seconds=3600)
+
+    def handle_invoke(body, load_private_key):
+        env = extract_envelope(body)
+        if env is None:
+            ...  # transitional: fall back to the legacy JOB_SETTINGS_FILE
+        settings = decrypt_settings(
+            env,
+            private_key_loader=load_private_key,
+            settings_cache=_settings_cache,
+            key_cache=_key_cache,
+        )
+"""
+
+from __future__ import annotations
+
+from .cache import TTLCache
+from .consumer import PrivateKeyLoader, decrypt_settings, open_envelope
+
+# NOTE: `seal_settings` (the producer helper) is intentionally NOT re-exported here. This is a
+# consumer library; producing envelopes is the Secrets Provider's job (it owns its own producer —
+# "format is the contract, not shared code"). `seal_settings` remains importable from
+# `utic_invocation_settings.crypto` for tests / dev tooling.
+from .crypto import compute_kid
+from .envelope import (
+    CONTENT_ALG,
+    FORMAT,
+    KEY_ALG,
+    ContentEncryption,
+    Envelope,
+    KeyEncryption,
+    protected_aad,
+)
+from .errors import (
+    DecryptionError,
+    IntegrityError,
+    InvocationSettingsError,
+    KeyNotFoundError,
+    MalformedEnvelopeError,
+    UnsupportedFormatError,
+)
+from .invoke import RESERVED_ENVELOPE_KEY, extract_envelope
+
+__all__ = [
+    "CONTENT_ALG",
+    "ContentEncryption",
+    "DecryptionError",
+    "Envelope",
+    "FORMAT",
+    "IntegrityError",
+    "InvocationSettingsError",
+    "KEY_ALG",
+    "KeyEncryption",
+    "KeyNotFoundError",
+    "MalformedEnvelopeError",
+    "PrivateKeyLoader",
+    "RESERVED_ENVELOPE_KEY",
+    "TTLCache",
+    "UnsupportedFormatError",
+    "compute_kid",
+    "decrypt_settings",
+    "extract_envelope",
+    "open_envelope",
+    "protected_aad",
+]

utic_invocation_settings/_canonical.py

@@ -0,0 +1,40 @@
+"""Canonical JSON + digest helpers. These MUST match the wire contract (envelope-contract-v1.md)
+byte-for-byte, because the producer and consumer both derive digests and GCM AAD from them."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any
+
+
+def canonical_json_bytes(obj: Any) -> bytes:
+    """Deterministic JSON: sorted keys, no whitespace, UTF-8, non-ASCII preserved.
+
+    This is the exact serialization the ``settings_digest`` is taken over and the exact form the
+    plaintext is encrypted from, so producer and consumer agree bit-for-bit.
+    """
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+        "utf-8"
+    )
+
+
+def sha256_oci(data: bytes) -> str:
+    """OCI-style content digest: ``sha256:<lowercase-hex>``."""
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def b64encode(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def b64decode(data: str) -> bytes:
+    # validate=True rejects non-alphabet characters instead of silently discarding them, so a
+    # tampered/corrupt envelope field fails closed here rather than sliding into decrypt.
+    return base64.b64decode(data, validate=True)
+
+
+def b64url_unpadded(data: bytes) -> str:
+    """Unpadded base64url, per RFC 7516 (used for the ``kid``)."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")

utic_invocation_settings/cache.py

@@ -0,0 +1,64 @@
+"""A small thread-safe TTL cache.
+
+Two instances are typically used (see ``consumer``): decrypted settings keyed by a full-envelope
+fingerprint, and unwrapped AES keys keyed by recipient ``kid`` plus ``encryption_key_digest``.
+Both keys are derived from public envelope metadata; neither exposes plaintext.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable
+
+
+class TTLCache:
+    def __init__(
+        self,
+        *,
+        ttl_seconds: float,
+        maxsize: int = 256,
+        time_fn: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be positive")
+        if maxsize <= 0:
+            raise ValueError("maxsize must be positive")
+        self._ttl = ttl_seconds
+        self._maxsize = maxsize
+        self._time = time_fn
+        self._lock = threading.Lock()
+        # key -> (expires_at, value)
+        self._store: dict[str, tuple[float, Any]] = {}
+
+    def get(self, key: str) -> Any | None:
+        now = self._time()
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            expires_at, value = entry
+            if expires_at <= now:
+                self._store.pop(key, None)
+                return None
+            return value
+
+    def set(self, key: str, value: Any) -> None:
+        now = self._time()
+        with self._lock:
+            # Evict expired entries, then the oldest-expiring if still over capacity.
+            if len(self._store) >= self._maxsize and key not in self._store:
+                self._evict_locked(now)
+            self._store[key] = (now + self._ttl, value)
+
+    def _evict_locked(self, now: float) -> None:
+        expired = [k for k, (exp, _) in self._store.items() if exp <= now]
+        for k in expired:
+            self._store.pop(k, None)
+        while len(self._store) >= self._maxsize:
+            oldest = min(self._store, key=lambda k: self._store[k][0])
+            self._store.pop(oldest, None)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._store.clear()

utic_invocation_settings/consumer.py

@@ -0,0 +1,123 @@
+"""Consumer orchestration: turn an :class:`Envelope` into plaintext settings, with caching.
+
+This is the plugin-facing entry point. The decrypt order follows envelope-contract-v1.md:
+authenticated-envelope cache -> recipient-scoped AES-key cache -> RSA unwrap -> GCM open -> digest
+verify -> parse -> cache.
+The plugin supplies a ``private_key_loader`` that maps a ``kid`` to its RSA private key (loaded from
+whatever secret mount the deployment provides) — the library stays deployment-agnostic.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from typing import Any, Callable
+
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from ._canonical import b64decode, sha256_oci
+from .cache import TTLCache
+from .crypto import _AES256_KEY_BYTES, _GCM_NONCE_BYTES, aesgcm_open, unwrap_aes_key
+from .envelope import FORMAT, Envelope, envelope_fingerprint, protected_aad
+from .errors import (
+    DecryptionError,
+    IntegrityError,
+    KeyNotFoundError,
+    MalformedEnvelopeError,
+    UnsupportedFormatError,
+)
+
+# kid -> RSA private key (or None if this process holds no key for that kid).
+PrivateKeyLoader = Callable[[str], "rsa.RSAPrivateKey | None"]
+
+
+def open_envelope(
+    envelope: Envelope,
+    *,
+    private_key_loader: PrivateKeyLoader,
+    key_cache: TTLCache | None = None,
+) -> bytes:
+    """Decrypt an envelope to the raw plaintext settings bytes. Fails closed on any problem."""
+    if envelope.format != FORMAT:
+        raise UnsupportedFormatError(f"unsupported envelope format: {envelope.format!r}")
+
+    kid = envelope.key_encryption.kid
+    key_digest = envelope.key_encryption.encryption_key_digest
+    # The CEK digest is identical when a producer wraps one CEK for multiple recipients. Scope the
+    # cache to the recipient so possession of key A never authorizes an envelope addressed to key B.
+    key_cache_key = f"{kid}|{key_digest}"
+    aes_key: bytes | None = key_cache.get(key_cache_key) if key_cache is not None else None
+
+    if aes_key is None:
+        private_key = private_key_loader(kid)
+        if private_key is None:
+            raise KeyNotFoundError(f"no private key for kid {kid!r}")
+        try:
+            aes_key = unwrap_aes_key(private_key, b64decode(envelope.key_encryption.encrypted_key))
+        except Exception as exc:  # RSA unwrap failure — do not leak detail
+            raise DecryptionError("failed to unwrap the content-encryption key") from exc
+        if sha256_oci(aes_key) != key_digest:
+            raise IntegrityError("unwrapped AES key does not match encryption_key_digest")
+        if key_cache is not None:
+            key_cache.set(key_cache_key, aes_key)
+
+    # AESGCM silently accepts 16/24-byte keys and any nonce length, so enforce the A256GCM
+    # parameters the envelope header promises before decrypting with them.
+    if len(aes_key) != _AES256_KEY_BYTES:
+        raise MalformedEnvelopeError(
+            f"content-encryption key is {len(aes_key)} bytes; A256GCM requires "
+            f"{_AES256_KEY_BYTES}"
+        )
+
+    try:
+        iv = b64decode(envelope.content_encryption.iv)
+        ciphertext_with_tag = b64decode(envelope.content_encryption.ciphertext)
+    except Exception as exc:  # invalid base64 — fail closed without detail
+        raise DecryptionError("failed to authenticate/decrypt settings ciphertext") from exc
+    if len(iv) != _GCM_NONCE_BYTES:
+        raise MalformedEnvelopeError(
+            f"iv is {len(iv)} bytes; AES-GCM requires exactly {_GCM_NONCE_BYTES}"
+        )
+
+    try:
+        plaintext = aesgcm_open(aes_key, iv, ciphertext_with_tag, protected_aad(envelope))
+    except Exception as exc:  # GCM authentication failure
+        raise DecryptionError("failed to authenticate/decrypt settings ciphertext") from exc
+
+    if sha256_oci(plaintext) != envelope.settings_digest:
+        raise IntegrityError("decrypted settings do not match settings_digest")
+    return plaintext
+
+
+def decrypt_settings(
+    envelope: Envelope,
+    *,
+    private_key_loader: PrivateKeyLoader,
+    settings_cache: TTLCache | None = None,
+    key_cache: TTLCache | None = None,
+) -> dict[str, Any]:
+    """Decrypt + parse settings, using authenticated caches when provided.
+
+    A cached value is deep-copied on the way out so callers cannot mutate the cache.
+    """
+    fingerprint = envelope_fingerprint(envelope)
+    if settings_cache is not None:
+        cached = settings_cache.get(fingerprint)
+        if cached is not None:
+            return copy.deepcopy(cached)
+
+    plaintext = open_envelope(envelope, private_key_loader=private_key_loader, key_cache=key_cache)
+    # Normalize decoded plaintext into the declared dict[str, Any] contract; fail closed on
+    # malformed JSON or a non-object payload. `plaintext` is bytes, so invalid UTF-8 surfaces as
+    # UnicodeDecodeError from json.loads — both mean "not valid JSON". `from None` so no
+    # plaintext-bearing detail leaks.
+    try:
+        settings = json.loads(plaintext)
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        raise IntegrityError("decrypted settings are not valid JSON") from None
+    if not isinstance(settings, dict):
+        raise IntegrityError("decrypted settings are not a JSON object")
+
+    if settings_cache is not None:
+        settings_cache.set(fingerprint, copy.deepcopy(settings))
+    return settings

utic_invocation_settings/crypto.py

@@ -0,0 +1,98 @@
+"""Crypto primitives, built directly on ``cryptography`` (no private deps).
+
+AES-256-GCM content encryption + RSA-OAEP-256 key wrap, exactly as frozen in
+envelope-contract-v1.md. ``seal_settings`` is the producer helper (used by tests and available to an
+internal producer that prefers to import rather than duplicate); ``open_bytes`` is the raw consumer.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from ._canonical import b64decode, b64encode, b64url_unpadded, canonical_json_bytes, sha256_oci
+from .envelope import (
+    CONTENT_ALG,
+    FORMAT,
+    KEY_ALG,
+    ContentEncryption,
+    Envelope,
+    KeyEncryption,
+    protected_aad,
+)
+
+_AES256_KEY_BYTES = 32
+_GCM_NONCE_BYTES = 12
+_OAEP = padding.OAEP(
+    mgf=padding.MGF1(algorithm=hashes.SHA256()),
+    algorithm=hashes.SHA256(),
+    label=None,
+)
+
+
+def compute_kid(public_key: rsa.RSAPublicKey) -> str:
+    """RFC 7516-style key id: unpadded base64url of SHA-256 over the DER SPKI."""
+    spki = public_key.public_bytes(
+        encoding=serialization.Encoding.DER,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return b64url_unpadded(hashlib.sha256(spki).digest())
+
+
+def unwrap_aes_key(private_key: rsa.RSAPrivateKey, encrypted_key: bytes) -> bytes:
+    """RSA-OAEP-256 unwrap of the AES key."""
+    return private_key.decrypt(encrypted_key, _OAEP)
+
+
+def aesgcm_open(key: bytes, iv: bytes, ciphertext_with_tag: bytes, aad: bytes) -> bytes:
+    """AES-256-GCM decrypt. Raises on authentication failure (tampered ciphertext/tag/aad)."""
+    return AESGCM(key).decrypt(iv, ciphertext_with_tag, aad)
+
+
+def seal_settings(
+    settings: Any,
+    recipient_public_key: rsa.RSAPublicKey,
+    *,
+    aes_key: bytes | None = None,
+    iv: bytes | None = None,
+) -> Envelope:
+    """Producer helper: build a v1 envelope for ``settings`` sealed to ``recipient_public_key``.
+
+    ``aes_key``/``iv`` are injectable for deterministic test vectors; otherwise fresh-random.
+    """
+    plaintext = canonical_json_bytes(settings)
+    aes_key = aes_key if aes_key is not None else AESGCM.generate_key(bit_length=256)
+    iv = iv if iv is not None else os.urandom(_GCM_NONCE_BYTES)
+    # Reject downgraded/injected material: AESGCM silently accepts 16/24-byte keys and any nonce
+    # length, which would produce an envelope whose A256GCM header lies about the cipher strength.
+    if len(aes_key) != _AES256_KEY_BYTES:
+        raise ValueError("aes_key must be 32 bytes (AES-256) to match the A256GCM envelope header")
+    if len(iv) != _GCM_NONCE_BYTES:
+        raise ValueError(f"iv must be exactly {_GCM_NONCE_BYTES} bytes for AES-GCM")
+    kid = compute_kid(recipient_public_key)
+
+    # AAD depends only on the protected header, all known pre-encryption.
+    aad = canonical_json_bytes({"cea": CONTENT_ALG, "format": FORMAT, "kea": KEY_ALG, "kid": kid})
+    ciphertext_with_tag = AESGCM(aes_key).encrypt(iv, plaintext, aad)
+    encrypted_key = recipient_public_key.encrypt(aes_key, _OAEP)
+
+    return Envelope(
+        format=FORMAT,
+        settings_digest=sha256_oci(plaintext),
+        key_encryption=KeyEncryption(
+            alg=KEY_ALG,
+            kid=kid,
+            encryption_key_digest=sha256_oci(aes_key),
+            encrypted_key=b64encode(encrypted_key),
+        ),
+        content_encryption=ContentEncryption(
+            alg=CONTENT_ALG,
+            iv=b64encode(iv),
+            ciphertext=b64encode(ciphertext_with_tag),
+        ),
+    )

utic_invocation_settings/devtools/make_vector.py

@@ -0,0 +1,54 @@
+"""Generate an example envelope vector for cross-implementation checks.
+
+``build_example_vector`` seals a small settings object to a fresh keypair and returns the
+private-key PEM, the envelope, and the original settings. ``python -m
+utic_invocation_settings.devtools.make_vector`` prints a JSON blob a second (e.g. non-Python)
+implementation can decrypt to confirm wire compatibility. RSA keygen is not deterministic, so this
+is an *example* vector, not a frozen one; freeze by checking in a specific output when needed.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from ..crypto import seal_settings
+from ..envelope import Envelope
+
+_EXAMPLE_SETTINGS: dict[str, Any] = {
+    "job_metadata": {"job_id": "job-123", "tenant_id": "tenant-abc"},
+    "connector": {"kind": "example", "base_url": "https://example.invalid"},
+    "secret_ref": "sha256:deadbeef",
+}
+
+
+def build_example_vector() -> tuple[bytes, Envelope, dict[str, Any]]:
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=3072)
+    envelope = seal_settings(_EXAMPLE_SETTINGS, private_key.public_key())
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    return private_pem, envelope, dict(_EXAMPLE_SETTINGS)
+
+
+def main() -> None:
+    private_pem, envelope, settings = build_example_vector()
+    print(
+        json.dumps(
+            {
+                "private_key_pem": private_pem.decode("ascii"),
+                "envelope": envelope.model_dump(mode="json"),
+                "expected_settings": settings,
+            },
+            indent=2,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

utic_invocation_settings/envelope.py

@@ -0,0 +1,80 @@
+"""The envelope wire model (envelope-contract-v1.md). Pydantic models mirror the frozen JSON shape;
+``protected_aad`` derives the GCM associated data binding ciphertext to its format + recipient."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from ._canonical import canonical_json_bytes, sha256_oci
+
+FORMAT = "u10d.invocation-settings.v1"
+KEY_ALG = "RSA-OAEP-256"
+CONTENT_ALG = "A256GCM"
+
+
+# The crypto submodels have a fixed shape within a `format` version — any structural change is a
+# new format (a coordinated producer+consumer change), so forbidding unknown fields here fails fast
+# on producer/client drift without costing forward-compat.
+class KeyEncryption(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    alg: Literal["RSA-OAEP-256"]
+    kid: str
+    encryption_key_digest: str
+    encrypted_key: str
+
+
+class ContentEncryption(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    alg: Literal["A256GCM"]
+    iv: str
+    ciphertext: str
+
+
+# NOTE: the top-level Envelope stays lenient (no extra="forbid") on purpose — the v1 wire contract
+# explicitly permits ADDITIVE optional plaintext fields within a format version (that is how
+# `expires_at`/`credential_version` were introduced). Forbidding extras here would break that
+# forward-compatibility. Structural changes to the crypto envelope get a `format` bump instead.
+class Envelope(BaseModel):
+    format: str
+    settings_digest: str
+    key_encryption: KeyEncryption
+    content_encryption: ContentEncryption
+    # Plaintext, optional. `expires_at` drives the OAuth settings-refresher; `credential_version`
+    # lets a consumer tell it received newer material.
+    expires_at: datetime | None = None
+    credential_version: int | None = None
+
+
+def envelope_fingerprint(envelope: Envelope) -> str:
+    """Return a cache key for this exact authenticated message.
+
+    ``settings_digest`` identifies the plaintext and is supplied by the sender, so it cannot
+    authorize a decrypted-settings cache hit on its own. The fingerprint covers every field that
+    participates in recipient selection or authenticated decryption. The two optional advisory
+    fields are excluded because v1 does not authenticate them.
+    """
+    return sha256_oci(
+        canonical_json_bytes(
+            envelope.model_dump(exclude={"expires_at", "credential_version"}, mode="json")
+        )
+    )
+
+
+def protected_aad(envelope: Envelope) -> bytes:
+    """GCM associated data = compact canonical JSON of the protected header.
+
+    Binding format + algs + kid means a swapped or relabeled envelope fails authentication.
+    """
+    return canonical_json_bytes(
+        {
+            "cea": envelope.content_encryption.alg,
+            "format": envelope.format,
+            "kea": envelope.key_encryption.alg,
+            "kid": envelope.key_encryption.kid,
+        }
+    )

utic_invocation_settings/errors.py

@@ -0,0 +1,28 @@
+"""Error taxonomy. Every failure fails closed — no partial/at-risk plaintext is ever returned."""
+
+from __future__ import annotations
+
+
+class InvocationSettingsError(Exception):
+    """Base class for all envelope/decrypt errors."""
+
+
+class UnsupportedFormatError(InvocationSettingsError):
+    """The envelope ``format`` is not one this library understands."""
+
+
+class KeyNotFoundError(InvocationSettingsError):
+    """No private key was available for the envelope's ``kid``."""
+
+
+class DecryptionError(InvocationSettingsError):
+    """RSA unwrap or AES-GCM open failed (includes GCM authentication-tag failure)."""
+
+
+class IntegrityError(InvocationSettingsError):
+    """A digest did not match the decrypted material (settings or AES key)."""
+
+
+class MalformedEnvelopeError(InvocationSettingsError):
+    """The supplied value is not a valid envelope: wrong shape, or crypto material (key/IV sizes)
+    that violates the frozen v1 contract."""

utic_invocation_settings/invoke.py

@@ -0,0 +1,51 @@
+"""Wrapper-independent extraction of the envelope from a plugin ``/invoke`` request.
+
+Plugins pull the envelope out of a reserved, out-of-schema field of the invoke body themselves,
+rather than declaring it as a handler parameter — so nothing here depends on the ``etl-uvicorn``
+schema generator, and removing that wrapper later changes nothing about settings delivery. See
+cellular-dataplane/prompts/ERA-01-Settings.md (decision 7).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+import pydantic
+
+from .envelope import Envelope
+from .errors import MalformedEnvelopeError
+
+# Reserved key carrying the settings envelope in the invoke request body.
+RESERVED_ENVELOPE_KEY = "invocation_settings"
+
+# Sentinel distinguishing a truly-absent reserved key from one present with a ``None`` value.
+_ABSENT = object()
+
+
+def extract_envelope(payload: Mapping[str, Any]) -> Envelope | None:
+    """Return the :class:`Envelope` from ``payload[RESERVED_ENVELOPE_KEY]``.
+
+    Returns ``None`` only when the reserved key is **absent** — the transitional signal to fall
+    back to the legacy ``JOB_SETTINGS_FILE`` path. A present key fails closed: a ``null`` (or
+    otherwise non-envelope) value is treated as a malformed envelope and raises
+    ``MalformedEnvelopeError`` rather than silently degrading to the legacy path. This keeps
+    "no envelope was sent" and "an envelope was sent but is invalid" distinct.
+
+    Accepts an already-parsed ``Envelope`` or a raw mapping (which is validated).
+    """
+    raw = payload.get(RESERVED_ENVELOPE_KEY, _ABSENT)
+    if raw is _ABSENT:
+        return None
+    if isinstance(raw, Envelope):
+        return raw
+    # Present-but-null / present-but-not-a-mapping flows here and fails closed via validation.
+    try:
+        return Envelope.model_validate(raw)
+    except pydantic.ValidationError as exc:
+        # `from None` so the verbose pydantic error tree doesn't leak into the domain-error
+        # boundary — mirrors how `decrypt_settings` translates low-level failures. A short
+        # summary (count + first error) is enough signal without dumping the full tree.
+        first_error = exc.errors()[0]["msg"]
+        raise MalformedEnvelopeError(
+            f"invalid envelope: {exc.error_count()} validation error(s), first: {first_error}"
+        ) from None

utic_invocation_settings-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: utic-invocation-settings
+Version: 0.1.0
+Summary: Public library for consuming encrypted Unstructured plugin invocation settings (AES-256-GCM + RSA-OAEP-256 envelope, decrypt + cache).
+Requires-Python: >=3.11
+Requires-Dist: cryptography<47.0.0,>=43.0.0
+Requires-Dist: pydantic<3.0.0,>=2.12.5
+Description-Content-Type: text/markdown
+
+# utic-invocation-settings
+
+Public library for **consuming encrypted Unstructured plugin invocation settings** — the plugin-side
+half of the cellular-dataplane "settings in the invoke payload" design. It reads the v1 settings
+envelope (RSA-OAEP-256-wrapped **AES-256-GCM**), decrypts **inside the plugin** at invoke time, and
+caches only previously authenticated envelopes.
+
+It is deliberately **self-contained on `cryptography` + `pydantic`** — no dependency on any
+private-feed package — so it can be published to public PyPI and imported by external plugin authors.
+
+## Why
+
+Under the cellular dataplane, a shared pod may serve multiple tenants, so a plugin identity decrypts
+settings routed to that plugin rather than a shared service handing out plaintext. Settings arrive as an
+opaque ciphertext envelope; this library turns that envelope into a plain settings object, verifying
+integrity and never logging secrets.
+
+The wire format is frozen in `cellular-dataplane/docs/envelope-contract-v1.md`. The producer
+(Secrets Provider / operator) emits exactly that shape; this library is the reference consumer.
+
+## Usage
+
+```python
+from utic_invocation_settings import extract_envelope, decrypt_settings, TTLCache
+
+_settings_cache = TTLCache(ttl_seconds=300)     # keyed by full-envelope fingerprint
+_key_cache = TTLCache(ttl_seconds=3600)         # keyed by recipient + encryption-key digest
+
+def load_private_key(kid: str):
+    # Load the RSA private key for this plugin identity's certificate from the mounted secret.
+    ...
+
+def on_invoke(body: dict):
+    env = extract_envelope(body)
+    if env is None:
+        return load_legacy_job_settings_file()   # transitional dual-path
+    return decrypt_settings(
+        env,
+        private_key_loader=load_private_key,
+        settings_cache=_settings_cache,
+        key_cache=_key_cache,
+    )
+```
+
+Every failure (unknown format, missing key, RSA/GCM failure, digest mismatch) raises a subclass of
+`InvocationSettingsError` — it never returns partial or unverified plaintext.
+
+## Develop
+
+```bash
+make install     # uv sync
+make test        # unit tests + coverage
+make check       # ruff
+```
+
+**Note:** published to public PyPI on merge to main (see repo README).

utic_invocation_settings-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+utic_invocation_settings/__init__.py,sha256=euJ7WEnA8LGJA0X1oCMrbph1lPZg82vs6TpCCiHZWj0,2293
+utic_invocation_settings/_canonical.py,sha256=bOmbWg--WdoecJg2QFGHMjPNvnLTELOSclBS2kFfHSI,1418
+utic_invocation_settings/cache.py,sha256=fqMwWDx_Jv6dDj4gJRid6G66NqfqKkeQk4nTzBZ6YjA,2153
+utic_invocation_settings/consumer.py,sha256=ZLrbi1DbKy2eTGsADR4S06kFEDKRFXvxdvzwFfXGNZM,5333
+utic_invocation_settings/crypto.py,sha256=MyPDiZtA-xRpFy5Exy846DnS2aperrPdg4ogSHrnslw,3674
+utic_invocation_settings/envelope.py,sha256=bJOyxssgXRwmHK69cl0IjDuS3E5_Jv_kWcXwA2xXFcA,2942
+utic_invocation_settings/errors.py,sha256=ANnrx8xAEn8rLa4nzmZJCvKuCQFiwYJcTVUJK9zWnu4,945
+utic_invocation_settings/invoke.py,sha256=2QYKvD1gjfU3GutVspBQeAJX9yFOHsseHYz_0DmanIk,2333
+utic_invocation_settings/devtools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+utic_invocation_settings/devtools/make_vector.py,sha256=Hf_6nRgbU_VEkvzfIrx-H1M6LkInsfYIVs2BwuUjKwE,1890
+utic_invocation_settings-0.1.0.dist-info/METADATA,sha256=RYc07q4yYTDtSS91RNqeRmQvJGuSzdrNiK5dKRo8IiI,2587
+utic_invocation_settings-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+utic_invocation_settings-0.1.0.dist-info/RECORD,,

utic_invocation_settings-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any